Claude Code skills — как написать один .md файл и автоматизировать всё, что раздражает

Claude Code skills — как написать один .md файл и автоматизировать всё, что раздражает

Каждый раз объяснять Claude Code, как ревьюить PR, как деплоить или как писать тесты — это как диктовать рецепт повару перед каждым блюдом. Skills решают эту проблему: пишешь инструкции один раз в .md файл, и дальше вызываешь их одной командой /review, /deploy, /test — или Claude сам подтягивает нужный скилл, когда контекст совпадает.

TL;DR: Skills — это .md файлы с YAML-frontmatter, которые живут в ~/.claude/skills/ (глобальные) или .claude/skills/ (проектные). Имя файла становится slash-командой. Скилл может ограничивать доступные инструменты, запускаться в изолированном субагенте, инжектить данные из shell-команд и даже генерировать HTML-отчёты. По документации Claude Code, описания скиллов занимают 2% контекстного окна — при 20+ скиллах можно упереться в лимит.

Зачем вообще skills, если есть CLAUDE.md

Короткий ответ: CLAUDE.md — это контекст, skills — это действия, hooks — это гарантии. Подробнее:

• CLAUDE.md — загружается в начале каждой сессии. Сюда пишешь стиль кода, структуру проекта, конвенции. Claude обычно следует этим правилам, но не гарантирует — это рекомендация, а не закон
• Skills — загружаются по запросу. Вызываешь /deploy — Claude получает пошаговые инструкции. Или Claude сам подтягивает скилл api-conventions, когда видит, что ты пишешь API-эндпоинт
• Hooks — выполняются всегда, детерминированно. PostToolUse хук на форматирование сработает после каждого редактирования файла, без исключений

Правило простое: если это рекомендация — CLAUDE.md. Если это рутина — skill. Если это требование — hook.

Создаём первый skill за 2 минуты

Минимальный скилл — это папка с файлом SKILL.md:

mkdir -p ~/.claude/skills/review-pr

Создаём ~/.claude/skills/review-pr/SKILL.md:

---
name: review-pr
description: Review current PR for bugs, security issues, and code quality
disable-model-invocation: true
allowed-tools: Bash(gh *), Read, Grep, Glob
---

Review the current pull request:

## Context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Checklist
1. Check for bugs and logic errors
2. Check for security vulnerabilities (SQL injection, XSS, exposed secrets)
3. Check for missing error handling
4. Check test coverage for changed code
5. Note any performance concerns

Provide feedback organized by priority:
- **Critical** — must fix before merge
- **Warning** — should fix
- **Suggestion** — nice to have

Теперь /review-pr в Claude Code запустит ревью текущего PR. Обрати внимание на три ключевых момента:

1. disable-model-invocation: true — Claude не будет запускать этот скилл сам. Только ты, только /review-pr. Для деплоя, отправки сообщений, коммитов — всегда ставь этот флаг
2. allowed-tools — скилл работает в read-only режиме плюс GitHub CLI. Claude не сможет редактировать файлы во время ревью
3. !gh pr diff`` — это динамический контекст. Shell-команда выполняется до того, как Claude увидит промпт, и её вывод подставляется в текст

Frontmatter: что настраивается

Все поля опциональные, но description — must have. Без него Claude не поймёт, когда применять скилл автоматически.

• name — имя и slash-команда. Только строчные буквы, цифры, дефисы. Максимум 64 символа
• description — когда использовать. Claude читает это описание и решает, подходит ли скилл к текущей задаче
• argument-hint — подсказка при автокомплите: [issue-number], [filename]
• disable-model-invocation — true = только ручной вызов через /name
• user-invocable — false = скрыт из меню /, только Claude может вызвать
• allowed-tools — белый список инструментов: Read, Grep, Glob, Bash(npm *)
• model — модель: opus, sonnet, haiku. По умолчанию наследует от сессии
• context: fork — запуск в изолированном субагенте (отдельное контекстное окно)
• agent — тип субагента при context: fork: Explore, Plan, general-purpose или кастомный

Переменные подстановки внутри скилла:

• $ARGUMENTS — всё, что написано после /skill-name
• $ARGUMENTS[0], $0 — первый аргумент, $1 — второй
• ${CLAUDE_SESSION_ID} — ID текущей сессии

Пример с аргументами:

---
name: fix-issue
description: Fix a GitHub issue by number
disable-model-invocation: true
---

Fix GitHub issue #$0:

1. Read the issue: !`gh issue view $0`
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit referencing #$0

Вызов: /fix-issue 42 — и Claude получает полный контекст issue из GitHub.

5 скиллов, которые реально экономят время

1. Конвейер тестирования

---
name: test-and-fix
description: Run tests, analyze failures, fix the code
disable-model-invocation: true
---

1. Run the test suite: `npm test` (or detect from package.json)
2. If all pass — report "All green" and stop
3. If tests fail:
   a. Read each failing test and the tested code
   b. Identify root cause
   c. Fix the code (NOT the tests, unless tests are wrong)
   d. Re-run tests
   e. Repeat until green or 3 attempts
4. Show summary: what broke, what was fixed, what remains

2. Контекст-справочник для библиотеки

---
name: dexie-expert
description: Dexie.js database expert. Use when working with IndexedDB, Dexie queries, or browser storage.
user-invocable: false
---

When working with Dexie.js:
- Use `liveQuery()` for reactive queries in React
- Always define indexes in schema, don't query unindexed fields
- Use `table.where()` over `table.filter()` for performance
- Transactions auto-commit — don't mix async/await with .then()

For API details, see [reference.md](reference.md)

user-invocable: false — этот скилл нельзя вызвать через /. Claude сам подтянет его, когда увидит работу с Dexie.js. Сопутствующий файл reference.md в той же папке содержит детальную документацию API.

3. Генерация визуального отчёта

По документации, скиллы могут запускать скрипты на любом языке. Паттерн: скилл вызывает Python-скрипт → скрипт генерирует HTML → файл открывается в браузере.

---
name: codebase-viz
description: Generate interactive codebase visualization
allowed-tools: Bash(python *)
---

Run the visualization script:
python ~/.claude/skills/codebase-viz/scripts/visualize.py .

This creates codebase-map.html and opens it in the browser.

Скрипт scripts/visualize.py сканирует директории и генерирует self-contained HTML с collapsible tree, цветовой разметкой по типам файлов и сайдбаром со статистикой. Работает на стандартной библиотеке Python, ничего устанавливать не нужно.

4. PR-саммари в изолированном контексте

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## PR context
- PR diff: !`gh pr diff`
- PR description: !`gh pr view`
- Changed files: !`gh pr diff --name-only`

Summarize this PR:
1. What changed and why
2. Key decisions and trade-offs
3. Potential risks
4. Missing test coverage

context: fork запускает скилл в изолированном субагенте — отдельное контекстное окно, без доступа к истории чата. Весь вывод gh pr diff остаётся в субагенте, а в основной чат возвращается только саммари. Для больших PR это критично — diff на 500 строк не засорит твой основной контекст.

5. Конвейер деплоя с гарантиями

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
context: fork
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-deploy-command.sh"
---

Deploy $ARGUMENTS to production:

1. Run the full test suite
2. Build the application
3. Run smoke tests against the build
4. Push to the deployment target
5. Verify the deployment succeeded
6. If any step fails — rollback and report

Этот скилл комбинирует три механизма: disable-model-invocation (только ручной вызов), context: fork (изоляция), и hooks (валидация каждой bash-команды перед выполнением). Хук validate-deploy-command.sh проверяет, что Claude не запускает ничего опасного.

Структура файлов для сложных скиллов

Для скиллов с документацией, шаблонами или скриптами используй директорию:

my-skill/
├── SKILL.md           # Основные инструкции (обязательно)
├── reference.md       # API-документация (по запросу)
├── examples.md        # Примеры вывода
├── templates/
│   └── report.md      # Шаблон для генерации
└── scripts/
    └── validate.sh    # Скрипт для выполнения

В SKILL.md ссылайся на сопутствующие файлы:

## Resources
- For API details, see [reference.md](reference.md)
- For output format, see [examples.md](examples.md)

Claude подгрузит эти файлы только когда они реально нужны — не при каждом вызове. По документации, SKILL.md лучше держать до 500 строк, а детали выносить в отдельные файлы.

Где хранить скиллы

• ~/.claude/skills/ — глобальные, работают во всех проектах. Сюда кладёшь универсальные вещи: ревью, деплой, форматирование
• .claude/skills/ — проектные, коммитятся в git. Скиллы, специфичные для кодовой базы: конвенции API, миграции, структура базы
• Плагины — через skills/ в директории плагина, неймспейс plugin:skill
• Enterprise — через managed settings для всей организации

Приоритет: Enterprise > Personal > Project. Если имена совпадают — побеждает более высокий уровень.

В монорепо скиллы автоматически обнаруживаются из вложенных .claude/skills/ — если работаешь в packages/frontend/, Claude увидит скиллы из packages/frontend/.claude/skills/.

Подводные камни

Бюджет контекстного окна. Описания всех скиллов загружаются в контекст, чтобы Claude знал, что доступно. Бюджет — 2% контекстного окна (фоллбэк: 16 000 символов). С 20+ скиллами с длинными description реально упереться в лимит. Проверяй командой /context — если видишь предупреждение об excluded skills, сокращай описания или выноси редкие скиллы в disable-model-invocation: true (они не занимают бюджет). Можно увеличить лимит через SLASH_COMMAND_TOOL_CHAR_BUDGET, но это съест контекст для основной работы.

context: fork без задачи — пустой результат. Если скилл содержит только гайдлайны вроде "use RESTful naming" без конкретного задания, субагент получит инструкции, но не поймёт, что делать, и вернёт пустоту. context: fork работает только для скиллов с явными шагами.

user-invocable: false не блокирует вызов через Skill tool. Это поле только скрывает скилл из меню /. Claude всё ещё может вызвать его программно. Для полной блокировки нужен disable-model-invocation: true.

Скилл не триггерится автоматически. Частая проблема: описание не совпадает с тем, как ты формулируешь запрос. Claude ищет ключевые слова из description. Если написано "Review code for security", а ты просишь "check this for vulnerabilities" — может не сработать. Решение: пиши description с вариативными формулировками или вызывай напрямую через /name.

Скиллы не наследуются субагентами. Если создал кастомный субагент, он не увидит скиллы из основной сессии. Нужно явно прописать skills: [skill-name] в frontmatter субагента — тогда полный контент скилла инжектится при старте.

Вердикт

Из всего арсенала кастомизации Claude Code — CLAUDE.md, hooks, skills, subagents — именно skills дают самый быстрый результат при минимальных усилиях. Один .md файл с 20 строками инструкций заменяет ежедневное копирование промптов. Три скилла, которые окупаются сразу: /review-pr с динамическим контекстом из gh, /test-and-fix для цикла тест-фикс-тест, и фоновый справочник по основной библиотеке проекта с user-invocable: false. Остальное — оптимизация для тех, кто уже использует Claude Code как основной инструмент.

Как попробовать

1. Создай папку для скилла:

mkdir -p ~/.claude/skills/my-first-skill

2. Напиши SKILL.md — минимум description и инструкции:

---
name: my-first-skill
description: What this skill does and when to use it
---

Your instructions here. Be specific.
Use $ARGUMENTS for user input.

3. Проверь, что скилл виден — спроси Claude Code: "What skills are available?"

4. Вызови напрямую: /my-first-skill some arguments

5. Для управления скиллами через интерактивный интерфейс — /agents (да, скиллы тоже показываются)

6. Полная документация — code.claude.com/docs/en/skills, раздел про субагентов — code.claude.com/docs/en/sub-agents