Lab: пишем свой skill

Что получится

В Cadence появится skill проекта .claude/skills/database-migrations/SKILL.md с процедурой изменения схемы БД. Из файла инструкций проекта уйдут и сама процедура, и строка-указатель на неё. Вы проверите, что описание skill-а попало в список skills, а потом поручите агенту изменить схему и увидите в transcript-е, что он сам вызвал skill и прошёл его шаги: миграция, seed-скрипт, reseed, проверка типов.

Указатель при этом меняет место, но не исчезает.

Подготовка

• Стенд из раздела 1: Claude Code и учебный репозиторий Cadence с установленными зависимостями.
• Отдельная git-ветка в Cadence для этого Lab-а, чтобы потом легко откатиться.
• Шаги миграции в Cadence: либо в файле инструкций проекта, либо в docs/database-migrations.md, если вы делали практику из 5.2.
• Bite-ы 5.2–5.4: паттерн «документ плюс указатель», устройство skill-а и уровни хранения.

Шаги

1. Запустите claude в корне Cadence и наберите /skills. Запишите, какие skills в списке и у каких из них есть описание. Это исходная картина: что агент видит до ваших изменений.

2. Выполните /context и запишите две строки: сколько занимают файлы инструкций и сколько — skills.

3. Попросите агента перенести процедуру в skill проекта. Не вызывайте никакой skill вручную — пусть агент сам решит, что ему нужно:

   Move the database migration steps into a project skill at
   .claude/skills/database-migrations/SKILL.md. Write a description that says
   when to use it. Then remove the steps and any pointer to them from AGENTS.md,
   and delete docs/database-migrations.md if it exists.

   Агент создаст папку skill-а, SKILL.md и уберёт старые следы процедуры.

4. Откройте .claude/skills/database-migrations/SKILL.md и проверьте frontmatter. Первая строка файла — ---, есть name и description, и описание начинается со сценария: изменение схемы, добавление или изменение колонки или таблицы. Если описание говорит, что skill делает, но не когда его использовать, допишите условие сами.

5. Выполните /clear и снова /skills. В списке должен появиться database-migrations с вашим описанием. Claude Code отслеживает .claude/skills/ и подхватывает новый skill без перезапуска.

6. Выполните /context и сравните с шагом 2: файлы инструкций стали меньше, а skills — немного больше, на одно описание.

7. Поручите агенту изменить схему:

   In the purchases table, rename pricePaid to amountPaid.

8. Нажмите Ctrl+O и найдите в transcript-е вызов skill-а database-migrations. Он должен произойти до генерации миграции, в момент, когда агент понял, что меняет схему.

9. Если npm run db:generate остановится на интерактивном вопросе (например, переименовать колонку или создать новую), агент не сможет ответить сам. Запустите команду в своём терминале, выберите переименование и напишите агенту, что миграция сгенерирована.

10. Дождитесь, пока агент закончит, и посмотрите, какие шаги он назвал в итоге. Это должны быть шаги из вашего skill-а: обновить seed-скрипт, сделать reseed, запустить проверку типов.

Проверка результата

Выполните в корне Cadence:

ls .claude/skills/database-migrations/
grep -rn "pricePaid" app scripts
npm run db:seed
npm run typecheck

Результат засчитывается, если:

• в папке skill-а есть SKILL.md;
• grep ничего не находит: старого имени не осталось ни в схеме, ни в seed-скрипте;
• npm run db:seed и npm run typecheck завершаются без ошибок;
• в файле инструкций проекта нет ни шагов миграции, ни строки-указателя на них;
• в transcript-е шага 8 есть вызов database-migrations.

Если не получилось

• Skill не появился в /skills. Проверьте путь: файл должен называться ровно SKILL.md и лежать в .claude/skills/<skill-name>/. Если первая строка SKILL.md — не ---, Claude Code не читает frontmatter и считает весь файл телом skill-а.
• Skill есть в списке, но агент его не вызвал. Проверьте, что в description есть слова, которыми вы описали задачу: «schema», «column», «table». Запустите Claude Code с --debug, чтобы увидеть ошибку разбора YAML, если она есть. В крайнем случае вызовите /database-migrations вручную и перепишите описание.
• Агент прошёл процедуру, но пропустил seed-скрипт. Добавьте в начало SKILL.md строку о том, что каждое изменение схемы попадает и в scripts/seed.ts. Самое важное держите в начале файла: после compaction Claude Code сохраняет только начало вызванного skill-а.

Проверь себя

Источники

• Anthropic, Extend Claude with skills
• Anthropic, Commands
• Anthropic, Interactive mode
• По мотивам AI Coding Crash Course, AI Hero