SKILL.md: анатомия и вызов skill

1. Файл вместо «мы и так помним»

Когда вы впервые решаете оформить skill, соблазн велик: создать папку, бросить туда пару умных фраз, решить, что готово. Автор помнит, что имел в виду. Остальные видят папку с загадочным названием и текстом уровня «помогает с анализом задач». Банка на кухне с надписью «что-то полезное».

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

Посмотрите на разницу между размытым и инженерным описанием:

# Плохо
Этот skill помогает с задачами и делает хороший анализ.

# Лучше
Этот skill превращает входящий issue в TASK_SPEC.md
до начала реализации и не меняет код проекта.

Во втором варианте уже появляется главное: назначение и граница. Сразу видно, чего skill не делает. Для issue-analysis это критично: начни он вдруг править код — перестанет быть аналитиком и превратится в коллегу, который пришёл «просто посмотреть», а через десять минут уже переименовал полпапки.

В контексте нашего курса это особенно заметно на связке Workflow Kit и Commerce OS. Skill живёт в отдельном репозитории Workflow Kit, а применяется к задачам Commerce OS — значит, описание должно быть ясным настолько, чтобы skill переносить, ревьюить и переиспользовать. Здесь SKILL.md становится не украшением, а контрактом.

2. Две части SKILL.md

Когда вы открываете SKILL.md, важно не пугаться объёма и не пытаться запомнить всё как таблицу умножения. Анатомия простая: верхний блок метаданных (часто оформляется как frontmatter) и markdown-тело с инструкциями. Frontmatter — это YAML-блок между тремя дефисами в начале файла, краткое машинно-читаемое описание. Тело объясняет логику человеческим языком.

flowchart TD
    A[SKILL.md] --> B[Frontmatter
метаданные и ограничения]
    A --> C[Body
инструкция и контракт результата]
    B --> D[name / description / when_to_use]
    B --> E[allowed_tools / способ вызова]
    C --> F[шаги работы]
    C --> G[что вернуть]
    C --> H[чего не делать]

Полезно держать в голове такую простую таблицу:

Минимальный каркас выглядит так:

---
name: issue-analysis
description: Превращает входящий issue в TASK_SPEC.md
when_to_use: Когда задачу нужно сначала проанализировать, а не сразу реализовывать
---

## Цель
Подготовить черновик task spec без изменений кода.

Важно помнить, что точные названия полей зависят от версии Claude Code. Меня интересует не священный синтаксис, а логика структуры. Понимание, что skill имеет метаданные и тело с контрактом, — уже стабильный навык.

На этом месте возникает естественный вопрос: окей, файл лежит в репозитории — как он вообще превращается в вызываемый workflow? Разделяйте стабильное и меняющееся:

Синтаксис может меняться, а хороший skill должен переживать смену оболочки. Точный формат сверяйте по текущим /help и документации.

3. Обязательные и опциональные поля

Когда человек впервые видит примеры SKILL.md, у него часто возникает одно из двух крайних состояний: либо опишете skill одной строкой и сбежите, либо набьёте файл всеми полями из чужого репозитория. Полезнее делить поля на базовые, полезные и продвинутые.

Теперь по сути. name — короткий и устойчивый. Не рекламный слоган. issue-analysis — хорошее имя. super-smart-issue-analyzer-for-enterprise-workflows — уже не имя, а симптом того, что автор слишком полюбил своё детище.

description — это одна короткая фраза про ценность skill. Здесь очень важно не расплываться. Сравните:

---
name: issue-analysis
description: Помогает с задачами
when_to_use: Когда нужно что-то проанализировать
---

И более рабочий вариант:

---
name: issue-analysis
description: Превращает входящий issue в TASK_SPEC.md до начала реализации
when_to_use: Когда есть баг, фича или рефакторинг, и сначала нужен план работ
---

Во втором варианте уже видно, что skill делает и когда применять. Это особенно важно для поля when_to_use. «Использовать при анализе» — ценность нулевая. Хороший when_to_use описывает триггер: ситуацию, после которой выбор skill становится естественным. Для issue-analysis это «есть входящий issue, и перед реализацией нужен task spec».

Отдельно стоит сказать про входные данные, то есть arguments. Даже если в вашей версии они оформляются иначе, идея одна: skill должен явно понимать, что ему дают на вход. Текст issue, ссылки на связанные файлы, номер тикета, краткий контекст. Без этого он ведёт себя как сотрудник, которому сказали «разберись», но забыли сообщить, в чём именно. Не можете одной фразой описать вход — skill описан недостаточно чётко.

4. Тело skill: цель, порядок, результат, запреты

После метаданных начинается самое интересное: именно здесь skill перестаёт быть ярлыком и становится процедурой. Он должен не объявить «Я — skill анализа», а провести Claude по понятной последовательности действий. Здоровое тело отвечает на четыре вопроса. Какова цель? В каком порядке работать? Что вернуть? Чего не делать ни при каких обстоятельствах? Есть эти четыре вещи — skill можно ревьюить без телепатии.

Вот короткий, но здоровый фрагмент:

## Цель
Собрать TASK_SPEC.md по шаблону проекта.

## Порядок работы
1. Прочитайте issue и связанные файлы.
2. Выделите scope, non-goals и риски.
3. Верните черновик без изменений кода.

Обратите внимание на одну важную вещь: здесь нет абстрактной философии в духе «думай глубоко и действуй профессионально» — красиво, но бесполезно. Claude полезнее от конкретного workflow: прочитай issue, найди связанные области, сформулируй scope, верни конкретный артефакт. Вот это уже инструкция.

Особенно важен блок ожидаемого результата, или, если говорить инженерно, контракт результата. Для issue-analysis мало сказать «подготовь анализ». Назовите артефакт прямо: TASK_SPEC.md, плюс список открытых вопросов по неподтверждённым данным. Тогда и человек на ревью знает, что увидит в конце.

Не менее важны ограничения — это то место, где вы не даёте skill «расползтись». Нельзя начинать реализацию. Нельзя менять код. Нельзя выдавать догадки за факты. Нельзя писать «готово», если на выходе нет структуры, похожей на TASK_SPEC.md. Без ограничений skill скатится в тот самый vibe-подход, от которого нас лечит курс.

И да, полезно держать логику предыдущих модулей: мы уже работали в evidence-first стиле. Тело skill это учитывает — ссылаясь на кодовую область, пусть привязывает утверждения к файлам, модулям и паттернам проекта, а не просто уверенно звучит.

5. Когда запускать и какие права давать

Когда контракт уже собран, следующий вопрос становится операционным: когда запускать skill и какими правами его ограничивать. Думайте не категориями «удобно / неудобно», а категориями риска.

Если skill новый, влияет на постановку задач, ещё не проверен на реальных кейсах — самый здоровый режим ручной запуск. Не делайте вид, что мы уже изобрели идеального ассистента, который сам понимает, когда вмешаться. Консервативность в инженерии недооценивают зря.

Для issue-analysis логика очень простая: это skill планирования, а не реализации. Значит, ему достаточно чтения и поиска — минимально нужные инструменты, без лишних прав. Skill, который собирает TASK_SPEC.md, не нуждается в праве править полпроекта. Это примерно как дать библиотекарю отбойный молоток — вдруг когда-нибудь пригодится, но лучше всё-таки не надо.

Концептуально верх файла может отражать это так:

---
name: issue-analysis
allowed_tools: read, grep
# запуск только вручную; точное поле зависит от версии
# редактирование файлов не разрешаем
---

Здесь важна не буквальная форма строк, а сама мысль. Планирует skill — нужны планировочные права. Анализирует — аналитические инструменты. Станет видно, что skill стабилен и команда пользуется им одинаково, — тогда расширяйте механизм вызова. Но стартовый режим максимально безопасный.

6. Сборка issue-analysis для Workflow Kit

Теперь давайте соберём наш первый нормальный skill не в вакууме, а в том самом проектном контексте, который проходит через весь курс. Минимальная версия issue-analysis — без лишних слоёв, но с понятным контрактом и безопасными правами. Напомню важную архитектурную вещь: skill живёт не внутри Commerce OS, а в отдельном репозитории Workflow Kit. Это не придирка к папкам, а инженерная граница: продуктовая кодовая база и мета-инструменты команды — разные артефакты.

Минимальная структура:

workflow-kit/
  .claude/
    skills/
      issue-analysis/
        SKILL.md
        templates/

Верхняя часть файла:

---
name: issue-analysis
description: Превращает входящий issue Commerce OS в TASK_SPEC.md
when_to_use: Когда по багу, фиче или рефакторингу сначала нужен анализ, а не реализация
allowed_tools: read, grep
---

Уже на этом этапе видно, что skill делает, где применяется и какими средствами. Дальше тело:

## Что сделать
1. Прочитать issue и связанные области проекта.
2. Выделить цель, scope, non-goals и риски.
3. Заполнить TASK_SPEC.md по шаблону.

## Что вернуть
Готовый TASK_SPEC.md и список открытых вопросов.

## Чего не делать
Не менять код и не начинать реализацию.

Теперь привяжем это к реальному примеру из Commerce OS. Допустим, пришёл issue: refund-запросы в inbox поддержки сортируются в неправильном порядке. Skill не лезет исправлять сортировку — он превращает текст задачи в инженерный артефакт:

## Цель
Исправить порядок refund-запросов в inbox поддержки.

## Область изменений
support/inbox, логика сортировки списка, связанные тесты

## Не-цели
Не менять правила эскалации и не трогать UI карточки тикета.

Вот здесь и становится видно, зачем мы так возились с анатомией SKILL.md. Хорошо описанный skill стабильно превращает сырую постановку в структуру, которую вы уже умеете читать по модулям про task spec. Он не создаёт магию, а автоматизирует знакомую дисциплину.

Именно поэтому такой skill — хороший первый артефакт Workflow Kit: не лезет в рискованные зоны, не требует внешних интеграций, не раздаёт широкие права и сразу приносит пользу. И его легко ревьюить — открыл файл, посмотрел описание, ограничения, ожидаемый результат.

7. Чтение чужого SKILL.md

Когда вы открываете чужой skill, ваша задача — не восхититься красотой markdown, а быстро понять, можно ли ему доверять. Хороший SKILL.md читается как краткий рабочий договор. Прочитали и всё ещё не понимаете, когда его вызывать и что он вернёт, — красиво, но не инженерно.

Очень помогает вот такой набор вопросов для ревью:

Если файл отвечает на эти вопросы, его уже можно использовать как командный артефакт. Не отвечает — перед вами не skill, а заготовка. Это нормально, многие первые версии такие. Главное — не притворяться, что заготовка уже зрелая.

Для issue-analysis хороший результат чтения выглядит так: за минуту понимаете, что skill берёт входящий issue, читает связанные области, собирает TASK_SPEC.md, не меняет код и работает с минимальными правами. Всё. Никакой мистики, никакого «автор наверняка что-то имел в виду». Когда артефакт не требует телепатии, он уже годится для нормальной инженерной среды.