2 апреля 2026 г. Read in English

Как писать свои Skills

Актуально на апрель 2026.

Что такое Skills

Skills для меня это способ “обучать” Claude Code повторяемым воркфлоу, не превращая CLAUDE.md в простыню.

Skill это папка с файлом SKILL.md (YAML frontmatter + Markdown инструкции). Claude может подхватить skill автоматически когда он релевантен, или ты можешь запустить его вручную как /slash-command.

Практический смысл очень простой: в CLAUDE.md должны жить правила дороги, а в skills — повторяемые приёмы.

Ключевые отличия:

CLAUDE.md / rules это “постоянная память” проекта. Хорошо для стабильных правил (команды, конвенции, архитектура).
Skills это “плейбуки по запросу”. Хорошо для действий и воркфлоу (deploy, commit, review) или опционального справочника.
.claude/commands/ всё еще работает, но кастомные команды объединили со skills. .claude/commands/deploy.md и .claude/skills/deploy/SKILL.md оба создают /deploy. Skills удобнее, потому что можно хранить supporting files рядом.

Где хранить

Расположение	Scope
`~/.claude/skills/<name>/SKILL.md`	Все твои проекты (личные)
`.claude/skills/<name>/SKILL.md`	Только этот проект (в git)
Плагин: `<plugin>/skills/<skill-name>/SKILL.md`	Где плагин включен

При конфликте имён: enterprise > личные > проектные. Skills из плагинов живут в неймспейсе plugin-name:skill-name, поэтому с остальными не конфликтуют.

Если работаешь один, начинай с личных skills. Если воркфлоу явно относится к одному репозиторию, переноси его в .claude/skills/ и коммить.

Минимальный skill

Это самый маленький полезный пример, который я знаю. Он делает одну вещь, у него понятный триггер, и его легко проверить.

mkdir -p ~/.claude/skills/explain-code

~/.claude/skills/explain-code/SKILL.md:

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works or when asked "how does this work?"
---

When explaining code, always:

1. **Start with an analogy** — сравни с чем-то из реальной жизни
2. **Draw a diagram** — ASCII art для структуры или flow
3. **Walk through step-by-step** — что происходит по шагам
4. **Highlight a gotcha** — частая ошибка или заблуждение

Проверка двумя способами:

Пусть Claude подхватит автоматически: “How does this code work?”
Запусти вручную: /explain-code src/auth/login.ts

Структура SKILL.md

---
name: skill-name            # становится /skill-name
description: Что делает и когда использовать. Claude читает это для авто-запуска.
---

# Содержимое

Инструкции для Claude что делать когда skill активирован.

Все frontmatter поля

Большинство этих полей тебе не понадобятся большую часть времени. Для многих реальных skills достаточно name + description + инструкции.

Поле	Описание
`name`	Имя. Если не указать, берется имя папки. Только lowercase буквы, цифры и дефисы. Макс 64 символа.
`description`	Что делает и когда использовать. Рекомендуется. В списке skills описания длиннее ~250 символов обрезаются, поэтому самое важное ставь в начало.
`argument-hint`	Подсказка для автокомплита. Пример: `"[issue-number]"`
`disable-model-invocation`	`true` чтобы Claude не запускал автоматически. Тогда запускаешь только ты: `/name`.
`user-invocable`	`false` чтобы скрыть из меню `/` (Claude все еще может использовать).
`allowed-tools`	Какие tools доступны без запроса разрешения пока активен skill. Можно строкой через пробел или YAML list.
`model`	Переопределить модель пока активен skill.
`effort`	Переопределить effort (`low`/`medium`/`high`/`max`, где `max` только для Opus 4.6).
`context`	`fork` чтобы выполнить skill в отдельном subagent контексте.
`agent`	Какой subagent использовать при `context: fork`.
`hooks`	Hooks на жизненный цикл skill.
`paths`	Glob паттерны, ограничивающие когда Claude авто-загружает skill (формат как у path-scoped rules).
`shell`	Shell для inline `!` команд (`bash` или `powershell`, с Windows-тогглом).

Три типа контента

Я мысленно делю skills на три корзины:

1. Reference — знания которые Claude применяет

Загружается inline, Claude использует рядом с разговором:

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- RESTful naming conventions
- Consistent error format: { error, code, message }
- Input validation on all endpoints
- JSDoc comments for all public routes

2. Task — пошаговая инструкция для конкретного действия

Для действий которые хочешь контролировать сам, добавь disable-model-invocation: true:

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
context: fork
---

Deploy to production:
1. Run test suite — `bun test`
2. Build — `bun run build`
3. Push to deployment target
4. Verify deployment succeeded

3. Context — фоновые знания только для Claude

Скрыт из меню, Claude использует когда нужно:

---
name: legacy-system-context
description: Context about the legacy billing system. Load when working with src/billing/legacy/
user-invocable: false
paths:
  - "src/billing/legacy/**"
---

# Legacy Billing System

Эта система написана в 2015 году и использует...
Никогда не трогай файл legacy-core.js напрямую...

Аргументы

Именно с аргументами skill перестаёт быть статичным шаблоном и начинает ощущаться как инструмент.

---
name: fix-issue
description: Fix a GitHub issue by number
disable-model-invocation: true
argument-hint: "[issue-number]"
---

Fix GitHub issue #$ARGUMENTS:

1. Read the issue description
2. Find relevant code
3. Implement the fix
4. Write tests
5. Create a commit

Вызов: /fix-issue 123

Позиционные аргументы:

---
name: migrate-component
---

Migrate the $0 component from $1 to $2.
# /migrate-component SearchBar React Vue
# $0 = SearchBar, $1 = React, $2 = Vue

Все аргументы: $ARGUMENTS — всё что после имени команды.

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

Префикс ! — выполнить команду и вставить результат до того как Claude увидит prompt:

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

## Pull Request Context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Task
Summarize this pull request: what changed, why, and what to review carefully.

Команды выполняются до отправки Claude. Поэтому этот паттерн особенно полезен для PR review, release notes и incident summaries.

Path-specific skills

Загружаются только когда Claude работает с matching файлами:

---
name: react-patterns
description: React component patterns for this codebase
paths:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
---

When writing React components:
- Functional components only, no class components
- Custom hooks в src/hooks/
- Стили через CSS modules

Запуск в subagent (context: fork)

Это одна из самых полезных возможностей. Skill выполняется в изолированном контексте, поэтому основной разговор остаётся чище:

---
name: deep-research
description: Research a topic thoroughly in the codebase
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Return a summary with specific file references

agent выбирай по задаче (read-only research vs implementation) или укажи кастомный subagent из .claude/agents/.

Папка с дополнительными файлами

Если skill начинает превращаться в простыню Markdown, разбивай его. SKILL.md должен оставаться читабельным:

.claude/skills/deploy/
├── SKILL.md              # основные инструкции + навигация
├── checklist.md          # детальный чеклист
├── rollback-guide.md     # инструкции на случай проблем
└── scripts/
    └── health-check.sh   # скрипт проверки

В SKILL.md ссылайся на файлы явно:

---
name: deploy
description: Deploy to production with full checklist
---

Follow the deployment checklist in [checklist.md](checklist.md).
If something goes wrong, see [rollback-guide.md](rollback-guide.md).

After deployment run: !`./scripts/health-check.sh`

SKILL.md держи до 500 строк. Детали — в отдельные файлы.

Контроль вызова

Это важно настроить в самом начале, потому что именно здесь решается, насколько “навязчивым” будет skill в повседневной работе.

Frontmatter	Ты вызываешь	Claude вызывает	В контексте
(дефолт)	✅	✅	Описание всегда, контент по вызову
`disable-model-invocation: true`	✅	❌	Не загружается автоматически
`user-invocable: false`	❌	✅	Описание в контексте, скрыт из меню

Когда что:

/deploy, /commit, /send-message → disable-model-invocation: true (ты контролируешь когда)
Фоновые знания о legacy системе → user-invocable: false (Claude решает когда нужно)

Встроенные skills (бесплатно из коробки)

Skill	Что делает
`/batch <instruction>`	Параллельный рефакторинг — разбивает на задачи, запускает агентов в worktrees
`/simplify [focus]`	Code review + исправление — 3 агента параллельно
`/debug [description]`	Включает debug logging и анализирует проблему
`/loop [interval] <prompt>`	Запускает prompt по расписанию
`/claude-api`	Загружает reference по Claude API

Практические примеры

Лучшие skills обычно не какие-то хитрые демо, а скучные операционные инструменты, к которым ты возвращаешься снова и снова.

Commit helper

---
name: commit
description: Create a well-formatted git commit
disable-model-invocation: true
allowed-tools: Bash(git *)
---

Create a git commit:
1. Run `git diff --staged` to see changes
2. Write commit message in format: `type(scope): description`
   Types: feat, fix, docs, style, refactor, test, chore
3. Keep subject under 72 characters
4. Add body if changes are complex

$ARGUMENTS

Code review

---
name: review
description: Review code changes for quality, security, and best practices
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob, Bash(git *)
---

Review the recent changes:

## Changes to review
!`git diff HEAD~1`

## Review checklist
- [ ] Code quality and readability
- [ ] Security issues (injections, exposed secrets)
- [ ] Error handling
- [ ] Test coverage
- [ ] Performance implications

Provide feedback organized by: Critical → Warnings → Suggestions

Session logger

---
name: session-log
description: Log this session's activity
disable-model-invocation: true
---

Append a summary of this session to logs/${CLAUDE_SESSION_ID}.log:

- What was accomplished
- Files changed
- Decisions made
- Next steps

$ARGUMENTS

Troubleshooting

Когда skill ощущается “каким-то кривым”, проблема обычно в одном из трёх мест: расплывчатый description, неправильный режим вызова или слишком много всего в одном файле.

Skill не триггерится автоматически:

Проверь что description содержит ключевые слова которые ты используешь
Спроси Claude “what skills are available?” — проверь что skill в списке
Вызови вручную /skill-name чтобы убедиться что работает

Skill триггерится слишком часто:

Сделай description конкретнее
Добавь disable-model-invocation: true

Описание обрезается:

Front-load главное — первые 250 символов самые важные