# Как правильно создавать Skills для Claude Code: от архитектуры до тестирования
> Исчерпывающее инженерное руководство по разработке Skills для Claude Code: анатомия папок и SKILL.md, поэтапная загрузка (progressive disclosure), отличия от хуков и evaluation-driven подход.
## 1. Что такое Skill и почему это полноценный программный артефакт
**Skill (навык)** в Claude Code — это стандартизированный модульный пакет знаний, включающий описание рабочего процесса (workflow), набор доменных правил, процедур или исполняемых скриптов, которые ИИ-агент подгружает для решения определенного класса задач. Вместо того чтобы разработчик вручную вводил повторяющиеся инструкции в каждом новом диалоге, агент самостоятельно распознает контекст задачи и активирует нужный Skill.
Принципиальное отличие Skill от традиционного исходного кода заключается в механизме активации: решение о запуске принимает сама языковая модель на основе семантического сопоставления описания навыка с запросом пользователя. Это решение является **вероятностным**: здесь нет компилятора или статической системы типов, поэтому точность формулировок метаданных напрямую определяет, сработает ли навык в нужный момент.
```mermaid
flowchart TD
subgraph Invocation ["Активация навыка"]
Prompt["Запрос пользователя"] --> Matcher{"Семантическое сопоставление (LLM)"}
Meta["Frontmatter name + description
(~100 токенов на старте)"] --> Matcher
Matcher -->|Совпадение намерений| Load["Загрузка SKILL.md в контекст"]
Matcher -->|Нет совпадения| Normal["Стандартное выполнение без навыка"]
end
subgraph Execution ["Конвейер выполнения"]
Load --> Steps["Выполнение пошаговых инструкций"]
Steps --> Scripts["Запуск локальных скриптов (bash/python)"]
Steps --> Refs["Чтение справочных файлов (references/)"]
Scripts & Refs --> Result["Финальный артефакт / код"]
end
```
### Почему Skill является программным артефактом
1. **Версионирование и модульность:** Навык состоит из обычных файлов репозитория, отслеживается через Git и развивается по стандартным законам разработки ПО.
2. **Разделение интерфейса и реализации:** Поле `description` во frontmatter выступает публичным интерфейсом навыка, а тело `SKILL.md` и вложенные скрипты — его внутренней реализацией.
3. **Композиционность:** Навык может обращаться к внешним инструментам через MCP, запускать консольные команды и делегировать подзадачи другим навыкам или субагентам.
4. **Уязвимость к регрессиям:** Неудачно измененное описание может привести к отказу (навык перестает активироваться) или к отклонениям от инструкций при выполнении.
> [!NOTE]
> Спецификация **Agent Skills**, предложенная Anthropic, представляет собой открытый стандарт. Навыки, оформленные по этому стандарту, совместимы не только с Claude Code, но и с другими современными инструментами автономной разработки.
---
## 2. Структура файлов и директорий: SKILL.md, скрипты и ресурсы
Навык представляет собой структурированную директорию в файловой системе, обязательным ядром которой является файл `SKILL.md`. В зависимости от задачи навык может включать исполняемые скрипты, справочные руководства и шаблоны.
### Уровни хранения навыков в Claude Code
- **Глобальные навыки (`~/.claude/skills/`):** Доступны разработчику во всех проектах на рабочей машине. Идеально для персональных утилит, форматирования коммитов или аналитических скриптов.
- **Проектные навыки (`.claude/skills/`):** Хранятся непосредственно в репозитории проекта и фиксируются в Git. Доступны всем участникам команды, гарантируя единые стандарты архитектуры и тестирования.
### Рекомендуемая структура сложного навыка
```text
.claude/skills/release-notes/
├── SKILL.md # Обязательный: метаданные и инструкции
├── changelog-style.md # Ресурс: правила оформления changelog
└── scripts/
└── gather-prs.py # Исполняемый скрипт: сбор объединенных PR через API
```
Минимальный навык может состоять только из одного файла `SKILL.md`. Более масштабные рабочие процессы упаковывают в папку скрипты автоматизации и документацию, сохраняя основной файл компактным.
---
## 3. Правила оформления Frontmatter: name и description
Файл `SKILL.md` обязательно начинается с блока метаданных YAML Frontmatter. Это единственная часть навыка, которую Claude считывает при инициализации сессии для построения каталога доступных действий.
```yaml
---
name: release-notes
description: Drafts release notes from merged pull requests between two git tags. Use when cutting a release or updating the changelog.
---
```
### Формальные ограничения для name
- Длина не более **64 символов**.
- Разрешены только строчные латинские буквы, цифры и дефисы (`[a-z0-9-]`).
- Запрещены любые XML/HTML-теги и пробелы.
- Запрещено использовать зарезервированные слова (`claude`, `anthropic`).
### Формальные ограничения для description
- Обязательное непустое поле.
- Длина не более **1024 символов**.
- Запрещено использование XML-тегов.
- Должно явно описывать назначение навыка и контекстные триггеры для активации.
| Поле | Корректный пример | Недопустимый пример | Причина ошибки |
| :--- | :--- | :--- | :--- |
| `name` | `db-migrate-helper` | `Claude-DB-Helper!` | Заглавные буквы, спецсимволы и зарезервированное имя `claude` |
| `name` | `deploy-staging` | `deploy_` | Запрещены подчеркивания и угловые скобки |
| `description` | `Generates API documentation from Express routes. Use when updating docs.` | `A tool for API` | Слишком короткое и расплывчатое описание, нет условий вызова |
> [!WARNING]
> Если навык должен вызываться исключительно вручную и не должен срабатывать автоматически по инициативе модели, его автоматический вызов можно отключить во frontmatter, превратив навык в детерминированную слеш-команду.
---
## 4. Поэтапная загрузка (Progressive Disclosure) и контекстное окно
Skills не загружаются в контекстное окно модели целиком при открытии диалога. Claude Code использует принцип **поэтапной загрузки (Progressive Disclosure)**, разделенный на три уровня.
```mermaid
flowchart LR
L1["Уровень 1: Метаданные
(~100 токенов, загружается всегда)"] -->|Триггер совпадения| L2["Уровень 2: Тело SKILL.md
(~1-3k токенов, по требованию)"]
L2 -->|Ссылки в шагах| L3["Уровень 3: Ресурсы и скрипты
(0 токенов до вызова или запуска)"]
```
### Три уровня загрузки
1. **Уровень 1 — Метаданные (Metadata):** Имена и описания всех зарегистрированных навыков загружаются в системный контекст в начале сессии (~100 токенов на навык). Это позволяет держать в проекте десятки навыков без перегрузки контекста.
2. **Уровень 2 — Тело файла (Body):** Когда модель определяет, что задача соответствует описанию навыка, она считывает `SKILL.md`. Рекомендуемый размер тела — до 500 строк, чтобы не вытеснять историю текущего диалога.
3. **Уровень 3 — Вложенные файлы и скрипты (Resources):** Справочные файлы читаются только тогда, когда инструкция напрямую к ним обращается. Скрипты обычно запускаются через интерпретатор; их исходный код не попадает в контекст, возвращается только результат выполнения.
---
## 5. Формулирование description: создание надежных триггеров активации
Поскольку `description` служит главным триггером вероятностного сопоставления, его формулировке следует уделять особое внимание.
### Правила составления эффективного описания
- **Только третье лицо:** Формулируйте описание от третьего лица (`Generates`, `Audits`, `Performs`). Модель воспринимает описание как спецификацию инструмента; местоимения первого или второго лица ухудшают качество сопоставления.
- **Формула «Что + Когда»:** Описание должно отвечать на два вопроса: какую именно операцию выполняет навык и в каких сценариях его следует запускать.
- **Практические термины:** Включайте точные технические термины, расширения файлов и команды, которые пользователь наверняка упомянет в запросе.
:::tabs
@tab Неудачное описание
```yaml
---
name: release-notes
description: Handles project releases and writes updates.
---
```
*Проблема: Отсутствуют конкретные триггеры. Модель не понимает, какие файлы анализировать и когда активировать навык.*
@tab Эталонное описание
```yaml
---
name: release-notes
description: Drafts release notes from merged pull requests between two git tags. Use when cutting a release, updating the changelog, or summarizing what changed in a version.
---
```
*Преимущество: Четко указаны входные данные (git tags, pull requests) и сценарии активации (cutting a release, updating changelog).*
:::
---
## 6. Анатомия эталонного Skill: пошаговый разбор пайплайна release-notes
Рассмотрим архитектуру навыка автоматизации релизной документации `release-notes`.
### Составные части рабочего процесса
- **Входные данные:** Аргументы пользователя (диапазон тегов `v1.2.0..v1.3.0`), руководство по стилю `changelog-style.md`, скрипт `gather-prs.py`.
- **Пошаговая инструкция в `SKILL.md`:**
1. Определить диапазон тегов в Git.
2. Запустить скрипт `python scripts/gather-prs.py` для выгрузки объединенных PR.
3. Сгруппировать изменения по категориям (Features, Fixes, Performance, Breaking Changes).
4. Составить черновик в соответствии с `changelog-style.md`.
5. Записать обновление в `CHANGELOG.md` и вывести резюме.
- **Выходные артефакты:** Обновленный файл `CHANGELOG.md` и краткий отчет в терминале.
### Рекомендации по содержанию тела навыка
1. **Не объясняйте базовые вещи:** Claude уже обладает широкими инженерными знаниями. Описывайте только специфику вашего проекта и корпоративные правила.
2. **Глубина ссылок — один уровень:** Справочные документы не должны ссылаться цепочкой на другие файлы. Все ресурсы должны быть прямо привязаны к `SKILL.md`.
3. **Кроссплатформенные пути:** Всегда используйте прямые слеши (`/`) в путях к файлам.
---
## 7. Ландшафт кастомизаций: Skills, CLAUDE.md, Slash-команды, MCP, хуки и плагины
В Claude Code предусмотрено несколько инструментов управления поведением агента. Неправильный выбор механизма — частая причина ненадежной работы системы.
| Механизм | Кто определяет запуск | Сила воздействия | Оптимальный сценарий использования |
| :--- | :--- | :--- | :--- |
| **CLAUDE.md (Memory)** | Рантайм (всегда в контексте) | Рекомендательная | Базовые правила проекта, стек технологий, команды сборки |
| **Skill** | Модель (семантически) или человек | Рекомендательная | Комплексные доменные процедуры, скрипты автоматизации |
| **Slash-команда** | Пользователь (`/команда`) | Рекомендательная | Интерактивные шаблоны промптов, вызываемые вручную |
| **Subagent** | Модель или пользователь | Изолированная | Делегирование независимой задачи в отдельное контекстное окно |
| **MCP Tool** | Модель (Tool Call) | Исполнительная | Прямая работа с внешними сервисами, базами данных и API |
| **Hook** | Рантайм (детерминированно) | **Блокирующая** | Жесткие проверки безопасности, запуск линтеров перед коммитом |
| **Plugin** | Пользователь (установка) | Комплексная | Пакетное распространение набора навыков, MCP и хуков для команды |
> [!IMPORTANT]
> Только механизмы, управляемые напрямую рантаймом (например, **хуки**), гарантируют безусловное выполнение и блокировку нежелательных действий. Инструкции внутри Skill остаются рекомендацией, которую модель исполняет с определенной вероятностью.
---
## 8. Skills против Hooks: баланс между рекомендациями и гарантиями рантайма
Попытка использовать Skills для принудительного форматирования или контроля безопасности — частая ошибка. Навык подсказывает, но не может заблокировать действие. Для строгих гарантий применяются хуки.
### Ключевые точки жизненного цикла
- **SessionStart (Хук):** Срабатывает при открытии сессии. Гарантирует проверку окружения и валидацию git-ветки.
- **Размышление модели (Чтение Skill):** Модель анализирует контекст задачи и подгружает `SKILL.md`.
- **PreToolUse (Хук, блокирующий):** Выполняется непосредственно перед вызовом инструмента. Может проверить команду и заблокировать ее выполнение (код выхода 2) при нарушении правил безопасности.
- **PostToolUse (Хук):** Выполняется сразу после завершения действия (например, автоматический запуск Prettier после изменения файла).
- **Stop (Хук):** Срабатывает по завершении ответа модели.
```text
Правило выбора инструмента:
- Требуется гибкое инженерное решение и контекст ──► Создавайте SKILL
- Действие должно выполняться безусловно и без исключений ──► Настраивайте HOOK
```
---
## 9. Процесс разработки через оценку (Evaluation-Driven Development)
Создание надежного навыка требует итеративного тестирования на реальных сценариях еще до написания финального текста инструкций.
### Четыре этапа разработки навыка
1. **Фиксация базового уровня (Baseline):** Проверьте Claude Code на типовых задачах без навыка. Зафиксируйте, где модель ошибается или пропускает детали.
2. **Формирование набора тестов (Eval Suite):** Преобразуйте найденные ошибки в компактный набор тестовых запросов с ожидаемыми результатами.
3. **Написание минимального текста (MVP):** Сформулируйте минимально достаточные инструкции в `SKILL.md` для прохождения тестов.
4. **Итеративная доработка:** Добавляйте уточнения только в ответ на ошибки тестов, избегая раздувания объема контекста.
### Рабочий процесс с двумя экземплярами модели
- **Экземпляр-редактор:** Сессия, в которой вы совместно с Claude формулируете и шлифуете инструкции навыка.
- **Экземпляр-тестировщик:** Чистая сессия, где вы проверяете, срабатывает ли навык автоматически на тестовых запросах и корректен ли итоговый результат.
---
## 10. Типовые паттерны проектирования и антипаттерны при создании Skills
Практический опыт сообщества позволил выявить ряд проверенных шаблонов и типичных ошибок.
### Эффективные инженерные паттерны
- **Нумерованные детерминированные последовательности:** Сложные операции всегда оформляйте в виде упорядоченных шагов (`1. ...`, `2. ...`, `3. ...`).
- **Встроенные чек-листы валидации:** Для критических операций добавляйте чек-лист, который модель должна воспроизвести и отмечать по ходу выполнения.
- **Циклы самопроверки (Verify & Fix):** Задавайте правило: «Запустить линтер -> исправить ошибки -> повторить до чистого вывода».
- **План перед деструктивными действиями:** При пакетных изменениях требуйте предварительно составить таблицу плана и дождаться подтверждения.
### Распространенные антипаттерны
- **Паралич выбора:** Перечисление слишком большого числа альтернативных библиотек без указания варианта по умолчанию.
- **Необъявленные зависимости:** Использование CLI-утилит или пакетов без инструкций по их установке.
- **Обратные слеши в путях:** Использование путей в стиле Windows (`\`), что ломает выполнение в Linux и macOS.
- **Необъясненные константы:** Использование числовых значений без пояснения их назначения.
---
## 11. Безопасность и аудит сторонних Skills перед установкой
Любой сторонний навык представляет собой исполняемый код в вашем окружении. Поскольку Claude Code имеет доступ к файловой системе, терминалу и сети, непроверенный Skill несет серьезные риски безопасности.
### Чек-лист аудита стороннего навыка перед использованием
- [ ] **Анализ текста `SKILL.md`:** Проверьте инструкции на наличие prompt injection, попыток чтения `.env` файлов или обхода защитных механизмов.
- [ ] **Аудит папки `scripts/`:** Изучите вложенные Python и bash-скрипты на предмет подозрительных сетевых запросов.
- [ ] **Проверка внешних URL:** Обратите внимание на ссылки на скачивание внешних бинарных файлов.
- [ ] **Тестирование в песочнице:** Первый запуск навыка выполняйте в изолированном тестовом репозитории без доступа к производственным секретам.