Урок 17.15. Свои скиллы: написание и тестирование

Дополнительные источники: https://github.com/obra/superpowers/blob/main/docs/testing.md, https://github.com/obra/superpowers/blob/main/AGENTS.md

Зачем это нужно

Финальный блок модуля: Superpowers не только поставляет скиллы — он поставляет методологию их написания. Скилл writing-skills (самый большой в библиотеке, 681 строка) применяется при создании, редактировании и проверке скиллов до деплоя — своих и чужих. Для курса он замыкает тему модуля 6 (написание скиллов — уроки 6.3 и 6.6): здесь — первоисточник и самая откалиброванная методология.

Здесь же — политика контрибуции: AGENTS.md проекта честно предупреждает, что почти все PR от агентов отклоняются (94% rejection rate), новые скиллы от сообщества обычно не принимаются, а изменения существующих требуют эвал-доказательств. Это практический урок о том, где проходит граница между «свои скиллы» и «скиллы в ядре».

Основная идея

Формула скилла: «Writing skills IS Test-Driven Development applied to process documentation» — написание скиллов и есть TDD, примененный к документации процессов. Вы пишете тест-кейсы (давление-сценарии с сабагентами), наблюдаете их падение (базовое поведение без скилла), пишете скилл (документация), наблюдаете прохождение (агенты соблюдают), рефакторите (закрываете лазейки). Ключевой принцип: «If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing» — если вы не видели, как агент падает без скилла, вы не знаете, учит ли скилл правильному.

flowchart LR A["RED: давление-сценарии БЕЗ скилла — зафиксировать нарушения дословно"] --> B["GREEN: минимальный скилл против этих нарушений"] B --> C["REFACTOR: новые рационализации → явные контрмеры"] C --> B

Обязательный фон: скилл test-driven-development (урок 17.10) — тот же RED-GREEN-REFACTOR, адаптированный к документации. Ирония методологии намеренная: скилл, который принуждает агентов к TDD, сам написан по TDD.

Что такое скилл и когда его создавать

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

Создавать, когда: техника не была интуитивно очевидной; вы сошлетесь на нее снова в других проектах; паттерн применим широко (не проектно-специфичен); другим это принесет пользу. Не создавать для: одноразовых решений; практик, задокументированных в стандартах; проектных конвенций (им место в инструкциях проекта); механических ограничений (проверяется регуляркой/валидацией — автоматизируйте; документация — для суждений).

Три типа: техника (конкретный метод с шагами — condition-based-waiting, root-cause-tracing), паттерн (способ мышления о проблеме), справочник (API-доки, синтаксис, тулинг).

Структура SKILL.md

Frontmatter (YAML): два обязательных поля — name и description; максимум 1024 символа; имя — буквы, цифры, дефисы; описание — третье лицо, только когда применять (не что делает), начинать с «Use when…», с конкретными симптомами и контекстами; по возможности до 500 символов.

Каркас тела: Overview (что это, ядро в 1-2 предложениях) → When to Use (симптомы, случаи; когда НЕ применять) → Core Pattern (для техник — сравнение до/после) → Quick Reference (таблица/списки для сканирования) → Implementation → Common Mistakes → опционально Real-World Impact.

Оптимизация обнаружения (SDO)

Будущий агент должен найти скилл. Четыре рычага:

1. description = When to Use, НЕ What the Skill Does. Самое тонкое правило скилла, и оно контринтуитивно: описание, пересказывающее workflow, создает короткий путь, которым агенты воспользуются. Тесты проекта показали: описание «code review between tasks» заставило агента сделать одно ревью, хотя диаграмма скилла требовала два (соответствие спеке, затем качество); описание без пересказа («Use when executing implementation plans with independent tasks») — агент прочитал диаграмму и прошел два этапа. «Descriptions that summarize workflow create a shortcut agents will take. The skill body becomes documentation agents skip» — описания-пересказы создают ярлык; тело скилла превращается в документацию, которую пропускают.

yaml
# ❌ ПЛОХО: пересказывает workflow — агенты последуют описанию, не читая скилл
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ✅ ХОРОШО: только условия срабатывания
description: Use when executing implementation plans with independent tasks in the current session

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

2. Покрытие ключевых словами: сообщения об ошибках («Hook timed out», ENOTEMPTY, race condition), симптомы (flaky, hanging, zombie, pollution), синонимы (timeout/hang/freeze; cleanup/teardown/afterEach), инструменты — реальные команды, имена библиотек, типы файлов.

3. Описательные имена, глаголы впереди: creating-skills, а не skill-creation; condition-based-waiting, а не async-test-helpers; называть по действию или ядру инсайта (root-cause-tracing > debugging-techniques); герундий (-ing) хорош для процессов.

4. Экономия токенов: стартовые и часто-загружаемые скиллы входят в каждый диалог. Цели по словам: getting-started — меньше 150; часто-загружаемые — меньше 200; прочие — меньше 500. Приемы: детали флагов — в --help (не в SKILL.md); кросс-ссылки вместо повторов («REQUIRED SUB-SKILL: Use superpowers:X» — явно, без @-ссылок, которые форс-грузят файлы и жгут 200k+ контекста); сжатые примеры (20 слов против 42).

Форма подбирается под тип отказа

Центральный таблица скилла (Match the Form to the Failure): форма, которая бронебойна для одного типа отказа, вредит для другого.

Базовый отказ	Правильная форма	Неправильная форма
Нарушает правило под давлением (знает лучше, но делает)	Запрет + таблица рационализаций + красные флаги	Мягкие «предпочтительно…», «рассмотрите…»
Соблюдает, но вывод не той формы (раздутый промпт, замытый вердикт)	Позитивный рецепт/контракт: что вывод ЕСТЬ — части, по порядку	Список запретов («не пересказывай», «не нюй…»)
Пропускает обязательный элемент из того, что уже производит	Структурно: REQUIRED-поле или слот в шаблоне	Прозаические напоминания у шаблона
Поведение зависит от условия	Условие на наблюдаемом предикате («если бриф существует — ссылаться»)	Безусловное правило + исключения

Почему запреты вредят для формирования вывода: под конкурирующим стимулом («сделай промпт самодостаточным») агенты торгуются с «не X». В wording-тестах рука с запретом произвела больше нежелаемого контента, чем рецепт — и трендировала хуже контроля без гайданса вообще. Правила любой формы: без клаузул нюансов («не X, если это важно» — reopen переговоров; единственная выигравшая рецепта с одной клаузулой деградировала до noisy в тех же тестах); исключения не скоупируют («лимит не касается кода» — все равно душит код: реструктурируйте так, чтобы правило не дотягивалось).

Бронебойность против рационализаций

Для дисциплинарных скиллов (как TDD): агенты умны и под давлением найдут лазейки. Приемы (все уже видны в скиллах модуля):

закрыть каждую лазейку явно — не только правило, но и запрет обходов: «Write code before test? Delete it. Start over. No exceptions: don't keep as reference / don't adapt / don't look / delete means delete»;
отсечь «дух vs буква» ранним фундаментальным принципом: «Violating the letter of the rules is violating the spirit of the rules»;
таблица рационализаций из базового тестирования: каждая отмазка агентов — в таблицу с «реальностью»;
список красных флагов для самопроверки;
дополнить description симптомами грядущего нарушения («before writing implementation code»).

RED-GREEN-REFACTOR для скиллов

RED: давление-сценарии с сабагентами без скилла; зафиксировать дословно: какие выборы, какие рационализации (цитируя), какие давления триггерили нарушения.
GREEN: минимальный скилл против этих конкретных рационализаций — не контент для гипотетических случаев; те же сценарии со скиллом — агент соблюдает.
REFACTOR: новая рационализация — явная контрмера; перепроверка до бронебойности.

Микро-тесты формулировок до полных сценариев (полные дороги, верифицируют формулировку первыми): (1) один свежий образец на вызов — raw API или single-shot сабагент; системный промпт — реалистичный контекст гайденса (весь скилл/шаблон, не гайденс в изоляции), пользовательское сообщение — задача, соблазняющая к отказу; (2) всегда контроль без гайденса: контроль не проявляет отказ — чинить нечего, стоп; (3) 5+ повторений на вариант: единичный образец лжет; (4) читать глазами каждый помеченный мач (эхо шаблона и цитаты контрпримеров мимикрируют под хиты); (5) дисперсия — метрика: пять разных интерпретаций на пяти повторах — формулировка не связывает; затянуть форму, не добавляя слов.

Тестирование типов скиллов: дисциплинарные — академические вопросы + давление + комбинированные давления; техники — применение + вариации + пробелы в инструкциях; паттерны — распознавание + применение + контрпримеры; справочники — retrieval + применение + покрытие частых случаев. Полная методология — testing-skills-with-subagents.md в каталоге скилла.

Железный закон тот же: NO SKILL WITHOUT A FAILING TEST FIRST — для новых скиллов и правок существующих. «Просто добавлю секцию» — такое же нарушение; непроверенные изменения не хранятся «как референс»; delete means delete. И стоп-правило: после каждого скилла — обязательный процесс деплоя; не писать скиллы пачкой, не переходить к следующему до верификации текущего: «Deploying untested skills = deploying untested code».

Тесты Superpowers: tests/ и evals/

docs/testing.md разделяет два вида тестов:

tests/ — работает ли не-LLM код плагина: bash/node/python интеграционные тесты (brainstorm-server JS, загрузка OpenCode-плагина, codex-plugin sync, анализ-утилиты). Запуск — через run-*.sh или npm test соответствующего каталога.
evals/ — ведут ли себя агенты правильно на реальных LLM-сессиях: Python-харнес (лаборатория superpowers-evals, клонируется в evals/), которая гоняет реальные tmux-сессии Claude Code / Codex / Gemini CLI с LLM-актором и верифаером, оценивающими соблюдение скиллов. CLI-харнес — Quorum: гоняет реальные CLI через Gauntlet QA-агента и оценивает по критериям приемки сценариев плюс детерминистические пост-проверки. Сценарии живут в evals/scenarios/<name>/. Быстрый локальный запуск:

bash
cd evals
bun install
export SUPERPOWERS_ROOT=/path/to/superpowers
bun run quorum run scenarios/triggering-test-driven-development --coding-agent claude
bun run quorum show <run-dir>

Оговорки: сценарии Quorum медленные (3-30+ минут) и гоняют реальные LLM-сессии в пермиссивных режимах; для публичного CI безопасны только статические гейты (bun run check, bun run quorum check).

Политика контрибуции: почему PR от агентов отклоняют

AGENTS.md открывается честно: «This repo has a 94% PR rejection rate» — 94% PR отклоняются; почти все отклоненные — от агентов, не читавших правила. Требования: шаблон PR заполнен целиком, без плейсхолдеров; поиск существующих PR (открытых и закрытых) до открытия; PR таргетирует ветку dev, не main; субмитер идентифицирует себя — модель, каркас, версии, все плагины (скрытие авторства — причина закрытия); обязательное свидетельство участия человека (ревью полного диффа).

Что не примут: сторонние зависимости (Superpowers — zero-dependency by design; новая зависимость — отдельный плагин); «комплаенс»-правки скиллов под чужие гайдлайны — контент скиллов откалиброван эвалами, бар изменений очень высок; проектная/личная конфигурация; массовые «spray-and-pray» PR (одна проблема — один PR); спекулятивные фиксы без реального симптома; доменно-специфичные скиллы («полезно ли это человеку над другим проектом?» — нет: отдельный плагин); фиктивный контент. Новый harness — принимается, но с транскриптом, доказывающим работу end-to-end (приемочный тест из урока 17.2).

Изменения скиллов требуют эвализации: использовать writing-skills, провести adversarial pressure-тестирование, показать до/после в PR; тщательно откалиброванный контент (таблицы Red Flags, списки рационализаций, «human partner») не трогать без доказательств улучшения. И — понять проект, прежде чем предлагать: «"your human partner" — намеренно, не взаимозаменяемо с "the user"» — терминология проекта откалибрована.

Практика

Возьмите процедуру, которую вы повторяете в работе с агентом (правило в CLAUDE.md/AGENTS.md, которое агент периодически нарушает под давлением). Определите тип отказа по таблице Match the Form: нарушение под давлением? вывод не той формы? пропущенный элемент?
По типу отказа выберите форму и напишите фрагмент скилла: для дисциплинарного — правило + 3 строки таблицы рационализаций; для формирующего — рецепт/контракт вывода.
Напишите description по правилам SDO: «Use when…», без пересказа процесса, с симптомами. Проверьте: сработал бы ваш description как триггер?
Спланируйте микро-тест: системный промпт = ваш скилл, сообщение = задача, соблазняющая к отказу; контроль без гайденса; 5 повторений.

Краткое резюме

writing-skills — TDD для документации: давление-сценарии без скилла (RED) → минимальный скилл против зафиксированных рационализаций (GREEN) → закрытие лазеек (REFACTOR). Скилл, не видевший падения агента без него, не доказывает, что учит правильному.

description — только условия срабатывания: пересказ workflow создает ярлык, тело скилла пропускается.
Форма — под тип отказа: запреты для нарушений под давлением; рецепты для формы вывода; структурные слоты для пропущенных элементов; условия на наблюдаемых предикатах. Без клаузул нюансов.
Микро-тесты формулировок (контроль без гайденса, 5+ повторений, чтение каждым глазом) — до дорогих давление-сценариев.
Тесты Superpowers: tests/ — инфраструктура плагина; evals/ (Quorum) — поведение агентов на реальных сессиях.
Контрибуция: 94% отклонений; новые скиллы обычно не принимаются; правки — только с эвал-доказательствами.

Вопросы для самопроверки

Что означает «writing skills IS TDD applied to process documentation»? Что играет роль теста, кода и рефакторинга?
Почему description не должен пересказывать workflow скилла? Расскажите эксперимент с двумя ревью.
Опишите таблицу Match the Form to the Failure: какие четыре типа отказа и почему запреты вредят формирующим задачам?
Что такое микротесты формулировок и зачем нужен контроль без гайданса?
Чем tests/ отличается от evals/ и почему живые эвалы небезопасны для публичного CI?
Почему «комплаенс»-правки и доменные скиллы отклоняются, а новый harness — принимается?

Что дальше

Свои скиллы написаны по методологии; предпоследний урок, 17.16, собирает все в сквозной цикл: артефакты Superpowers в его собственном репозитории (догфудинг) — от дизайн-документа до merge.

Источники

https://github.com/obra/superpowers/blob/main/skills/writing-skills/SKILL.md