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

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

Когда задача пользователя подходит под описание skill’а, Claude автоматически подгружает его содержимое и работает по инструкциям. По данным Anthropic API Docs, описание в YAML — главный сигнал для подбора: «Claude uses description to determine when to invoke your Skill».

Это позволяет один раз описать сложный workflow, а потом запускать его естественным языком без повторного промпт-инжиниринга.

Как Skills отличаются от MCP, Hooks и Slash Commands

Механизм	Что это	Когда вызывается
Skill	Папка с SKILL.md и инструкциями	Авто-загрузка по описанию задачи
MCP-сервер	Внешний сервис с tool API	Подключается как источник tools
Hook	Скрипт на событие	Авто-запуск на edit / commit / etc
Slash command	/<имя> промпт-шаблон	Явно набирается пользователем

Skill = декларативный гайд агенту, MCP = программируемый инструмент, hook = автоматизация на событие, slash command = ручной шорткат. Подробнее про другие механизмы — на странице Claude Code.

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

По официальной документации skill — это папка со следующим содержимым:

my-skill/
├── SKILL.md             ← обязательно
├── scripts/             ← опционально: исполняемые скрипты
│   └── helper.py
├── references/          ← опционально: справочные материалы
│   └── api-spec.md
└── assets/              ← опционально: ресурсы (шаблоны, картинки)
    └── template.txt

Обязателен только SKILL.md. Остальные папки появляются по необходимости.

Где живут skills

• Глобально — ~/.claude/skills/<name>/ — доступны во всех проектах
• На проект — <project>/.claude/skills/<name>/ — только для конкретного репозитория
• Через симлинк — рабочая практика: держать skills/ в репозитории, а ~/.claude/skills/ симлинкать на него

Симлинк-вариант удобен когда skills разрабатываются и версионируются вместе с кодом проекта или личным конфигом.

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

По гайду Claude Help Center и best practices Anthropic, файл состоит из двух частей.

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

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

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

Обязательные поля:

• name — короткий идентификатор. Латиница, дефисы. Например, email-sequence, vk-ads-operator.
• description — до 200 символов, главный сигнал для авто-вызова. Claude матчит запросы пользователя против описаний всех skills и подгружает подходящий. Описание должно содержать: что делает skill, когда его использовать, какие триггер-фразы из user-запроса.

Опциональные поля:

• disable-model-invocation: true — отключает авто-загрузку. Skill будет работать только при явном указании. Полезно для редких операций, которые не должны срабатывать на похожих запросах.

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

## Style guide

- Outline ≤ 300 words
- One key per H2
- No internal SEO jargon in titles

Markdown может быть как короткой запиской, так и многостраничным гайдом с разделами, ссылками на скрипты и примерами.

Минимальный рабочий skill — пример

Простейший skill из двух частей:

Файл ~/.claude/skills/commit-message/SKILL.md:

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

# Conventional commit messages

When the user wants to commit:

1. Run `git diff --cached` to see staged changes
2. Identify the type: feat / fix / refactor / docs / chore / test
3. Identify the scope from the modified path
4. Write a one-line summary in present tense, lowercase, no period
5. Format as: `<type>(<scope>): <summary>`

## Examples

- `feat(auth): add OAuth callback handler`
- `fix(parser): handle empty input array`
- `refactor(db): extract query builder helper`

## Body (optional)

If changes are non-trivial, add a body explaining the *why*, not the *what*.
Wrap at 72 chars.

Когда пользователь напишет «помоги составить commit», Claude увидит совпадение с описанием skill’а и применит эти правила.

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

По best practices Anthropic и деталям из deep dive Hanchung Lee:

1. Description — самое важное поле. Это единственное, что Claude читает на этапе выбора skill’а. Должно содержать: предмет, действие, триггерные фразы пользователя.

❌ Плохо: 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. Один skill — одна ответственность. Не пытаться засунуть несколько workflow’ов в один SKILL.md. Лучше два skill’а с чёткими ролями, чем один универсальный.

3. Конкретные инструкции, не общие принципы. Скажите что делать, не как думать. «Run git diff», а не «Analyze the changes».

4. Триггеры в описании. Указывайте конкретные фразы, на которые должен срабатывать skill: «when the user wants to», «when the request mentions», «if the user asks about».

5. Дисциплина именования. name короткое, без пробелов, в lowercase. Желательно — глагол + существительное (generate-outline, review-pr).

6. Версионирование. Skill — это код. Его стоит держать в git, документировать изменения, тестировать на типовых запросах.

7. Не дублировать общие знания. Claude и так знает что такое git commit. В SKILL.md описывайте только специфичные правила вашей команды: стиль коммитов, обязательные секции в README, конкретные команды build-системы.

Skill-creator — официальный мета-skill

Самый быстрый способ создать skill — использовать skill-creator, официальный инструмент от Anthropic. По инструкции из репозитория, он работает интерактивно:

1. Установить skill-creator из репозитория anthropic/skills.
2. В Claude сказать: «Я хочу создать skill для [задача]».
3. Skill-creator проводит через Q&A, собирает требования.
4. Генерирует валидный SKILL.md со структурой папок.

Это особенно полезно для первых skill’ов — заодно изучаются конвенции на практике.

Где брать готовые skills

Официальный репо Anthropic. github.com/anthropics/skills — базовый набор: skill-creator, pdf-skill, и другие. Скопировать в ~/.claude/skills/ или симлинкнуть на репо.

Awesome-листы сообщества. travisvn/awesome-claude-skills, ComposioHQ/awesome-claude-skills — кураторские подборки skills от разработчиков. По данным обзора Firecrawl, на 2026 уже есть сотни тематических skills.

Тематические коллекции. alirezarezvani/claude-skills — 313+ skills под маркетинг, продакт, инженерию, исследования и т.д. Не все универсальны, но как референс для написания собственных — полезно.

Skills под Claude.ai (веб). Anthropic поддерживает Skills и в браузерной версии Claude (не только в CLI). Те же SKILL.md, такой же формат — портабельность между интерфейсами.

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

По умолчанию Claude автоматически выбирает подходящий skill из всех установленных. Это работает хорошо при 5–20 skills, но при 100+ растёт шанс ложных срабатываний — Claude может выбрать «похожий» skill, когда нужен совсем другой.

Решение: для редких или специфичных skills проставлять disable-model-invocation: true. Тогда они работают только когда пользователь явно говорит «используй skill X». Это снижает шум и делает поведение предсказуемее.

Типовые кандидаты на disable:

• Деструктивные операции (миграции, удаление данных)
• Специфичные под клиента / проект workflow’ы, которые не должны применяться по умолчанию
• Экспериментальные skills, которые проверяются перед широким включением

FAQ

Что такое Claude Code Skills простыми словами? Папки с инструкциями для агента. Каждый skill описывает один сценарий работы. Когда пользовательская задача подходит под описание — Claude автоматически применяет инструкции из skill’а.

Где живут Skills? В ~/.claude/skills/ (глобально) или <project>/.claude/skills/ (на проект). Обычная практика — держать skills/ в репозитории конфигов и симлинкать на ~/.claude/skills/.

Какие поля обязательны в SKILL.md? name (короткий идентификатор) и description (до 200 символов). Описание — главный сигнал для авто-вызова skill’а.

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

Можно ли отключить авто-вызов skill’а? Да. В YAML-фронтматтере добавить disable-model-invocation: true. Skill будет работать только при явном указании пользователя.

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

Сколько skills можно держать одновременно? Технического ограничения нет. Практически — при 50+ skills начинает расти шанс ложных срабатываний (Claude выбирает похожий skill, когда нужен другой). Для редких операций — ставьте disable-model-invocation: true.

Работают ли Skills в браузерной Claude.ai? Да. Anthropic поддерживает тот же формат SKILL.md и в Claude.ai (веб), и в Claude Code (CLI). Skills переносимы между интерфейсами.

Можно ли в SKILL.md подключать скрипты? Да. Структура: my-skill/scripts/helper.py или любой другой исполняемый файл. В markdown указывается путь и условия запуска. Claude вызывает скрипт через bash/python из tool’ов.