Библиотека скиллов: SKILL.md для агента (Phase 6)
Фаза 6 серии Harness Engineering: скилл (skill) — это SKILL.md, кодирующий повторяемую процедуру («как сделать рекуррентную задачу»), который агент сам подгружает по триггеру из поля description. Учимся отличать скилл от lessons-ledger (тот хранит «что НЕ повторять»), искать кандидатов в скиллы по коммит-истории, писать make-or-break поле description с фразами-триггерами, структурировать SKILL.md (When to use / Steps / DoD / Anti-patterns / Examples) и подключать библиотеку в контекст-файл агента. Стек-агностично, с копируемым шаблоном.
СреднийDevOps с AI20 минClaude Code, SKILL.md, CLAUDE.md, git
1
Скилл — это процедура, а не документация и не разовый промпт
Если вы ловите себя на том, что в третий раз вставляете в чат один и тот же длинный промпт «вот как у нас пишется тест к компоненту: сначала…», — это сигнал, что пора завести скилл (skill). Скилл — это SKILL.md, который кодирует ПОВТОРЯЕМУЮ ПРОЦЕДУРУ: «как сделать рекуррентную задачу на ЭТОМ проекте». Не теория, не справочник — пошаговый рецепт действия.
Ключ, отличающий скилл от обычного файла в docs/: агент подгружает его САМ. У SKILL.md есть поле description с триггером; когда задача пользователя совпадает с триггером, агент автоматически втягивает тело скилла в контекст. Поэтому скилл — это не documentation (её агент читает, только если вы указали путь) и не разовый промпт (он живёт в истории одного треда и теряется).
Граница скоупа честная: скилл описывает ПРОЦЕДУРУ, а не форсит её. Если правило обязано соблюдаться всегда (границы импортов, строгие типы) — ему место в барьере из Phase 3, а не в скилле. Скилл хорош там, где есть стабильная последовательность шагов, но запуск контекстный: «когда добавляешь новый эндпоинт — делай так».
🟩 Скилл (SKILL.md)
- Повторяемая процедура: «как сделать X»
- Агент подгружает сам по триггеру
- Живёт в репо, переиспользуется в каждом треде
🟦 Документация
- Объясняет «что есть», не «как делать»
- Агент читает, только если дать путь
- Описывает систему, а не действие
🟨 Разовый промпт
- Длинный текст, вставленный в один чат
- Теряется вместе с историей треда
- Каждый раз набирается заново
Тест «скилл или нет»: если вы уже дважды объясняли агенту одну и ту же последовательность шагов почти слово в слово — это кандидат в скилл. Объясняли разово под уникальную задачу — нет.
2
Скилл vs lessons-ledger: «как ДЕЛАТЬ» против «что НЕ повторять»
Скилл легко спутать с lessons-ledger из Phase 5.5 — оба про «накопленное знание о проекте», оба текстовые. Но они хранят противоположные вещи и не взаимозаменяемы.
Скилл хранит позитивную процедуру: «как ДЕЛАТЬ рекуррентную задачу» — стабильную последовательность шагов, которую вы хотите повторять одинаково. Lessons-ledger хранит негатив: «что НЕ повторять» — коррекции конкретных ошибок агента, накопленные после фразы «нет, не так». Скилл вы пишете проактивно, заметив повтор задачи; запись в ledger появляется реактивно, после ошибки.
Они дополняют друг друга. Часто ledger подсказывает, что пора завести скилл: если одна и та же коррекция «снова забыл шаг X в этой процедуре» всплывает раз за разом, значит, у процедуры нет скилла — заведите его, и шаг X станет частью Steps. А если коррекция детерминируема («снова импорт в обход слоя») — ей место не в скилле и не в ledger, а в барьере Phase 3. Три разных дома для трёх разных типов знания.
| Тип знания | Что хранит | Где живёт |
|---|---|---|
| Скилл (SKILL.md) | «Как ДЕЛАТЬ» — позитивная процедура | .claude/skills/, триггер по description |
| Lessons-ledger | «Что НЕ повторять» — коррекции ошибок | Реестр уроков, читается на старте сессии |
| Барьер (Phase 3) | Детерминируемое правило, форсится машиной | Линтер / тест / скрипт в pre-commit + CI |
Спросите себя: правило срабатывает по триггеру задачи или после ошибки? По триггеру «когда делаешь X» — скилл. После «нет, не так» — ledger. А если его можно проверить машиной — это вообще не текст, это барьер.
3
Где искать кандидатов: майним повторы из коммит-истории
Главное правило этой фазы: скиллы НЕ выдумываются «по best practice», а добываются из РЕАЛЬНЫХ повторов на этом проекте. Цель — найти 3–5 рекуррентных задач, которые на проекте уже делались много раз. Источник — не фантазия, а коммит-история и структура кода.
Как майнить: пробегитесь по git log и сгруппируйте коммиты по типу работы. Какие задачи повторяются месяц за месяцем? «add … endpoint», «add … page», «test for …», «bump … to v…» — это и есть скелеты ваших скиллов. Параллельно посмотрите, где в коде есть очевидный паттерн-по-образцу: папка с двадцатью однотипными модулями означает, что «создать новый модуль по образцу X» — рекуррентная задача с устоявшейся процедурой.
Ниже — универсальные формы кандидатов, стек-агностичные. Но не берите их как готовый список: ваши реальные кандидаты — это пересечение этих форм с тем, что РЕАЛЬНО повторяется в вашем git log. Скилл на задачу, которая случилась один раз, — это мёртвый груз, который агент будет грузить в контекст зря.
Универсальные формы кандидатов (бери ТОЛЬКО те, что реально повторяются)
Написать тест к компоненту / функции / модулю
Создать новый модуль по образцу X
Добавить новый эндпоинт / страницу / сценарий
Рефакторинг по образцу X (миграция на новый паттерн)
Триаж продакшн-бага: от репорта к воспроизведению
Процедура релиза / bump зависимости с breaking changes
Задача, которая случилась РОВНО один раз
Порог для скилла: задача повторилась 3+ раз И имеет стабильную последовательность шагов. Повторилась, но каждый раз по-разному — рано: сначала процедура должна устояться, иначе вы зафиксируете шум.
4
Структура SKILL.md: шаблон, который агент читает как рецепт
У SKILL.md фиксированная форма: frontmatter с двумя полями (name в kebab-case и description) плюс тело из пяти секций. Каждая секция несёт нагрузку, без воды.
When to use — конкретные ситуации, в которых скилл применяется (это дублирует и уточняет триггер для человека-читателя). Steps — пошаговая процедура без «бла-бла», ровно те действия, что вы устали повторять. Definition of Done — по каким признакам задача считается закрытой (тот же DoD-словарь, что в Phase 1 и Phase 3). Anti-patterns — что НЕ делать: сюда стекаются коррекции из lessons-ledger, относящиеся к этой процедуре. Examples — РЕАЛЬНЫЙ пример с этого репо, с конкретными путями к файлам: именно он превращает абстрактный рецепт в «делай по аналогии вот с этим».
Главный приём — Examples с настоящими путями. Скилл без живого примера из репо агент трактует как угодно; скилл со ссылкой «смотри, как это сделано в <реальный-путь>» даёт ему якорь, и результат становится предсказуемым. Ниже — копируемый шаблон; пути в нём замените на свои.
---
name: add-endpoint # kebab-case, уникально / unique
description: >
Use when adding a NEW HTTP endpoint / route / handler to the API.
Triggers: "add an endpoint", "new route", "create a handler for",
"expose ... over the API", "добавь эндпоинт", "новый роут".
---
# Add a new endpoint
## When to use
- A new public route/handler is needed (CRUD, action, webhook).
- NOT for: changing an existing handler's logic (that's a normal edit).
## Steps
1. Create the handler next to its siblings (see Examples for the folder).
2. Wire validation of the request shape at the boundary.
3. Register the route where the router is assembled.
4. Add a test mirroring the nearest existing endpoint test.
5. Update the API list/docs if the project keeps one.
## Definition of Done
- Route reachable; request/response shapes validated.
- A test exists and passes; existing tests untouched (no .skip, no loosened asserts).
- Boundary linter + type check are green (Phase 3 barriers).
## Anti-patterns
- Business logic inside the handler (keep it in the domain layer).
- Copy-pasting a sibling without renaming its identifiers.
- Skipping the test "because it's trivial".
## Examples
- Reference handler: <path/to/handlers/get_user> # adapt to your repo
- Reference test: <path/to/handlers/get_user_test> # adapt to your repo
- Router assembly: <path/to/router> # adapt to your repoСекция Anti-patterns — это мост к lessons-ledger: когда повторяющаяся коррекция относится к конкретной процедуре, её место не в общем реестре, а здесь, рядом со Steps. Так урок попадает в контекст ровно тогда, когда задача его триггерит.
5
Поле description — make-or-break: триггер решает всё
Можно написать идеальный SKILL.md и ни разу его не запустить — если поле description расплывчатое. Это поле не для людей: по нему агент решает, втягивать тело скилла в контекст или нет. Размытое description не срабатывает; острое, с характерными фразами-триггерами, срабатывает надёжно.
Разница на примере. «Helps with API work» — провал: под это подходит что угодно и ничего конкретно, агент не понимает, когда это релевантно. «Use when adding a new HTTP endpoint/route/handler. Triggers: "add an endpoint", "new route", "expose … over the API", "добавь эндпоинт"» — попадание: есть точная ситуация И буквальные фразы, которые пользователь скажет. Включайте оба языка, если работаете на двух.
Правило написания: опишите ситуацию запуска + перечислите 3–5 характерных фраз, которыми пользователь реально формулирует задачу (а не как вы её называете внутри команды). Думайте как поисковый запрос: какие слова произнесёт человек в тот момент, когда этот скилл нужен? Их и кладите в description. Это поле дороже всего тела — его стоит отладить экспериментально: задайте задачу естественной формулировкой и проверьте, подтянулся ли скилл.
✅ Острый триггер — срабатывает
- Точная ситуация запуска: «когда добавляешь эндпоинт»
- 3–5 буквальных фраз, которые скажет пользователь
- Оба языка, если работаете на двух
❌ Размытый триггер — молчит
- «Helps with API work» — подходит ко всему
- Внутренний жаргон команды вместо слов юзера
- Идеальное тело, которое никогда не подгружается
Отлаживайте description как поисковый запрос: сформулируйте задачу так, как сказал бы коллега «с улицы», и проверьте, подтянулся ли скилл. Не подтянулся — добавьте недостающую фразу в триггер, а не переписывайте Steps.
6
Подключение в контекст-файл + место в серии
Скиллы должны быть видимы агенту. Достаточно одной строки в контекст-файле из Phase 1: в CLAUDE.md / AGENTS.md добавьте «Available skills: see .claude/skills/, triggered automatically by description». Для агентов, которые не делают авто-триггер по description, то же тело SKILL.md работает как сохранённый плейбук/промпт — вы просто подаёте его руками, когда наступает ситуация из When to use. Процедура в файле, а не в голове, — вот что переносимо между агентами.
Definition of Done фазы: в репо ≥3 SKILL.md, каждый ссылается на РЕАЛЬНЫЕ пути проекта в Examples, и контекст-файл обновлён строкой про библиотеку скиллов. Не больше: лучше три рабочих скилла на реальных повторах, чем пятнадцать «на будущее», которые засоряют выбор агента.
Где это в серии. Скиллы — позитивная сторона накопленного знания (как ДЕЛАТЬ); они дополняют lessons-ledger (что НЕ повторять) и барьеры Phase 3 (что форсится машиной). По-настоящему универсальные скиллы (триаж бага, релиз) станут материалом для migration capsule в Phase 8 — шаблонного репо, с которого стартуют новые проекты; проектно-специфичные («новый модуль по нашему образцу») остаются в проекте. Дальше — Phase 7: workflow и worktrees. А карта всех фаз и связи между ними — в хабе серии.
Definition of Done — Phase 6
≥3 SKILL.md, добытых из реальных повторов (git log), а не выдуманных
У каждого острое description с фразами-триггерами
Examples ссылается на РЕАЛЬНЫЕ пути этого проекта
Контекст-файл (CLAUDE.md/AGENTS.md) обновлён строкой про библиотеку
Универсальные скиллы помечены как кандидаты в migration capsule (Phase 8)
Пятнадцать скиллов «на будущее» без реальных повторов
Помечайте скилл как «universal» или «project-specific» прямо в момент написания. Это бесплатно сейчас и экономит часы в Phase 8: migration capsule собирается из universal-скиллов одной выборкой, а не археологией по всему репо.
Результат
Phase 6 собрана: вы перестали в каждом треде заново вставлять длинные промпты и завели библиотеку скиллов — SKILL.md, кодирующих повторяемые процедуры, которые агент подгружает сам по триггеру. Вы умеете отличать скилл («как ДЕЛАТЬ») от lessons-ledger («что НЕ повторять») и от барьера Phase 3 (что форсится машиной), искать кандидатов по реальным повторам в git log (а не выдумывать), структурировать SKILL.md (When to use / Steps / DoD / Anti-patterns / Examples с реальными путями) и — главное — писать make-or-break поле description с фразами-триггерами, без которого даже идеальный скилл не срабатывает. DoD: ≥3 SKILL.md на реальных путях, контекст-файл обновлён. Дальше — Phase 7 (workflow и worktrees); универсальные скиллы поедут в migration capsule на Phase 8.