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

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

У меня есть небольшой self-hosted инстанс Mastodon. Обновление это одни и те же двадцать минут каждый раз: прочитать release notes, забэкапить базу, поднять три тега образов, перезапустить, проверить, вычистить старые образы. Ничего сложного и всё легко забывается — худшее сочетание. Шаг, который пропускаешь на патч-релизе, это бэкап, а патч-релизы ровно тогда и выясняется, что он был нужен.

Это единственная процедура, которую я удосужился записать как skill. И на неё же я бы показал, объясняя, зачем skills вообще нужны.

Плейбуки, а не постоянные правила

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

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

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

Где обычно путаются:

CLAUDE.md / rules — всегда включены. Подходит для стабильных правил: команды, конвенции, архитектурные решения.
Skills — по запросу. Подходит для повторяемых действий: deploy, review, commit. Или справочника который нужен только иногда.
.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

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

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

Вот и вся структура: name становится slash-командой, description — то, что Claude читает, решая подгружать ли skill самому, а всё под фронтматтером это инструкции.

Все frontmatter поля

Большинство этих полей тебе не понадобятся большую часть времени. Тот самый Mastodon-skill из опенера — 156 строк и ровно два поля, 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 пока skill активен: `low`, `medium`, `high`, `xhigh`, `max`. Верхние уровни зависят от модели, на которой работаешь.
`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 напрямую...

Context skills самый недооценённый тип. Skill, который тихо подгружает контекст о запутанной части кодовой базы — без slash-команды, просто по paths: — незаметно делает Claude лучше каждый раз, когда ты касаешься этого кода. Никто не замечает что он есть. В этом и смысл.

Аргументы

Именно с аргументами 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

$ARGUMENTS — это всё, что идёт после имени команды. Если нужны части по отдельности, они позиционные:

---
name: migrate-component
---

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

Динамический контент через 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 строк. Детали — в отдельные файлы.

До этого потолка я ни разу не добирался. Mastodon-skill — самое длинное, что я писал, и это треть от лимита. Отчего мне кажется, что skill на 500 строк это обычно два skill’а, которые ещё не разделили.

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

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

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

Правило, которым пользуюсь я: всё, у чего есть побочный эффект за пределами сессии — /deploy, /commit, /send-message — получает disable-model-invocation: true, потому что решать когда это запускается хочу я. Фоновые знания, которые просто делают Claude осведомлённее, получают user-invocable: false и не мозолят глаза.

Встроенные skills

Набор меняется от релиза к релизу и зависит от того, какие плагины включены, так что любой список в блог-посте это снимок — /help покажет что реально загружено у тебя. Те, к которым возвращаюсь я:

Skill	Что делает
`/code-review`	Ревью текущего диффа, ветки или PR
`/simplify [focus]`	Ревью изменённого кода на переиспользование и упрощение, потом применяет правки
`/loop [interval] <prompt>`	Запускает prompt по расписанию
`/run`	Поднимает приложение проекта, чтобы проверить изменение вживую
`/claude-api`	Загружает reference по Claude API

Как выглядит настоящий

Всё выше — шаблоны. А это тот самый Mastodon-skill из опенера, с вырезанной конкретикой моего сервера: 156 строк, два поля во фронтматтере, ни одной хитрой фичи.

---
name: mastodon-upgrade
description: Upgrade the self-hosted Mastodon instance (DigitalOcean droplet,
  Docker Compose) to a newer release. Use when asked to update/upgrade Mastodon,
  check whether the instance is behind upstream, or roll back a bad upgrade.
  Also covers post-upgrade verification and disk cleanup of stale images.
---

# Mastodon upgrade

Прочитай release notes целевой версии **до** того, как трогать сервер. Патч-релизы
обычно это просто bump тега, но минорные и мажорные тянут миграции и изменения
`.env`, которые эта процедура вслепую не покрывает.

## The environment
[таблица: какой хост, какой compose-проект, какие сервисы, куда идут бэкапы,
что ещё крутится на этой машине и что трогать нельзя]

## Before you start
1. Прочитать release notes всех версий между текущей и целевой
2. Проверить свободное место — на pull нужно ~1.2 GB
3. Если прыжок через минорную версию — остановиться и читать внимательно

## Procedure
### 1. Забэкапить базу
### 2. Поднять теги
### 3. Pull и рестарт
### 4. Проверить
### 5. Вычистить старые образы

Работает это по двум причинам, и ни одна из них не фича из таблицы выше.

description перечисляет фразы, которые я реально набираю — “обнови Mastodon”, “не отстал ли инстанс”, “откати” — вместо абстрактного описания возможностей. В этом и разница между skill, который подгружается сам, и skill, который просто лежит.

А тело конкретно до степени бесполезности для кого-то ещё: какие три тега, в каком порядке, как выглядит здоровый бэкап, какие сервисы на этой машине чужие. Эта конкретика и есть вся ценность. Skill, который говорит “деплой аккуратно”, не стоит ничего — Claude и так знает, что надо аккуратно, он не знает, где лежит скрипт бэкапа.

Отправные точки

Это шаблоны, а не 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 было “creates a summary”, а я каждый раз спрашивал “write a session log”. Эти две фразы не пересекаются вообще, поэтому skill так и не загрузился. Отсюда и правило писать описания теми словами, которые ты реально набираешь: ты пишешь не документацию, а поисковый запрос, который твоё будущее «я» случайно наберёт.

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

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

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

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

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

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