# Як писати та тестувати патерни для SKILL.md: повний інженерний гайд

> Професійний посібник з розробки навичок для ШІ-агентів: 4 обов'язкові розділи SKILL.md, синхронізація Codex і Claude Code, патерни компонування, 5 обов'язкових тестів та захист від регресій.

## 1. Архітектура та обов’язкові розділи файлу SKILL.md

Файл **SKILL.md** — це інженерний інструмент, який перетворює універсальну мовну модель на підготовленого профільного інженера для виконання одного регламентованого типу завдань. Він не дублює глобальні інваріанти проєкту, а додає до них вузьке, високоспецифічне процедурне знання.

Перш ніж створювати навичку для власного репозиторію, обов'язково вивчіть загальний конфігураційний файл правил проєкту (`AGENTS.md` або `CLAUDE.md`). Ці системні документи є абсолютним джерелом істини для критичних правил безпеки та команд збірки. Завдання самого Skill — навчити агента структурі та послідовності кроків, посилаючись на системні правила, а не копіюючи їх.

```mermaid
flowchart TD
    subgraph Structure ["Чотири обов'язкові компоненти якісного SKILL.md"]
        F["1. Description у Frontmatter<br><i>(Формулюється строго як УМОВА, а не тема)</i>"]
        T["2. When to Trigger<br><i>(Точні контекстні критерії та ключові слова)</i>"]
        P["3. Procedure<br><i>(Нумеровані кроки з реальними командами й шляхами)</i>"]
        Pit["4. Pitfalls & Anti-Patterns<br><i>(Дія + Наслідок + Точне виправлення)</i>"]
    end

    F --> T --> P --> Pit
```

### Детальний розбір обов'язкових розділів

1. **Description у Frontmatter:** Єдиний блок тексту, який агент зчитує до прийняття рішення про підвантаження навички. Його необхідно формулювати як предикатну умову активації («Використовуй, коли...»), а не абстрактну назву теми.
2. **When to trigger (Коли активувати):** Розгорнутий перелік прямих запитів, помилок у логах або операцій у git, за яких навичка зобов'язана спрацювати.
3. **Procedure (Регламентована процедура):** Нумерований алгоритм дій із точними назвами локальних команд та валідованими шляхами до файлів.
4. **Pitfalls (Підводні камені):** Каталог зафіксованих у минулому збоїв. Кожен запис будується за формулою: *Конкретна помилкова дія* → *Точний технічний збій* → *Рецепт виправлення*.

> [!NOTE]
> Якщо навичка закінчується процедурою релізу або деплою, не дублюйте сам пайплайн усередині навички. Замість цього завершуйте алгоритм вказівкою: «Запусти навичку ship-pipeline».

---

## 2. Структура розміщення: синхронізація між Codex та Claude Code

У сучасних робочих процесах розробники часто використовують одночасно кілька клієнтів (наприклад, **OpenAI Codex** у терміналі чи IDE та **Claude Code**). Обидва рантайми підтримують відкриту специфікацію навичок, але очікують побачити їх у різних каталогах проєкту.

![Шляхи розміщення файлів навичок для рантаймів Codex та Claude Code](/api/guides-media/ai_agents/testing-and-writing-skill-md-patterns-guide/images/testing-and-writing-skill-md-patterns-guide-extra-01.webp)

### Матриця шляхів для рантаймів

| Рантайм / Агент | Цільовий шлях файлу SKILL.md | Особливості виявлення |
| :--- | :--- | :--- |
| **OpenAI Codex** | `.agents/skills/<name>/SKILL.md` | Зчитується агентом Codex під час сканування локальних інструментів |
| **Anthropic Claude Code** | `.claude/skills/<name>/SKILL.md` | Зчитується Claude Code під час ініціалізації середовища сесії |

> [!IMPORTANT]
> **Вимога дуальної синхронізації:** Якщо навичка додана лише в `.claude/skills/`, вона буде повністю невидима для агентів Codex, і навпаки. Завжди створюйте та підтримуйте навичку в обох директоріях або налаштовуйте символічні посилання (symlinks).

---

## 3. Критерії готовності та валідація чорнового скіла

Перш ніж передавати навичку в командний репозиторій, оцініть її за стандартизованою інженерною шкалою якості:

- **Фальсифікованість тригера:** Ви можете назвати щонайменше 2 суміжні запити у тій самій предметній області, за яких навичка **НЕ** повинна спрацьовувати.
- **Аудит команд:** Кожна виконувана команда в процедурі існує в розділі Local Commands системного файлу `AGENTS.md`.
- **Фактологічні підводні камені:** Кожен пункт у розділі Pitfalls описує реальний інцидент із практики, а не загальне застереження на кшталт «будьте обережні».
- **Компактність контексту:** Читання тексту навички займає не більше 2–3 хвилин (до 500 рядків).
- **Нульове дублювання:** Жоден абзац не копіює загальні правила з `AGENTS.md`.

```mermaid
flowchart LR
    Draft["Чорновий Skill<br><i>(Розмитий опис, копії правил, абстрактні кроки)</i>"] --> Review{"Валідація чернетки"}
    Review -->|Виявлено недоліки| Fix["Виправлення формулювань і команд"]
    Fix --> Review
    Review -->|Всі критерії виконано| Prod["Production-Ready Skill"]
```

---

## 4. Патерни компонування: диспетчери, референси та ланцюжки

Реальні робочі процеси рідко ізольовані в межах одного файлу. Спроба описати все в єдиному монолітному `SKILL.md` призводить до роздування контексту та падіння уваги моделі. Використовуйте три перевірені архітектурні патерни:

### Патерн 1: Entry Router (Скіл-диспетчер)
Один загальний скіл виступає картою маршрутизації. Він аналізує намір користувача і делегує задачу спеціалізованим під-навичкам:

```text
Запит: "Оптимізуй продуктивність запитів до бази"
  └── db-router (Entry Router)
        ├── Спрямовує на: neon-migrations (якщо потрібні зміни структури)
        └── Спрямовує на: drizzle-index-optimizer (якщо потрібні індекси)
```

### Патерн 2: Reference-файли
Основний файл `SKILL.md` містить лише високорівневий алгоритм, а складні деталі, таблиці та граматики виносяться в директорію `references/`:

```text
.claude/skills/fleet-coordinator/
├── SKILL.md                   # Короткий пайплайн оркестрації
└── references/
    ├── agent-roles.md         # Опис спеціалізацій та матриці ролей
    └── file-ownership.md      # Правила запобігання конфліктам при записі
```

### Патерн 3: Skill Chain (Ланцюжок скілів)
Навички посилаються одна на одну як на наступний логічний етап через поле `relatedPaths` або текстову директиву:

```markdown
> Після успішного проходження валідації схеми обов'язково запусти навичку drizzle-migration-runner.
```

---

## 5. Стратегії рефакторингу: коли ділити, а коли об’єднувати скіли

Вибір між поділом та укрупненням навичок визначає стійкість вашої системи автоматизації.

:::tabs
@tab Розділяти навичку
- **Різні умови спрацювання:** Сценарії вимагають протилежних налаштувань (наприклад, аудит коду без права запису проти міграції бази даних із прямою зміною схеми).
- **Різні поверхні продукту:** Скіл намагається одночасно регулювати лендинг (дизайн-код, Tailwind) та бекенд-сервер (NestJS, SQL).
- **Перевантаження контексту:** Обсяг тексту перевищує 500 рядків, і агент починає плутати кроки.
@tab Об'єднувати навички
- **Нерозривний зв'язок:** Два крихітні скіли ніколи не викликаються окремо, і виконання одного без іншого позбавлене практичного сенсу.
- **Дублювання коду:** Розділення призводить до того, що той самий блок перевірок дублюється у двох файлах.
:::

> [!TIP]
> У 90% випадків правильним рішенням є саме **розділення**. Спроба створити «універсальний скіл для всього бекенду» неминуче перетворюється на неефективний моноліт із високим рівнем галюцинацій.

---

## 6. Контракт версіонування та конвеєр збірки прапорцевих скілів

У складних кодових базах навички діляться на три технологічні рівні за способом розповсюдження та збірки:

![Матриця збірки та розміщення різних типів навичок у системі](/api/guides-media/ai_agents/testing-and-writing-skill-md-patterns-guide/images/testing-and-writing-skill-md-patterns-guide-extra-02.webp)

| Тип навички | Де редагується вихідний код | Конвеєр збірки | Призначення |
| :--- | :--- | :--- | :--- |
| **Скіл репозиторію (приватний)** | `.agents/skills/<name>/SKILL.md` + `.claude/skills/<name>/SKILL.md` | **Не потрібен** (зчитується напряму) | Внутрішні правила команди для поточного проєкту |
| **Публічний флагманський (багатофайловий)** | `skills-source/<slug>/` + метадані в скрипті генерації | `node scripts/build-flagship-skills.mjs skills-source/` | Комплексні модульні рішення з reference-файлами для маркетплейсу |
| **Публічний однофайловий** | `baseSkills` у `lib/library/skills.ts` | **Не потрібен** | Легковажні базові навички для каталогу платформи |

> [!WARNING]
> **Заборона ручного редагування згенерованих файлів:** Ніколи не редагуйте скомпільований файл флагманського скіла вручну. Будь-які зміни вносяться виключно у вихідну папку `skills-source/<slug>/` з наступним запуском скрипта компіляції.

---

## 7. Методологія тестування: п'ять обов'язкових перевірок якості

Написання інструкції — це лише початок. Щоб навичка надійно працювала у продакшені, вона повинна послідовно пройти 5 етапів тестування:

```mermaid
flowchart TD
    T1["1. Trigger Probe<br><i>(3 позитивні + 2 негативні запити)</i>"] --> T2["2. Procedure Walk-Through<br><i>(Наскрізний запуск на реальному репозиторії)</i>"]
    T2 --> T3["3. Pitfall Audit<br><i>(Перевірка формули: Дія + Збій + Фікс)</i>"]
    T3 --> T4["4. Scope Test<br><i>(Перевірка єдиної відповідальності одним реченням)</i>"]
    T4 --> T5["5. Staleness Check<br><i>(Звірка команд і шляхів з актуальним репозиторієм)</i>"]
    T5 --> Ready["Схвалено до коміту"]
```

### Деталі тестового протоколу

1. **Trigger Probe (Перевірка тригера):** Сформулюйте 3 запити, які повинні активувати навичку, та 2 запити, які повинні бути відхилені. Перевірте, чи опис у frontmatter чітко розмежовує ці випадки.
2. **Procedure Walk-Through (Натурний прогін):** Пройдіть кожен крок вручну на живому стенді. Якщо для виконання кроку вам не вистачило ввідних даних — у навичці пропущено важливу умову.
3. **Pitfall Audit (Аудит збоїв):** Переконайтеся, що кожна описана пастка реально траплялася на практиці, а запропонований спосіб усунення є робочим.
4. **Scope Test (Тест фокусу):** Сформулюйте призначення скіла одним простим реченням. Якщо речення вимагає сполучника «а також» — навичку слід розділити на дві частини.
5. **Staleness Check (Контроль застарівання):** Звірте кожну CLI-команду з поточною конфігурацією репозиторію та актуальними версіями залежностей.

---

## 8. Анатомія антипатернів: як відрізнити робочий скіл від чернетки

Порівняння типових помилок дозволяє швидко провести самоаудит перед збереженням навички.

| Ознака | Чернетка (Draft) | Готова до продакшену навичка (Ready) |
| :--- | :--- | :--- |
| **Формулювання тригера** | Описує широку тему: *«Для роботи з базою даних»* | Задає точну умову: *«Використовуй при створенні міграцій Drizzle»* |
| **Опис кроків** | Розмиті інструкції: *«запусти лінтер за потреби»* | Чіткі команди: *«запусти npm run lint:fix»* |
| **Опис небезпек** | Загальне побажання: *«будь обережний із файлами»* | Конкретний збій: *«git add неіснуючого шляху перерве staging»* |
| **Джерела правил** | Копіює текст із `AGENTS.md` у свій вміст | Містить пряме посилання на розділ у `AGENTS.md` |
| **Синхронізація** | Створено лише в `.claude/skills/` | Синхронізовано в `.agents/` та `.claude/` одночасно |

---

## 9. Запобігання підводним каменям: відмова від дублювання AGENTS.md

Найбільш підступна пастка при розробці навичок — дублювання глобальних інваріантів проєкту (наприклад, правила відмови від довгих тире, вимоги до круглих кутів у CSS або заборона прямого пушу в main).

```text
Чому дублювання руйнує систему:
1. Інженер копіює правило з AGENTS.md у тіло SKILL.md.
2. Через місяць архітектурний комітет оновлює правило в AGENTS.md.
3. Усередині SKILL.md залишається застаріле формулювання.
4. Агент отримує два суперечливі системні сигнали і починає галюцинувати.
```

### Безпечна індексація змін у Git

Під час виконання процедур коміту всередині навичок завжди застосовуйте перевірку існування шляхів перед додаванням у staging:

```bash
# Небезпечно (якщо файл відсутній, вся команда переривається з помилкою):
git add src/generated/schema.ts src/types/db.ts

# Безпечно (додаються лише реально існуючі файли):
[ -e src/generated/schema.ts ] && git add src/generated/schema.ts
[ -e src/types/db.ts ] && git add src/types/db.ts
```

---

## 10. Підсумковий чек-лист готовності до продакшену

Перед фіксацією створеної навички в Git перевірте виконання кожного пункту:

- [ ] Навичка синхронізована в обох директоріях: `.agents/skills/<name>/SKILL.md` та `.claude/skills/<name>/SKILL.md`.
- [ ] Поле `description` починається зі слів «Використовуй, коли...» і визначає чіткі межі активації.
- [ ] Усі 5 етапів тестового протоколу (Trigger, Procedure, Pitfall, Scope, Staleness) пройдені успішно.
- [ ] У тексті відсутні фрази-маркери невизначеності («за потреби», «відповідним чином»).
- [ ] Усі консольні команди протестовані в живому терміналі проєкту.
- [ ] Глобальні інваріанти оформлені як посилання на `AGENTS.md` без прямого копіювання тексту.