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

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

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

mermaid

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

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

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

Примітка

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

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

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

Шляхи розміщення файлів навичок для рантаймів Codex та Claude Code Збільшити

Шляхи розміщення файлів навичок для рантаймів Codex та Claude Code

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

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

Важливо

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

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

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

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

mermaid

flowchart LR Draft["Чорновий Skill (Розмитий опис, копії правил, абстрактні кроки)"] --> 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. Стратегії рефакторингу: коли ділити, а коли об’єднувати скіли

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

Порада

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

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

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

Матриця збірки та розміщення різних типів навичок у системі Збільшити

Матриця збірки та розміщення різних типів навичок у системі

Тип навички	Де редагується вихідний код	Конвеєр збірки	Призначення
Скіл репозиторію (приватний)	`.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`	Не потрібен	Легковажні базові навички для каталогу платформи

Увага

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

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

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

mermaid

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

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

Trigger Probe (Перевірка тригера): Сформулюйте 3 запити, які повинні активувати навичку, та 2 запити, які повинні бути відхилені. Перевірте, чи опис у frontmatter чітко розмежовує ці випадки.
Procedure Walk-Through (Натурний прогін): Пройдіть кожен крок вручну на живому стенді. Якщо для виконання кроку вам не вистачило ввідних даних — у навичці пропущено важливу умову.
Pitfall Audit (Аудит збоїв): Переконайтеся, що кожна описана пастка реально траплялася на практиці, а запропонований спосіб усунення є робочим.
Scope Test (Тест фокусу): Сформулюйте призначення скіла одним простим реченням. Якщо речення вимагає сполучника «а також» — навичку слід розділити на дві частини.
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 без прямого копіювання тексту.