Как создать свой навык для Claude Code и игры на телефоне

Сегодня разбираем материал freecodecamp.org о теме «Как создать собственный навык для Claude Code». Практический разбор с шагами и примерами, который можно быстро применить в своей работе.

---

Разработчики формируют свои рабочие процессы, повторяя одни и те же действия: будь то написание сообщений коммитов, чеклист перед открытием pull request или структура, которой они придерживаются при ревью кода. Эти процессы требуют повторного объяснения агентам в каждой сессии, и каждый раз агент воспринимает инструкции по-своему.

Навыки агента решают эту проблему: это markdown-файлы, которые автоматически загружаются в контекст Claude Code при необходимости. Вы один раз описываете рабочий процесс, и агент следует ему каждый раз. Важно, что один и тот же файл может использоваться в Claude Code, GitHub Copilot, Cursor и Gemini CLI.

Это руководство предлагает пошаговое руководство по созданию навыка. Вы разработаете commit-message-writer — навык, который читает staged-изменения и генерирует структурированное сообщение коммита по стандарту Conventional Commits. В итоге вы получите рабочий навык, установленный и готовый к использованию, а структура будет понятна для создания любых необходимых навыков.

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

Навык — это папка, содержащая файл SKILL.md. Этот файл состоит из двух частей: блока YAML frontmatter (метаданных в начале файла) вверху и тела в формате markdown ниже.

my-skill/
└── SKILL.md

Frontmatter сообщает агенту, как называется навык и когда его использовать. Тело сообщает агенту, что делать при загрузке навыка. Вот минимальная структура:

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

# My Skill

Instructions for the agent go here.

Когда вы вызываете навык — явно через /skill-name или описывая свои потребности — агент читает тело SKILL.md и следует указанным инструкциям. Frontmatter не попадает в инструкции агента; это метаданные для системы навыков, которые помогают принимать решение о загрузке навыка.

Как агент решает, загружать ли навык

Агент принимает решение о загрузке вашего навыка, опираясь исключительно на поле description, которое должно быть конкретным и ясным.

Навыки появляются в контексте Claude Code в виде списка имён и описаний. Когда вы делаете запрос, агент просматривает этот список и загружает любой навык, описание которого соответствует вашему запросу. Если описание расплывчато, навык не загрузится тогда, когда он нужен. Если описание слишком узкое, оно не сработает для вариаций одного и того же запроса.

Инструкции в теле имеют значение только после загрузки навыка. Правильно написанное описание определяет, загрузится ли навык вообще.

Чем навыки не являются

Навыки — это файлы с инструкциями. Они не могут выполнять код самостоятельно, но могут инструктировать агента запускать команды с помощью его инструментов. Это не плагины или пакеты, у них нет среды выполнения; это markdown-файлы, которые агент читает как рецепты, следуя им последовательно.

Как выбрать, что создавать

Лучшие навыки обладают тремя свойствами.

Они кодируют повторяемый рабочий процесс. Если вы каждый раз делаете что-то по-разному, навык не поможет. Если вы следуете одним и тем же шагам в каждой сессии — даже если объясняете их по-разному — это кандидат на навык.

У них есть чёткий триггер. Вы должны уметь закончить фразу «Этот навык нужен мне, когда я хочу…». Если вы не можете закончить эту фразу одним придаточным предложением, рабочий процесс недостаточно ограничен для навыка.

Они производят согласованный формат вывода. Навыки, которые выводят результат в фиксированной структуре — сообщение коммита, ревью кода, спецификация — проще создавать и тестировать, чем навыки, производящие произвольный текст.

Хорошие кандидаты: сообщения коммитов, описания pull request, ревью кода, записи в changelog. Плохие кандидаты: «помоги мне обдумать это», «сделай это лучше» — слишком открытые, чтобы кодировать их в навыке.

Для этого руководства генерация сообщений коммитов — правильный масштаб. Триггер очевиден (вы хотите сделать коммит), рабочий процесс определён (читать staged-изменения, применять формат Conventional Commits), а вывод структурирован (сообщение коммита с конкретной формой).

Как структурировать навык

Каждый навык начинается как одна папка с одним файлом:

commit-message-writer/
└── SKILL.md

По мере роста навыки могут включать дополнительные файлы, которые агент загружает по мере необходимости:

commit-message-writer/
├── SKILL.md ← всегда загружается при срабатывании навыка
└── references/ └── examples.md ← загружается только когда агенту нужны примеры

Тело SKILL.md должно оставаться в пределах 500 строк. Если инструкции разрастаются за этот предел, перенесите вспомогательные детали в подпапку references/ и укажите агенту, когда читать эти файлы. Это сохраняет навык компактным — агент загружает только то, что нужно.

Для этого руководства достаточно одного SKILL.md.

Как написать описание

Поле description — это условие триггера. Оно определяет, когда ваш навык загружается, а когда нет. Большинство навыков не работают не потому, что инструкции неверны, а потому что описание не соответствует тому, как люди на самом деле просят о помощи.

Вот слабое описание:

description: Generates commit messages.

Оно будет срабатывать слишком редко. «Generate a commit message» загрузит его. «Write a commit for my changes» — вероятно, нет. «Summarize my staged diff» — точно нет, хотя все три запроса означают одно и то же.

Вот более сильное описание:

description: Generates structured commit messages following the Conventional Commits standard.
Use when you want to commit your changes and need a well-formatted message.
Triggers on "write a commit message", "commit my changes", "summarize my staged diff",
"what should my commit say", or any request to describe or document code changes for version control.

Паттерн такой: что делает навык + когда его использовать + конкретные фразы-триггеры. Фразы-триггеры охватывают разные способы, которыми разработчик может попросить об одном и том же.

Два правила для описаний:

Будьте конкретны в отношении вывода. «Generates commit messages» — расплывчато. «Generates structured commit messages following the Conventional Commits standard» точно сообщает агенту и пользователю, что они получат.

Будьте немного настойчивы. У агента есть естественная склонность к недостаточному срабатыванию навыков — обрабатывать запросы самостоятельно, а не загружать навык. Описание, которое явно перечисляет фразы-триггеры, противодействует этому. Вы не повторяетесь. Вы обучаете триггер.

Как писать инструкции

Тело файла SKILL.md — это место, где вы определяете, что делает агент при загрузке навыка. Хорошие инструкции следуют двум принципам.

Сначала генерируй, потом уточняй. Агент должен сразу производить результат, а не задавать уточняющие вопросы. Если ему нужно делать допущения — пусть делает их и отмечает, а не спрашивает. Вопросы перед выдачей результата создают трение и уничтожают саму ценность навыка.

Явно определяй формат вывода. Не говорите «напиши хорошее сообщение коммита». Укажите точную структуру, обязательные поля, ограничения по символам. Чем конкретнее формат вывода, тем стабильнее результаты.

Я убедился на практике: навыки без явного формата вывода деградируют быстро — уже на третьей-четвёртой сессии агент начинает импровизировать. Конкретная спецификация формата — это страховка от дрейфа.

Как создать навык commit-message-writer

Теперь создадим его. Создайте директорию навыка:

mkdir -p ~/.claude/skills/commit-message-writer

Примечание: PowerShell использует обратный апостроф (` «) для переноса строки, а не обратный слеш.

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\commit-message-writer"

Создайте файл SKILL.md внутри этой директории. Вот полное содержимое:

---
name: commit-message-writer
description: Generates structured commit messages following the Conventional Commits standard. Use when you want to commit your changes and need a well-formatted message. Triggers on "write a commit message", "commit my changes", "summarize my staged diff", "what should my commit say", or any request to describe or document staged changes for version control.
---

# commit-message-writer

You generate structured commit messages from staged git changes.

## How to invoke

Run `git diff --staged` to read the staged changes. If nothing is staged, tell the user
and suggest they run `git add` first.

Generate first. Do not ask clarifying questions before producing the commit message.
If you need to make assumptions about scope or type, make them and note them after the output.

## Output format

type(scope): short description

[body — optional, include if changes are non-trivial]

[footer — optional]

**Type** — choose one:
- `feat` — a new feature
- `fix` — a bug fix
- `docs` — documentation changes only
- `refactor` — code change that neither fixes a bug nor adds a feature
- `test` — adding or updating tests
- `chore` — build process, tooling, or dependency updates

**Scope** — the module, file, or area affected. Use the directory name or component name.
Omit if the change spans the entire codebase.

**Short description** — imperative mood, under 72 characters, no period at the end.
"Add user authentication" not "Added user authentication" or "Adds user authentication."

**Body** — what changed and why, not how. One bullet per logical change.
Skip if the short description is self-explanatory.

**Footer** — include `BREAKING CHANGE:` if the commit breaks backward compatibility.
Include `Closes #N` if it resolves a GitHub issue.

## Quality rules

- Never use "updated", "changed", or "modified" in the short description — be specific
- Never write "various improvements" or "misc fixes" — name what improved
- If more than three files changed across unrelated concerns, flag it:
  "These changes may be better split into separate commits: [list concerns]"
- The short description must be under 72 characters — count before outputting

## Example output

Input: staged changes adding a rate limiter to an API endpoint

feat(api): add rate limiting to /query endpoint

- Limits requests to 100 per minute per IP using Cloudflare's rate limit binding
- Returns 429 with Retry-After header when limit is exceeded
- Adds rate limit configuration to wrangler.toml

Closes #47

Сохраните этот файл. Навык создан.

Как установить и протестировать навык

Проверьте наличие файла

cat ~/.claude/skills/commit-message-writer/SKILL.md

Вы должны увидеть полное содержимое SKILL.md. Если возникает ошибка, проверьте путь к директории.

Протестируйте навык

Откройте Claude Code в любом git-репозитории со staged-изменениями. Введите:

/commit-message-writer

Агент прочитает ваш staged diff и сформирует сообщение коммита в соответствии с заданным форматом.

Можно также вызвать его естественным образом:

write a commit message for my staged changes
what should my commit say
summarize my diff for git

Все три варианта должны загрузить навык и сформировать структурированное сообщение коммита. Если навык не срабатывает на запросы на естественном языке, в описании нужно добавить больше триггерных фраз — см. раздел об улучшении ниже.

Протестируйте граничные случаи

Проверьте эти случаи перед тем, как полагаться на навык в продакшене:

• Запустите навык без staged-изменений — агент должен сообщить об этом и предложить выполнить git add
• Сделайте коммит с изменениями в несвязанных файлах — агент должен предложить разбить его на несколько коммитов
• Проверьте, что длина short description не превышает 72 символа в сгенерированном выводе

Как улучшать навык со временем

Первая версия любого навыка — это черновик. Вы улучшаете его, наблюдая, где он даёт непоследовательный или неверный вывод, и затем обновляя инструкции.

Когда навык срабатывает слишком редко

Если вы вводите «summarize my changes for git», а навык не загружается, добавьте эту фразу в список триггеров описания:

description: ... Triggers on "write a commit message", "commit my changes",
"summarize my staged diff", "summarize my changes for git", ...

Описание — ваш главный инструмент для исправления проблем с триггерингом.

Когда формат вывода начинает дрейфовать

Если агент начинает формировать сообщения коммитов, не соответствующие вашему формату — неверный тип, отсутствующий scope, тело в неправильном стиле — инструкции нужно сделать более явными. Добавьте конкретный пример, показывающий ошибку и правильный вывод:

## Common mistakes to avoid

Wrong: "Updated the authentication flow"
Right: "refactor(auth): simplify token validation logic"

Wrong: "Fixed bugs"
Right: "fix(api): handle null response from upstream service"

Конкретные контрпримеры эффективнее абстрактных правил.

Когда область применения расширяется

Если вы обнаруживаете, что хотите, чтобы навык выполнял смежные задачи — проверял сообщения коммитов, генерировал changelogs, писал описания PR — сопротивляйтесь желанию добавить всё в один навык. Создавайте отдельные навыки. Каждый навык должен хорошо делать одно дело. Стандарт Agent Skills разработан для композиции, а не для монолитных инструкций.

Типичные ошибки при создании навыков

На практике большинство проблем с навыками укладываются в три категории, и все они решаются редактированием SKILL.md, а не переустановкой.

Слишком широкое описание без триггерных фраз. Агент не знает, когда загружать навык, и либо игнорирует его, либо загружает в неподходящий момент. Решение — добавить конкретные фразы, которые вы реально используете в запросах.

Инструкции без примера вывода. Агент интерпретирует «структурированный формат» по-своему. Один конкретный пример в секции ## Example output стоит больше, чем три абзаца описания правил.

Один навык на все случаи жизни. Я сам допускал эту ошибку — пытался объединить генерацию коммитов, описания PR и changelog в один файл. Результат предсказуем: навык срабатывает непредсказуемо, а инструкции конфликтуют между собой. Один навык — одна задача.

Что делать дальше

Навык написания коммит-сообщений охватывает основной паттерн. Та же структура работает для любого повторяющегося рабочего процесса.

Описания pull request следуют той же схеме — читаем diff, применяем структуру, получаем согласованный результат. Триггерные фразы отличаются («write a PR description», «summarize my branch for review»), а формат вывода добавляет разделы для описания мотивации и тестирования, но структура SKILL.md идентична.

Чеклисты для code review хорошо работают как навыки, когда у вашей команды есть стандартный процесс проверки. Триггер — «review this code» или «check this PR», а инструкции кодируют то, что ваша команда реально проверяет: вопросы безопасности, покрытие тестами, соглашения об именовании.

Навык написания коммит-сообщений — это простейшая архитектура навыка: только инструкции. По мере того как ваши навыки становятся более специализированными, полезными становятся два других паттерна.

Первый добавляет директорию references/: навык voice-humanizer загружает файл CORPUS.md, содержащий опубликованные тексты автора, которые агент читает, когда нужно сверить результат с конкретным стилем. Второй добавляет правила качества и структурированные форматы вывода, которые делают результаты строже и согласованнее — именно этот паттерн использует spec-writer для отображения допущений прямо в тексте. На моём опыте переход от первого паттерна ко второму занимает один-два итерационных цикла: сначала вы видите, где агент отклоняется, потом фиксируете это в формате. Каждый из них использует ту же структуру SKILL.md, но на другом уровне сложности.

Начните только с инструкций. Добавляйте references/, когда агенту нужен внешний контекст. Добавляйте правила формата вывода, когда согласованность важнее гибкости.

Стандарт Agent Skills поддерживается в Claude CodeGitHub Copilot в в сравнении с Code, Cursor и Gemini CLI. Навык, созданный один раз, устанавливается во всех из них. Путь установки отличается в зависимости от агента, но формат SKILL.md одинаков для всех.

Навык написания коммит-сообщений, который вы только что создали, — это рабочий навык. Следующий займёт меньше времени. К третьему вы начнёте замечать рабочие процессы, которые повторяете, и сразу думать: это должно стать навыком.

В этом и есть смысл.

Ответы на эти вопросы могут быть для вас полезными

Можно ли использовать один и тот же навык в разных AI-агентах?

Да. Стандарт Agent Skills поддерживается в Claude CodeGitHub Copilot в в сравнении с Code, Cursor и Gemini CLI. Формат SKILL.md одинаков для всех — отличается только путь установки.

Что делать, если навык не срабатывает на мои запросы?

Откройте SKILL.md и добавьте в поле description конкретные фразы, которые вы используете. Описание — единственный механизм, по которому агент решает, загружать ли навык. Чем точнее фразы-триггеры, тем стабильнее срабатывание.

Сколько инструкций можно поместить в один SKILL.md?

Рекомендуемый предел — 500 строк. Если инструкции разрастаются, вынесите вспомогательные детали в подпапку references/ и укажите агенту, когда читать эти файлы.

Может ли навык выполнять код самостоятельно?

Нет. Навык — это markdown-файл с инструкциями. Он не имеет среды выполнения. Но он может инструктировать агента запускать команды с помощью его собственных инструментов — например, выполнить git diff --staged для чтения staged-изменений.

Стоит ли объединять несколько задач в один навык?

Нет. Один навык должен хорошо решать одну задачу. Стандарт Agent Skills разработан для композиции: лучше создать три узких навыка, чем один широкий, который срабатывает непредсказуемо.