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 является программным артефактом

Версионирование и модульность: Навык состоит из обычных файлов репозитория, отслеживается через Git и развивается по стандартным законам разработки ПО.
Разделение интерфейса и реализации: Поле description во frontmatter выступает публичным интерфейсом навыка, а тело SKILL.md и вложенные скрипты — его внутренней реализацией.
Композиционность: Навык может обращаться к внешним инструментам через MCP, запускать консольные команды и делегировать подзадачи другим навыкам или субагентам.
Уязвимость к регрессиям: Неудачно измененное описание может привести к отказу (навык перестает активироваться) или к отклонениям от инструкций при выполнении.

Примечание

Спецификация Agent Skills, предложенная Anthropic, представляет собой открытый стандарт. Навыки, оформленные по этому стандарту, совместимы не только с Claude Code, но и с другими современными инструментами автономной разработки.

2. Структура файлов и директорий: SKILL.md, скрипты и ресурсы

Навык представляет собой структурированную директорию в файловой системе, обязательным ядром которой является файл SKILL.md. В зависимости от задачи навык может включать исполняемые скрипты, справочные руководства и шаблоны.

Архитектура навыка: интерфейс, реализация, ресурсы в комплекте и внешние инструменты Збільшити

Архитектура навыка: интерфейс, реализация, ресурсы в комплекте и внешние инструменты

Уровни хранения навыков в Claude Code

Глобальные навыки (~/.claude/skills/): Доступны разработчику во всех проектах на рабочей машине. Идеально для персональных утилит, форматирования коммитов или аналитических скриптов.
Проектные навыки (.claude/skills/): Хранятся непосредственно в репозитории проекта и фиксируются в Git. Доступны всем участникам команды, гарантируя единые стандарты архитектуры и тестирования.

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_<staging>`	Запрещены подчеркивания и угловые скобки
`description`	`Generates API documentation from Express routes. Use when updating docs.`	`A tool for API`	Слишком короткое и расплывчатое описание, нет условий вызова

Внимание

Если навык должен вызываться исключительно вручную и не должен срабатывать автоматически по инициативе модели, его автоматический вызов можно отключить во 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 — Метаданные (Metadata): Имена и описания всех зарегистрированных навыков загружаются в системный контекст в начале сессии (~100 токенов на навык). Это позволяет держать в проекте десятки навыков без перегрузки контекста.
Уровень 2 — Тело файла (Body): Когда модель определяет, что задача соответствует описанию навыка, она считывает SKILL.md. Рекомендуемый размер тела — до 500 строк, чтобы не вытеснять историю текущего диалога.
Уровень 3 — Вложенные файлы и скрипты (Resources): Справочные файлы читаются только тогда, когда инструкция напрямую к ним обращается. Скрипты обычно запускаются через интерпретатор; их исходный код не попадает в контекст, возвращается только результат выполнения.

5. Формулирование description: создание надежных триггеров активации

Поскольку description служит главным триггером вероятностного сопоставления, его формулировке следует уделять особое внимание.

Правила составления эффективного описания

Только третье лицо: Формулируйте описание от третьего лица (Generates, Audits, Performs). Модель воспринимает описание как спецификацию инструмента; местоимения первого или второго лица ухудшают качество сопоставления.
Формула «Что + Когда»: Описание должно отвечать на два вопроса: какую именно операцию выполняет навык и в каких сценариях его следует запускать.
Практические термины: Включайте точные технические термины, расширения файлов и команды, которые пользователь наверняка упомянет в запросе.

6. Анатомия эталонного Skill: пошаговый разбор пайплайна release-notes

Рассмотрим архитектуру навыка автоматизации релизной документации release-notes.

Пошаговый пайплайн выполнения навыка 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 и краткий отчет в терминале.

Рекомендации по содержанию тела навыка:

Не объясняйте базовые вещи: Claude уже обладает широкими инженерными знаниями. Описывайте только специфику вашего проекта и корпоративные правила.
Глубина ссылок — один уровень: Справочные документы не должны ссылаться цепочкой на другие файлы. Все ресурсы должны быть прямо привязаны к SKILL.md.
Кроссплатформенные пути: Всегда используйте прямые слеши (/) в путях к файлам.

7. Ландшафт кастомизаций: Skills, CLAUDE.md, Slash-команды, MCP, хуки и плагины

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

Матрица механизмов кастомизации Claude Code: кто определяет запуск против силы воздействия Збільшити

Матрица механизмов кастомизации Claude Code: кто определяет запуск против силы воздействия

Механизм	Кто определяет запуск	Сила воздействия	Оптимальный сценарий использования
CLAUDE.md (Memory)	Рантайм (всегда в контексте)	Рекомендательная	Базовые правила проекта, стек технологий, команды сборки
Skill	Модель (семантически) или человек	Рекомендательная	Комплексные доменные процедуры, скрипты автоматизации
Slash-команда	Пользователь (`/команда`)	Рекомендательная	Интерактивные шаблоны промптов, вызываемые вручную
Subagent	Модель или пользователь	Изолированная	Делегирование независимой задачи в отдельное контекстное окно
MCP Tool	Модель (Tool Call)	Исполнительная	Прямая работа с внешними сервисами, базами данных и API
Hook	Рантайм (детерминированно)	Блокирующая	Жесткие проверки безопасности, запуск линтеров перед коммитом
Plugin	Пользователь (установка)	Комплексная	Пакетное распространение набора навыков, MCP и хуков для команды

Важно

Только механизмы, управляемые напрямую рантаймом (например, хуки), гарантируют безусловное выполнение и блокировку нежелательных действий. Инструкции внутри Skill остаются рекомендацией, которую модель исполняет с определенной вероятностью.

8. Skills против Hooks: баланс между рекомендациями и гарантиями рантайма

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

Жизненный цикл выполнения сессии Claude Code и точки интеграции хуков и навыков Збільшити

Жизненный цикл выполнения сессии Claude Code и точки интеграции хуков и навыков

Ключевые точки жизненного цикла

SessionStart (Хук): Срабатывает при открытии сессии. Гарантирует проверку окружения и валидацию git-ветки.
Размышление модели (Чтение Skill): Модель анализирует контекст задачи и подгружает SKILL.md.
PreToolUse (Хук, блокирующий): Выполняется непосредственно перед вызовом инструмента. Может проверить команду и заблокировать ее выполнение (код выхода 2) при нарушении правил безопасности.
PostToolUse (Хук): Выполняется сразу после завершения действия (например, автоматический запуск Prettier после изменения файла).
Stop (Хук): Срабатывает по завершении ответа модели.

text

Правило выбора инструмента: - Требуется гибкое инженерное решение и контекст ──► Создавайте SKILL - Действие должно выполняться безусловно и без исключений ──► Настраивайте HOOK

9. Процесс разработки через оценку (Evaluation-Driven Development)

Создание надежного навыка требует итеративного тестирования на реальных сценариях еще до написания финального текста инструкций.

Четыре этапа разработки навыка

Фиксация базового уровня (Baseline): Проверьте Claude Code на типовых задачах без навыка. Зафиксируйте, где модель ошибается или пропускает детали.
Формирование набора тестов (Eval Suite): Преобразуйте найденные ошибки в компактный набор тестовых запросов с ожидаемыми результатами.
Написание минимального текста (MVP): Сформулируйте минимально достаточные инструкции в SKILL.md для прохождения тестов.
Итеративная доработка: Добавляйте уточнения только в ответ на ошибки тестов, избегая раздувания объема контекста.

Рабочий процесс с двумя экземплярами модели

Экземпляр-редактор: Сессия, в которой вы совместно с 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: Обратите внимание на ссылки на скачивание внешних бинарных файлов.
Тестирование в песочнице: Первый запуск навыка выполняйте в изолированном тестовом репозитории без доступа к производственным секретам.

Как правильно создавать Skills для Claude Code: от архитектуры до тестирования