Навыки

CLAUDE.md хорош для правил, которые нужны всегда. Но у каждой команды есть процедуры, которые нужны иногда: собрать релиз, оформить PR по шаблону, написать компонент по соглашениям проекта. Держать их в CLAUDE.md — значит тратить контекст каждой сессии на инструкции, которые в этой сессии не понадобятся. Для этого есть навыки (skills): инструкции, которые загружаются по запросу.

Что такое навык

Навык — это папка с файлом SKILL.md внутри. В файле — YAML-заголовок и markdown-инструкция. При старте сессии в контекст попадает только однострочное описание навыка; полный текст загружается, когда вы вызываете навык командой /имя или когда Claude сам решает, что он нужен.

Место хранения задаёт область:

Минимальный навык:

---
name: api-conventions
description: REST API design conventions for our services
---
# API Conventions
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path (/v1/, /v2/)

Поле name необязательно — по умолчанию берётся имя папки. Поле description формально тоже, но без него Claude не сможет понять, когда навык уместен, поэтому пишите его всегда. Именно по описанию модель решает вызвать навык автоматически, когда вы, например, просите «добавь эндпоинт для списка заказов».

Если раньше вы пользовались файлами в .claude/commands/, знайте: это тот же механизм. Файл .claude/commands/deploy.md и .claude/skills/deploy/SKILL.md оба создают команду /deploy. Навыки добавляют папку под вспомогательные файлы, автоматический вызов и несколько полей управления.

Два способа вызова

По команде. Наберите /имя-навыка и, если нужно, аргументы. Внутри текста навыка аргументы доступны через $ARGUMENTS (всё, что после имени), $ARGUMENTS[0], $ARGUMENTS[1] (по позиции) или по именам из поля arguments.

Автоматически. Claude видит описания всех навыков и загружает подходящий, если ваш запрос совпал с описанием. Это можно ограничить: disable-model-invocation: true — только вы можете вызвать навык; user-invocable: false — только Claude, навык не показывается в меню /.

Первое — для процедур с побочными эффектами (деплой, публикация, рассылка), которые не должны запускаться случайно. Второе — для фоновых знаний, которые Claude должен подтягивать сам, а вам вызывать незачем: «как устроена legacy-система», «схема прав в CRM».

Навык-процедура

Пример из документации — исправление задачи по номеру:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.

1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR

Вызов: /fix-issue 1234. Агент подставит номер вместо $ARGUMENTS и пойдёт по шагам. Заметьте disable-model-invocation: true: процедура пушит ветку и открывает PR, случайный запуск здесь нежелателен.

Пример для нашей практики — навык для нового компонента в Next.js-проекте:

---
name: new-component
description: Scaffold a React component following project conventions. Use when the user asks to create a new UI component.
arguments: [name, feature]
---
Create component $name in `src/features/$feature/components/$name/`.

- `$name.tsx`: functional component, named export, props typed via interface
- `$name.test.tsx`: render test with Testing Library, one interaction test
- `index.ts`: re-export
- Strings only through `t()` from `@/i18n`; add keys to `locales/ru.json`
- No default exports, no inline styles; use CSS modules next to the component

After creating files, run `pnpm test -- src/features/$feature` and report the result.

Поле arguments объявляет именованные аргументы, которые подставляются как $name и $feature. Вызов: /new-component OrderFilters orders. Такой навык можно вызвать и не по команде: Claude подхватит его сам на фразу «создай компонент фильтров заказов», потому что описание совпадает.

Динамический контекст

Навык может выполнить команду оболочки до того, как его текст попадёт к Claude, и подставить вывод. Синтаксис — восклицательный знак и команда в обратных кавычках:

---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed or wants a commit message.
---
## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list
any risks you notice such as missing error handling, hardcoded values,
or tests that need updating. If the diff is empty, say so.

Команда выполняется при вызове, и Claude сразу получает актуальный diff — без отдельного шага «прочитай изменения». Команды с ненулевым кодом выхода прерывают вызов навыка; если команда может падать штатно, добавьте || true. Ограничение по времени — две минуты.

Права, изоляция, вспомогательные файлы

Поле allowed-tools заранее разрешает инструменты на время выполнения навыка:

---
name: commit
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Так навык коммита не будет спрашивать разрешение на каждую git-команду. Разрешение действует один ход и снимается после вашего следующего сообщения.

Поле context: fork запускает навык в отдельном субагенте: текст навыка становится его задачей, а результат возвращается в основной разговор. Поле agent задаёт тип субагента (Explore, Plan, general-purpose или ваш). Это удобно для навыков-исследований, которые читают много файлов.

В папке навыка могут лежать вспомогательные файлы: reference.md с подробностями, examples.md, скрипты в scripts/. На них ссылаются из SKILL.md относительными ссылками, и Claude читает их только когда доходит до ссылки. Так навык по интеграции с платёжным шлюзом может держать в SKILL.md короткую процедуру, а в reference.md — описание API на сто строк, которое не грузится без надобности. Путь к папке навыка доступен через ${CLAUDE_SKILL_DIR}.

Встроенные навыки

Часть команд Claude Code — это навыки из комплекта: /code-review (ревью diff'а), /security-review, /debug (систематическая отладка), /verify (собрать и запустить, чтобы проверить изменение), /run (запустить приложение), /batch (разбить большую правку на параллельные субагенты), /loop (повторять промпт по расписанию), /doctor (проверка настройки). Наберите / и посмотрите, что доступно в вашей версии.

Навык, CLAUDE.md или субагент

Простое разграничение.

• CLAUDE.md — правила, нужные в каждой сессии: команды, соглашения, ловушки.
• Навык — процедура или знание, нужные иногда: как собрать релиз, как устроен модуль оплаты, как оформить компонент.
• Субагент — когда важна изоляция контекста или ограничение инструментов: ревью, исследование, прогон тестов.

Если CLAUDE.md разросся, ищите в нём разделы, которые читаются словами «когда нужно сделать X» — это кандидаты в навыки. Документация прямо советует переносить такие инструкции из CLAUDE.md в навыки, чтобы базовый контекст оставался небольшим.

Если навык не срабатывает автоматически, проверьте описание — в нём должны быть слова, которыми вы обычно формулируете задачу. Если срабатывает слишком часто — уточните описание или поставьте disable-model-invocation: true. Синтаксис заголовка проверяет команда claude plugin validate .claude/skills.