раздел 04

Сделать свой skill

Разберём на примере Claude Agent Skills - формат SKILL.md. Принципы те же и для правил Cursor, и для AGENTS.md в Codex: главное - ясно сказать, что навык делает и когда применять.

Шаг 1. Создать папку

Имя папки - это имя навыка. Кладите её в .claude/skills (для проекта) или ~/.claude/skills (для всех ваших проектов).

.claude/
  skills/
    changelog-entry/
      SKILL.md

Шаг 2. Написать SKILL.md

Минимальный навык - это только SKILL.md с frontmatter и инструкциями.

---
name: changelog-entry
description: Добавляет запись в NOTES.md по стандарту проекта. Применять, когда сделано значимое изменение и нужно записать его в журнал.
---

# Запись в NOTES.md

Новые записи добавляй сверху файла. Формат:

## YYYY-MM-DD
### Добавлено / Изменено / Исправлено / Удалено
- Краткое описание, 3-7 строк.

Мелкие правки не записывай.

Шаг 3. Главное - description

Поле description - это триггер. По нему агент решает, подключать навык или нет. Если описание расплывчатое, навык просто не сработает в нужный момент.

description отвечает на два вопроса: что навык делает и когда его применять. Второй вопрос - важнее.

Хорошо
Добавляет запись в NOTES.md по стандарту проекта. Применять, когда сделано значимое изменение.
Плохо
Помогает с журналом изменений. Расплывчато: агент не поймёт, в какой момент брать навык.

Принципы хорошего описания

  • Называйте триггер. Не "помогает с коммитами", а "применять, когда нужно сделать коммит".
  • Пишите для агента как для человека. Представьте, что объясняете коллеге, в каком случае открыть эту инструкцию.
  • Конкретика вместо общих слов. Имена файлов, типы задач, ключевые слова, по которым видно, что навык уместен.
  • Один навык - одна задача. Если описание начинается с "и то, и сё", разбейте на два навыка.

Шаг 4. Тело и ресурсы

Ниже frontmatter - инструкции в Markdown: шаги, правила, примеры. Если навыку нужны скрипты или шаблоны, положите их рядом в папки scripts, references, assets и ссылайтесь на них из тела. Тело подгружается только при использовании навыка, так что объёмные справочники почти ничего не стоят, пока не понадобятся.

Проверка

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