25 марта 2026 г.

Claude Code Skills — собственные навыки для агента

Q: Где живут Skills?

В ~/.claude/skills/ (глобально), .claude/skills/ (на проект), enterprise managed settings (для организации) или в плагинах. Рабочая практика — держать skills/ в репозитории конфигов и симлинкать на ~/.claude/skills/.

Q: Какие поля обязательны в SKILL.md?

Технически только description (и его можно опустить — возьмётся первый параграф markdown). Имя берётся из имени директории. Рекомендуется явно прописывать description — это главный сигнал для авто-вызова.

Q: Можно ли отключить авто-вызов skill'а?

Да. В YAML-фронтматтере добавить disable-model-invocation: true. Skill будет работать только при явном указании /name от пользователя.

Q: Как создать первый skill?

Самый быстрый путь — установить skill-creator из официального репозитория Anthropic и попросить агента помочь. Skill-creator проведёт через Q&A и сгенерирует валидный SKILL.md. Альтернатива — написать вручную по образцу из этой страницы.

Q: Можно ли в SKILL.md подключать скрипты?

Да. Структура: my-skill/scripts/helper.py или любой другой исполняемый файл. В markdown указывается путь и условия запуска. Агент вызывает скрипт через bash/python tool. Также доступна inline ! подстановка для команд, исполняемых до загрузки skill'а.

Skills в Claude Code — переиспользуемые пакеты с инструкциями, расширяющие возможности ИИ-агента. Каждый skill — папка с обязательным SKILL.md (YAML-фронтматтер плюс markdown-инструкции) и опциональными ресурсами: скриптами, шаблонами, справочниками. Когда задача пользователя подходит под описание skill’а, агент автоматически подгружает его содержимое и работает по инструкциям. По официальной документации Claude Code, skill — способ упаковать повторяющийся workflow один раз и запускать его естественным языком. Skills следуют открытому стандарту Agent Skills, и тот же формат работает в Claude.ai, Claude Code и Claude Agent SDK.

В этом гайде разбирается, что такое skills, как они вызываются, чем отличаются от MCP-серверов и sub-agents, какие готовые skills есть у Anthropic и как написать свой первый SKILL.md.

Skills простыми словами

Skill — инструкция в файле, которую ИИ-агент применяет, когда видит подходящую задачу. Способ вынести часть знания из головы разработчика в репозиторий, чтобы команда (и Claude) работала единообразно. Документация Anthropic формулирует: skills — это «новый способ строить специализированных агентов через файлы и папки». Skill использует принцип progressive disclosure — постепенного раскрытия в трёх слоях: метаданные (name и description) всегда висят в системном промпте; тело SKILL.md подгружается, когда агент решил, что skill релевантен; вспомогательные файлы (reference.md, examples.md, скрипты) открываются только при необходимости.

Такой подход экономит контекст: длинные справочники не съедают токены, пока не нужны. Это главное практическое преимущество skill перед раздуванием CLAUDE.md: в CLAUDE.md всё висит в контексте каждой сессии, в skill — только когда триггерится.

Когда использовать skills

Создавайте skill, когда одни и те же инструкции или чек-лист копируются в чат повторно; когда в CLAUDE.md появился раздел, описывающий как делать, а не факты о проекте; когда команда устала договариваться о стиле commit-сообщений, формате PR-описаний, шаблонах тест-генерации — пора зафиксировать в коде; когда workflow повторяется в десятках сессий и переписывать его в каждом промпте дорого. Skill не нужен, если задача делается один раз или Claude и так выполняет её корректно без дополнительных правил.

Как Skills отличаются от MCP, sub-agents и slash commands

В Claude Code есть несколько механизмов расширения. По техническому разбору k21academy и полевому гайду AntStack, у каждого своя роль:

Механизм	Что это	Когда вызывается	Что даёт
Skill	Папка с `SKILL.md` и инструкциями	Авто-загрузка по описанию или `/<имя>`	Декларативные знания «как делать»
MCP-сервер	Внешний сервис с tool API	Подключается как источник tools	Доступ к внешним системам (БД, API, файлы)
Sub-agent	Специализированный агент со своим контекстом	Делегирование задачи специалисту	Изоляция контекста, особые tool-разрешения
Hook	Скрипт на событие	Авто-запуск на edit / commit / start / stop	Автоматизация по событиям
Slash command	`/<имя>` промпт-шаблон	Явный набор пользователем	Ручной шорткат

Ключевая разница в одной фразе: skills говорят «как делать», MCP даёт «инструменты, которыми делать», sub-agents — «кому поручить». Большинство продуктовых сетапов используют все три уровня.

Skills vs MCP. Skills — текстовые инструкции для агента. MCP (Model Context Protocol) — открытый протокол подключения внешних tool’ов. По статье IntuitionLabs, MCP — «USB-C для ИИ»: один протокол, разные устройства. Skills и MCP не конкурируют — работают на разных слоях. Skill может содержать инструкции о том, как использовать tool’ы из MCP-сервера.

Skills vs sub-agents. Sub-agent — отдельный агент с собственным контекстным окном, системным промптом и ограниченным набором tool’ов. Полезен, когда нужно делегировать работу специалисту — например, code reviewer’у с read-only доступом или исследовательскому агенту на более лёгкой модели. Skill можно запустить внутри sub-agent’а через context: fork в YAML-фронтматтере: специалист со своим контекстом, работающий по чёткой инструкции из skill’а.

Skills vs slash commands. Раньше slash commands жили в .claude/commands/<имя>.md как простые промпт-шаблоны. В современном Claude Code custom commands объединены со skills: файл .claude/commands/deploy.md и skill .claude/skills/deploy/SKILL.md оба создают /deploy и работают одинаково. Старые .claude/commands/ продолжают работать. Skills добавляют папку с вспомогательными файлами, фронтматтер с контролем invocation и авто-загрузку по описанию. Подробнее про другие механизмы расширения — на странице Claude Code.

Структура skill’а

По официальной документации, skill — папка с фиксированной структурой:

my-skill/
├── SKILL.md # обязательно: основные инструкции
├── reference.md # опционально: детальные API-доки
├── examples.md # опционально: примеры использования
├── scripts/ # опционально: исполняемые скрипты
│ └── helper.py
└── assets/ # опционально: ресурсы (шаблоны)
 └── template.txt

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

Где живут skills

По официальному гайду, расположение skill’а определяет, кто им может пользоваться:

Уровень	Путь	Кому доступен
Enterprise	См. managed settings	Всем пользователям организации
Personal	`~/.claude/skills/<name>/SKILL.md`	Все ваши проекты
Project	`.claude/skills/<name>/SKILL.md`	Только этот репозиторий
Plugin	`<plugin>/skills/<name>/SKILL.md`	Где плагин включён

Если skills с одним именем есть на разных уровнях — enterprise перекрывает personal, personal перекрывает project. Plugin-skills используют namespace plugin-name:skill-name и не конфликтуют с другими уровнями.

Рабочая практика: держать skills/ в git-репозитории и симлинкать ~/.claude/skills/ на него. Это даёт версионирование, code review skills и портабельность между машинами.

Live change detection и `/reload-skills`

Claude Code следит за изменениями в директориях skills. Добавление, редактирование или удаление skill’а под ~/.claude/skills/ или .claude/skills/ применяется внутри текущей сессии — без рестарта. Создание самой top-level директории требует перезапуска, чтобы агент начал её отслеживать.

Если skill не подхватился автоматически (например, добавлен через симлинк или поменялся фронтматтер на лету), доступна команда /reload-skills — она перечитывает все директории и пересобирает список доступных skills внутри текущей сессии. Полезна при разработке skill’а в одном окне Claude Code и тестовом запуске в другом — не нужно завершать сессию, достаточно дёрнуть /reload-skills после правки.

Авто-обнаружение в monorepo

Project skills загружаются из .claude/skills/ в стартовой директории и во всех родительских вплоть до корня репозитория. При работе с файлами в поддиректориях Claude Code также обнаруживает skills из вложенных .claude/skills/ — это поддерживает monorepo-сетапы, где у каждого пакета свои skills.

SKILL.md — формат файла

Файл состоит из двух частей: YAML-фронтматтер и markdown-тело.

1. YAML-фронтматтер

В самом верху, между двумя строчками ---:

---
name: my-skill
description: Generates SEO-optimized blog outline from topic and target keyword. Use when the user wants a blog outline.
---

Минимально достаточно поля description. Поле name опционально и по умолчанию берётся из имени директории.

По полному фронтматтер-референсу, основные поля:

name — отображаемое имя; дефолт — имя директории.
description — что делает skill и когда использовать, главный сигнал для авто-вызова, усечён до 1536 символов.
when_to_use — дополнительные триггерные фразы и примеры запросов.
argument-hint, arguments — подсказка и именованные аргументы ([issue-number], подстановка в тело).
disable-model-invocation: true — отключает авто-загрузку, оставляет только ручной /name.
user-invocable: false — скрывает skill из меню /, только авто.
allowed-tools / disallowed-tools — фильтры доступных tool’ов, пока skill активен.
model, effort — оверрайд модели и уровня усилия (low, medium, high, xhigh, max) до конца хода.
context: fork + agent — запустить в форкнутом sub-agent контексте.
hooks — hooks, привязанные к жизненному циклу skill’а.
paths — glob-паттерны, ограничивающие активацию определёнными файлами.
shell — bash (дефолт) или powershell для inline-команд.

Главное правило про description — это единственное, что Claude читает на этапе выбора skill’а. Описание должно содержать: что делает skill, когда его использовать, триггер-фразы из user-запроса. Плохо: Helps with marketing tasks. Хорошо: Designs automated email sequences — welcome, nurture, re-engagement, cart-abandonment. Use when the user wants to build an email funnel.

2. Markdown-инструкции

После закрывающего --- идёт обычный markdown с инструкциями для агента:

# How to generate a blog outline

When the user asks for a blog outline:

1. Ask for the topic and primary keyword if not provided
2. Suggest 4–6 H2 sections matching user intent
3. For each H2 — propose 2–3 H3 subsections
4. Return as markdown checklist

Markdown может быть и короткой запиской, и многостраничным гайдом со ссылками на скрипты и примеры. Рекомендация Anthropic — держать SKILL.md под 500 строк, детальные справочники выносить в отдельные файлы.

Invocation: как агент решает вызвать skill

Два способа запуска. Авто-вызов по описанию: агент сравнивает запрос пользователя с описаниями всех установленных skills, при достаточном совпадении подгружает тело SKILL.md и применяет инструкции — пользователь не указывает skill явно. Явный вызов через /<имя>: пользователь набирает /skill-name, skill загружается напрямую. Имя берётся из имени директории. Аргументы передаются после имени: /deploy staging.

Динамическая подстановка контекста

Skill умеет вставлять результат shell-команды прямо в свои инструкции, давая «живой» контекст до старта агента:

---
description: Summarizes uncommitted changes and flags risks
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above and list any risks.

Конструкция !`git diff HEAD` исполняется до того, как агент увидит skill — реальный diff попадает в контекст. Также доступны подстановки $ARGUMENTS, $0, $1, ${CLAUDE_SESSION_ID}, ${CLAUDE_SKILL_DIR} и другие.

Контроль invocation и hooks

Два поля фронтматтера управляют тем, кто запускает skill: disable-model-invocation: true — только пользователь через /name (полезно для /deploy, /commit, /send-email — действий, где не хочется, чтобы агент сам решил «пора»); user-invocable: false — только агент (фоновый контекст, например legacy-system-context). Skill также может объявить hooks, привязанные к собственному жизненному циклу (PreToolUse, PostToolUse, Stop) — для валидации до запуска tool’ов, очистки после или логирования специфичных событий.

Bundled skills — встроенные в Claude Code

Claude Code поставляется с набором skills, доступных в каждой сессии. По справочнику команд Claude Code, среди встроенных — /code-review (структурированное ревью изменений), /debug (поиск и устранение багов), /loop (повторяющиеся задачи по интервалу), /batch (пакетная обработка), /claude-api (помощь со встраиванием Claude API), /run и /verify (запуск приложения и проверка изменений на работающей сборке), /run-skill-generator (обучает /run и /verify тому, как собирать конкретный проект).

В отличие от встроенных команд с фиксированной логикой, bundled skills — prompt-based: они дают агенту подробные инструкции и позволяют оркестрировать работу собственными tool’ами.

Готовые skills от Anthropic и сообщества

Официальный репозиторий — github.com/anthropics/skills: базовый набор skill-creator, pdf-skill и другие. Скопировать в ~/.claude/skills/ или симлинкнуть на репо. Awesome-листы сообщества — travisvn/awesome-claude-skills, ComposioHQ/awesome-claude-skills — кураторские подборки от разработчиков. По обзору Firecrawl, на 2026 — сотни тематических skills. Тематические коллекции вроде alirezarezvani/claude-skills собирают навыки под маркетинг, продакт, инженерию, исследования — полезно как референс для собственных.

Marketplace плагинов

Плагин — следующий уровень упаковки: один пакет может содержать сразу несколько skills, slash-команд, sub-agents, MCP-конфигов и hooks. По гайду itnots.ru, плагины подключаются командой /plugin install <namespace>/<name> и распаковываются в ~/.claude/plugins/. Skills внутри плагина видны под namespace plugin-name:skill-name и не конфликтуют с локальными. Основные источники — anthropics/skills, корневой репозиторий anthropics/claude-code и awesome-листы сообщества. При установке стороннего плагина имеет смысл открыть SKILL.md каждого вложенного навыка и просмотреть allowed-tools и scripts/ — это снижает риск получить навык, который сам выполняет неожиданные команды.

Лучшие готовые skills от Anthropic

Среди опубликованных в anthropics/skills и встроенных в Claude Code выделяются три мета-навыка «стартового набора»:

agent-builder — навык-конструктор, помогает спроектировать нового sub-agent’а: роль, ограничения tools, системный промпт, триггеры. Используется, когда нужен изолированный специалист — code reviewer, researcher, refactoring-агент.
statusline-setup — настраивает кастомную строку статуса Claude Code: модель, активный контекст, токены, режимы. Удобно, когда хочется видеть текущую модель прямо в CLI.
output-style-creator — генерирует output-style для проекта: правила форматирования ответов агента, длину, стиль кода, чек-листы. Подходит командам с единой стилистикой документации или комментариев в PR.

Хороший способ изучить best practices — открыть SKILL.md этих трёх skill’ов и посмотреть, как Anthropic пишет description, как раскладывает инструкции по слоям и какие триггеры выбирает.

Composability — вызов одного skill из другого

Skills соединяются в цепочки двумя способами. Через явный вызов в инструкциях: в теле SKILL.md одного навыка указывается ссылка на другой — «После генерации outline вызови skill seo-keyword-check». Агент увидит ссылку, найдёт нужный skill в списке и применит его инструкции внутри текущего хода. Удобно для пайплайнов вида «outline → текст → fact-check → обложка». Через context: fork и sub-agent: основной агент остаётся в сессии, под-задача выполняется изолированно, результат возвращается одним сообщением. Это спасает контекст в длинных пайплайнах. Правило: один skill — одна ответственность, цепочки строятся явно через инструкции, а не раздуванием одного SKILL.md.

Skill-паттерны для разработки

По анализу must-have skills для coding agent в 2026 и обзору Nimble, есть устойчивые паттерны:

Code review. Skill читает diff и проверяет по чек-листу команды (тесты, обработка ошибок, безопасность, типы, нейминг), возвращает структурированный отчёт.
Refactor. Описывает допустимые/запрещённые паттерны, имена файлов и переменных. Активируется на «отрефактори», «вынеси в отдельную функцию».
Documentation. Генерирует docstring/JSDoc по стилю команды, README по шаблону, CHANGELOG по conventional commits.
Test generation. Знает фреймворк (Jest, Vitest, pytest), стиль тестов (AAA, описательные имена), что мокать. Триггер — «напиши тесты для X».
Library reference. По опыту Anthropic, полезны skills с edge cases конкретной библиотеки: «Prisma — никогда не использовать findUnique без проверки на null, всегда оборачивать в try/catch ConnectionError».
Verification. Skill тестирует, что код реально работает: открывает страницу через Playwright или tmux, проверяет элемент, фиксирует результат.
Data stack. Подключает к внутренним базам: креды, шаблоны запросов, ID дашбордов. Skill сразу указывает, в какой таблице лежит user_id.
Scaffolding. Генерирует boilerplate с интерактивными решениями: «handler async или sync?» и сборка под ответ.
Deployment. Оборачивает деплой-пайплайн: проверки до push, проверки после, обязательные env, куда смотреть логи. Чаще ставится с disable-model-invocation: true — деструктивная операция.

Как создать свой skill

Самый быстрый путь — skill-creator

skill-creator — официальный мета-skill от Anthropic. По инструкции из репозитория, он работает интерактивно: установить skill-creator из anthropics/skills, сказать Claude «Я хочу создать skill для [задача]», пройти Q&A — на выходе валидный SKILL.md со структурой папок. Это особенно полезно для первых skills — заодно изучаются конвенции на практике.

Минимальный рабочий skill вручную

Простейший skill — один файл ~/.claude/skills/commit-message/SKILL.md:

---
description: Generates conventional-commits style commit message from staged changes. Use when the user wants to commit code.
---

# Conventional commit messages

## Current diff

!`git diff --cached`

## Instructions

1. Identify type: feat / fix / refactor / docs / chore / test
2. Identify scope from the modified path
3. Write one-line summary in present tense, lowercase, no period
4. Format as: `<type>(<scope>): <summary>`

Когда пользователь напишет «помоги составить commit», агент увидит совпадение с описанием и применит правила. Diff подтянется автоматически через ! подстановку.

Лучшие практики написания SKILL.md

По best practices Anthropic и 9 советам по построению skills:

Description — самое важное поле. Описание сравнивается с user-запросом. Без хорошего description skill не запустится. Включайте: предмет, действие, триггерные фразы.
Один skill — одна ответственность. Не засовывать несколько workflow’ов в один SKILL.md. Лучше два skill’а с чёткими ролями.
Конкретные инструкции, не общие принципы. Говорите что делать, не как думать. «Run git diff», а не «Analyze the changes».
Триггеры в описании. Конкретные фразы: «when the user wants to», «when the request mentions», «if the user asks about».
Дисциплина именования. name короткое, без пробелов, в lowercase. Глагол + существительное (generate-outline, review-pr).
Версионирование. Skill — это код. Держать в git, документировать изменения, тестировать на типовых запросах.
Не дублировать общие знания. Claude знает, что такое git commit. В SKILL.md описывайте специфичные правила команды: стиль коммитов, обязательные секции в README, команды build-системы.
Тело — концентрат. После загрузки skill держится в контексте до конца сессии. Каждая строка — повторяющаяся стоимость токенов. Длинные справочники выносите в отдельные файлы со ссылкой из SKILL.md.
Тестируйте триггеры. После написания skill’а проверьте 5–7 типовых формулировок задачи. Если хотя бы одна не активирует skill — расширьте description или добавьте when_to_use.

Когда использовать `disable-model-invocation: true`

По умолчанию агент автоматически выбирает подходящий skill из всех установленных. При большом количестве установленных skills растёт шанс ложных срабатываний — агент выбирает «похожий» skill, когда нужен другой. Решение: для редких или специфичных skills проставлять disable-model-invocation: true. Тогда они работают только когда пользователь явно говорит /name. Типовые кандидаты на disable: деструктивные операции (миграции, удаление данных, deploy); специфичные под клиента / проект workflow’ы, которые не должны применяться по умолчанию; экспериментальные skills, проверяемые перед широким включением.

FAQ

Что такое Claude Code Skills простыми словами?

Папки с инструкциями для ИИ-агента. Каждый skill описывает один сценарий работы. Когда пользовательская задача подходит под описание — агент автоматически применяет инструкции из skill’а или пользователь запускает его командой /skill-name.

Где живут Skills?

В ~/.claude/skills/ (глобально), .claude/skills/ (на проект), enterprise managed settings (для организации) или в плагинах. Рабочая практика — держать skills/ в репозитории конфигов и симлинкать на ~/.claude/skills/.

Какие поля обязательны в SKILL.md?

Технически только description (и его можно опустить — возьмётся первый параграф markdown). Имя берётся из имени директории. Рекомендуется явно прописывать description — это главный сигнал для авто-вызова.

Чем Skills отличаются от MCP-серверов?

Skills — декларативные текстовые инструкции для агента. MCP — программируемый протокол подключения внешних tool’ов (баз данных, API, файловой системы). Skills говорят «как делать», MCP даёт «инструменты, которыми делать». Они не конкурируют — работают на разных слоях стека.

Чем Skills отличаются от sub-agents?

Sub-agent — отдельный агент со своим контекстом и tool-разрешениями. Skill — инструкция, которая может работать как в основной сессии, так и внутри sub-agent’а (через context: fork). Sub-agent отвечает на вопрос «кому поручить», skill — «по каким правилам делать».

Можно ли отключить авто-вызов skill’а?

Да. В YAML-фронтматтере добавить disable-model-invocation: true. Skill будет работать только при явном указании /name от пользователя.

Как создать первый skill?

Самый быстрый путь — установить skill-creator из официального репозитория Anthropic и попросить агента помочь. Skill-creator проведёт через Q&A и сгенерирует валидный SKILL.md. Альтернатива — написать вручную по образцу из этой страницы.

Сколько skills можно держать одновременно?

Технического ограничения нет. Практически — при 50 plus skills начинает расти шанс ложных срабатываний. Для редких операций — disable-model-invocation: true. Для нишевых — paths с glob-паттерном, чтобы skill активировался только при работе с определёнными файлами.

Работают ли Skills в браузерной Claude.ai?

Да. Тот же формат SKILL.md поддерживается в Claude.ai, Claude Code, Claude Agent SDK и Claude Developer Platform — часть открытого стандарта Agent Skills.

Можно ли в SKILL.md подключать скрипты?

Да. Структура: my-skill/scripts/helper.py или любой другой исполняемый файл. В markdown указывается путь и условия запуска. Агент вызывает скрипт через bash/python tool. Также доступна inline ! подстановка для команд, исполняемых до загрузки skill’а.

Загружается ли тело SKILL.md, если skill не активирован?

Нет. В контекст агента при старте попадают только метаданные (name plus description). Тело подгружается, когда агент решает активировать skill. Это позволяет держать сотни skills без раздувания контекста.

Дальше

Skills — один кирпич стека вокруг Claude Code: CLI-агент Anthropic, который читает, пишет и запускает код через терминал и редактор. Если Claude Code ещё не стоит локально — стартовая точка установка Claude Code: системные требования, авторизация и первый запуск. Когда skill пора встроить в собственное приложение, дальше Claude Agent SDK — программный интерфейс для встраивания того же агентного цикла (модель, tools, hooks, skills) в свой backend. Дополнительно — обзор Anthropic, страница Claude Opus, сравнение с Cursor и общий ИИ для разработчика.