Как писать скиллы

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

ДокументацияПак: Superpowersссылкаwriting-skills
Автор
Источник
obra/superpowers/skills/writing-skills @ 22f0b46
Лицензия
MIT

Об этом скилле

Что делает

Скилл относится к скиллу как к коду, а к запуску агента — как к тесту. До того как писать, вы даёте субагенту реалистичную задачу без скилла и записываете, где он ошибается и какими словами оправдывается. Потом пишете минимальный скилл, который отвечает ровно на эти ошибки, повторяете сценарий уже со скиллом и закрываете лазейки, пока агент не начнёт держать правило под давлением. Правки тоже в счёт: непроверенное изменение скилла — нарушение. Ещё скилл объясняет, как писать description (только когда применять скилл и никогда — пересказ шагов, иначе агент пойдёт по пересказу и не прочтёт тело), как выбирать форму указаний под тип ошибки и как проверять формулировки микротестами против контрольного прогона без указаний.

В references/ — шаблон SKILL.md с правилами имён и объёма (discovery.md), методика тестирования с видами давления (testing-skills-with-subagents.md), разобранная серия тестов вариантов CLAUDE.md (CLAUDE_MD_TESTING.md), таблицы отговорок и тревожные признаки (bulletproofing.md), принципы убеждения и границы их честного применения (persuasion-principles.md), правила блок-схем (flowcharts.md, graphviz-conventions.dot) и руководство Anthropic по написанию скиллов (anthropic-best-practices.md). render-graphs.js рисует dot-диаграммы из SKILL.md в SVG (node ./render-graphs.js ../some-skill из папки скилла); нужны Node и Graphviz.

Когда включать и когда не надо

Когда вы создаёте или меняете скилл, который будут загружать другие агенты, — особенно если он задаёт правило, которое агенту захочется обойти.

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

Как поставить и вызвать

Этот скилл мы не копируем: в его папке лежит копия документации Anthropic (anthropic-best-practices.md), на которую MIT автора не распространяется. Ставьте его из репозитория автора, ссылка ниже: всю папку skills/writing-skills целиком в папку скиллов вашего агента. Агент сам подхватывает скилл по описанию. Вызвать вручную:

  • Claude Code: /writing-skills или попросить скилл по имени.
  • Codex: $writing-skills.
  • Cursor: наберите / в чате Agent и выберите writing-skills.

Пример: /writing-skills Нужен скилл, который не даёт агенту править сгенерированные файлы. Сначала прогони сценарий без него и покажи, что идёт не так.

Обязательной основой скилл называет test-driven-development — поставьте и его. Две ссылки в SKILL.md ведут на using-superpowers, которого в нашем каталоге нет; нужные пути — ~/.claude/skills/ и общий для разных сред ~/.agents/skills/ — названы прямо в тексте.

Чем отличается от похожих

Создание скиллов с проверкой на тестах от Anthropic тоже гоняет субагентов со скиллом и без него, но сначала пишет черновик, потом оценивает прогоны по заранее заданным проверкам, сводит бенчмарк, показывает результаты в просмотрщике и подгоняет описание по запросам-триггерам. Скиллы по спецификации Agent Skills от Sentry делает упор на источники и структуру: происхождение каждого источника, SPEC.md, короткий SKILL.md, который отсылает к файлам в references/. Тексты для агентов: скиллы и AGENTS.md — только о формулировках, без процедуры проверки. Этот скилл начинает с провального прогона и сверяет текст с тем, как агенты ведут себя на деле, — это test-driven-development, перенесённый на текст. Приложенное руководство Anthropic прямо говорит, что набросать скилл агент может и без специального скилла; этот добавляет к тексту цикл проверки.

Установка

Скилл не скопирован в каталог. Установите его из репозитория автора.

Скилл написан на английском — агент поймёт его и ответит вам по-русски.

Открыть источник

Подключить через AnyModel API

Скилл работает на той модели, которую использует агент. Подключите Claude Code, Codex или Cursor к AnyModel и запускайте его на Claude, GPT, Gemini и других моделях по одному ключу — оплата за токены, без подписки.

Ещё из пака Superpowers

Брейншторм перед работой

Выясняет, что и зачем вы хотите построить: вопросы по одному, пересказ по частям, два-три способа на выбор и дизайн-документ, без одобрения которого код не пишется. Для новых фич и изменений, когда запрос оставляет главное открытым.

Параллельные субагенты

Раздаёт независимые задачи параллельным субагентам: каждому — одна область и самодостаточное задание с рамками и форматом отчёта, потом сверяет правки на конфликты и гоняет все тесты. Для случаев, когда упало сразу несколько несвязанных мест.

Выполнение плана по шагам

Выполняет план из writing-plans в текущей сессии без субагента на каждую задачу: задачи подряд через TDD, журнал прогресса и спорных решений на случай сжатия контекста, одно свежее ревью всей ветки в конце. Для случаев, когда ревью каждой задачи не нужно или субагентов нет.

Завершение ветки разработки

Завершает ветку: прогоняет тесты, предлагает слить локально, открыть PR или оставить как есть, после слияния снова проверяет тесты и убирает свой worktree, а работу удаляет только после «discard». Для случаев, когда реализация готова.

Как принимать код-ревью

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

Запрос код-ревью

Отдаёт законченную работу свежему субагенту-ревьюеру по шаблону: диапазон коммитов, план или требования, замечания по важности и вердикт о мерже. Для случаев, когда закончена задача или фича и впереди мерж в main.

Разработка через субагентов

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

Системная отладка

Не даёт агенту чинить наугад: сначала воспроизвести баг и найти первопричину, проверять по одной гипотезе, исправлять с падающим тестом, а после трёх неудачных правок пересмотреть устройство кода. Для любых багов, падений тестов и странного поведения.

TDD по методу Superpowers

Ведёт работу тестом вперёд: сначала тест и его падение, потом минимум кода и прогон всего набора; код, написанный до теста, удаляется. Для фич и багфиксов, когда агент норовит дописать тесты после кода.

Работа в git worktree

Выносит работу над фичей в отдельный git worktree: проверяет, не изолирован ли агент уже, предпочитает родной инструмент среды, следит за .gitignore, ставит зависимости и прогоняет тесты на старте. Для случаев, когда работа не должна попасть в текущую ветку.

Проверка перед словом «готово»

Не даёт агенту сказать «готово» или «тесты проходят», пока он заново не запустил проверку и не прочитал вывод целиком. Для случаев, когда агент докладывает об успехе, коммитит или открывает PR.

План реализации перед кодом

Превращает спецификацию в план для исполнителя, не знающего проекта: файлы, сигнатуры, интерфейсы между задачами, тесты с точными значениями и шаги TDD с ожидаемым выводом команд. Для многошаговых задач, когда спецификация готова, а кода ещё нет.