# Как писать и тестировать паттерны для SKILL.md: полное инженерное руководство > Профессиональное руководство по разработке навыков для ИИ-агентов: 4 обязательных раздела SKILL.md, синхронизация Codex и Claude Code, паттерны компоновки, 5 обязательных тестов и предотвращение регрессий. ## 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 ``` ### Подробный разбор обязательных компонентов 1. **Description во Frontmatter:** Единственный блок текста, который агент считывает до принятия решения о вызове навыка. Его необходимо формулировать как предикатное условие запуска («Используй, когда...»), а не как абстрактную тему. 2. **When to trigger (Когда активировать):** Развернутый перечень прямых запросов, ошибок в терминале или операций в Git, при которых навык обязан сработать. 3. **Procedure (Регламентированная процедура):** Нумерованный алгоритм действий с проверенными командами и существующими путями к файлам. 4. **Pitfalls (Подводные камни):** Каталог реальных сбоев. Каждая запись строится по формуле: *Ошибочное действие* → *Точный технический сбой* → *Рецепт исправления*. > [!NOTE] > Если процедура завершается деплоем или релизом, не дублируйте пайплайн внутри навыка. Завершайте шаг указанием: «Запусти навык ship-pipeline». --- ## 2. Структура размещения: синхронизация между Codex и Claude Code В современных рабочих процессах инженеры часто используют несколько агентских клиентов (например, **OpenAI Codex** в консоли или IDE и **Claude Code**). Оба рантайма поддерживают спецификацию Agent Skills, но ожидают найти файлы в разных директориях. ![Пути размещения файлов навыков для рантаймов 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//SKILL.md` | Считывается Codex при сканировании локальных инструментов | | **Anthropic Claude Code** | `.claude/skills//SKILL.md` | Считывается Claude Code при инициализации сессии | > [!IMPORTANT] > **Требование дуальной синхронизации:** Навык, созданный только в `.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. Стратегии рефакторинга: когда разделять, а когда объединять навыки Правильный баланс между дроблением и укрупнением навыков обеспечивает долгосрочную стабильность системы. :::tabs @tab Разделять навык - **Разные условия запуска:** Сценарии требуют противоположных настроек (например, аудит кода в режиме чтения против прямой миграции схемы БД). - **Разные контуры проекта:** Навык пытается одновременно регулировать публичный лендинг (Tailwind) и серверный бэкенд (NestJS, SQL). - **Перегрузка контекста:** Объем текста превышает 500 строк, и агент начинает пропускать промежуточные шаги. @tab Объединять навыки - **Неразрывная связь:** Два небольших навыка всегда запускаются вместе, и выполнение одного без другого бессмысленно. - **Дублирование кода:** Разделение приводит к копированию одного и того же блока проверок в два разных файла. ::: > [!TIP] > В большинстве спорных ситуаций правильным решением является **разделение**. Попытка создать «универсальный навык для всего бэкенда» неизбежно приводит к галлюцинациям модели. --- ## 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//SKILL.md` + `.claude/skills//SKILL.md` | **Не требуется** (читается напрямую) | Внутренние регламенты команды для текущего проекта | | **Публичный флагманский (многофайловый)** | `skills-source//` + метаданные в скрипте сборки | `node scripts/build-flagship-skills.mjs skills-source/` | Комплексные модульные решения с reference-файлами для маркетплейса | | **Публичный однофайловый** | `baseSkills` в `lib/library/skills.ts` | **Не требуется** | Легковесные базовые навыки для общего каталога платформы | > [!WARNING] > **Запрет ручной правки скомпилированных файлов:** Никогда не редактируйте скомпилированные артефакты флагманских навыков напрямую. Любые изменения вносятся исключительно в папку `skills-source//` с последующим запуском генератора. --- ## 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["Одобрено в продакшн"] ``` ### Детали протокола тестирования 1. **Trigger Probe (Проверка триггера):** Составьте 3 запроса, которые должны запускать навык, и 2 запроса, которые должны отклоняться. Убедитесь, что описание во frontmatter четко разделяет эти случаи. 2. **Procedure Walk-Through (Натурный прогон):** Выполните каждый шаг вручную в терминале. Если для выполнения шага вам не хватило контекста — в инструкции пропущено необходимое условие. 3. **Pitfall Audit (Аудит сбоев):** Убедитесь, что каждая описанная ошибка действительно происходила на практике, а предложенное исправление работает. 4. **Scope Test (Тест фокуса):** Сформулируйте назначение навыка одним предложением. Если формулировка требует союза «а также» — навык необходимо разделить. 5. **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//SKILL.md` и `.claude/skills//SKILL.md`. - [ ] Поле `description` начинается со слов «Используй, когда...» и задает точные условия активации. - [ ] Пройдены все 5 проверок тестового протокола (Trigger, Procedure, Pitfall, Scope, Staleness). - [ ] В тексте отсутствуют слова неопределенности («по возможности», «при необходимости»). - [ ] Все терминальные команды проверены в рабочей консоли проекта. - [ ] Глобальные правила оформлены в виде ссылок на `AGENTS.md` без дублирования текста.