1. Архитектура и обязательные разделы файла SKILL.md

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

Перед созданием навыка обязательно изучите глобальный файл правил репозитория (AGENTS.md или CLAUDE.md). Эти документы служат единственным источником истины для критических правил безопасности и локальных команд. Задача навыка — обучить агента последовательности действий, ссылаясь на системные правила, а не дублируя их.

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). Оба рантайма поддерживают спецификацию Agent Skills, но ожидают найти файлы в разных директориях.

Пути размещения файлов навыков для рантаймов 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, и наоборот. Всегда поддерживайте актуальность файлов в обоих каталогах или настраивайте символические ссылки.

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. Стратегии рефакторинга: когда разделять, а когда объединять навыки

Правильный баланс между дроблением и укрупнением навыков обеспечивает долгосрочную стабильность системы.

Совет

В большинстве спорных ситуаций правильным решением является разделение. Попытка создать «универсальный навык для всего бэкенда» неизбежно приводит к галлюцинациям модели.

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 (Контроль актуальности): Сверьте команды и пути с текущими версиями зависимостей и структурой проекта.

8. Анатомия антипаттернов: как отличить рабочий навык от черновика

Сравнение типовых дефектов помогает быстро провести самопроверку перед коммитом.

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

9. Предотвращение подводных камней: отказ от дублирования AGENTS.md

Наиболее распространенная ошибка — копирование глобальных правил проекта (запрет длинных тире, стили кнопок в CSS или правила работы с ветками) внутрь SKILL.md.

text

Почему дублирование разрушает систему: 1. Разработчик копирует правило из AGENTS.md в SKILL.md. 2. Спустя месяц системное правило в AGENTS.md обновляется. 3. В SKILL.md остается устаревшая формулировка. 4. Агент получает взаимоисключающие сигналы и начинает галлюцинировать.

Безопасное добавление файлов в Git

В процедурах коммита внутри навыков всегда проверяйте существование файлов перед их добавлением в индекс:

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 без дублирования текста.