Написание скиллов

Написание скиллов — это TDD (разработка через тестирование), применённая к документации процессов.

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

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

Обязательный фон: Необходимо понимать superpowers:test-driven-development. Этот скилл адаптирует TDD к документации.

Что такое скилл?

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

Скиллы — это: многократно используемые техники, паттерны, инструменты, справочные руководства

Скиллы — это НЕ: нарративы о том, как вы однажды решили проблему

TDD для скиллов

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

Создавайте, когда:

• Техника не была для вас интуитивно очевидной
• Вы будете обращаться к ней снова в разных проектах
• Паттерн применим широко (не специфичен для проекта)
• Другие выиграют от него

Не создавайте для:

• Разовых решений
• Стандартных практик, хорошо задокументированных в другом месте
• Специфических для проекта соглашений (помещайте в файл инструкций)
• Механических ограничений, автоматизируемых через regex/валидацию

Структура директории

skills/
  skill-name/
    SKILL.md              # Основной справочник (обязателен)
    supporting-file.*     # Только при необходимости

Плоское пространство имён — все скиллы в одном пространстве. Выносите в отдельные файлы тяжёлые справочники (100+ строк) и многократно используемые инструменты. Всё остальное — инлайн.

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

Frontmatter (YAML):

• Два обязательных поля: name и description (макс. 1024 символа)
• name: только буквы, цифры и дефисы (без скобок и спецсимволов)
• description: от третьего лица, описывает ТОЛЬКО когда использовать (НЕ что делает скилл). Начинать с «Use when...». Никогда не резюмировать процесс или рабочий процесс скилла

---
name: Skill-Name-With-Hyphens
description: Use when [конкретные условия и симптомы]
---

# Название скилла

## Обзор
Что это? Ключевой принцип в 1–2 предложениях.

## Когда использовать
[Небольшая инлайн-блок-схема, если решение неочевидно]

## Основной паттерн
Сравнение до/после

## Быстрый справочник
Таблица или маркеры для быстрого поиска

## Реализация
Инлайн-код для простых паттернов

## Распространённые ошибки
Что идёт не так + исправления

Оптимизация для поиска (SDO)

Поле description

КРИТИЧНО: Description = Когда использовать, а НЕ что делает скилл

Если description резюмирует рабочий процесс, агент может следовать описанию вместо чтения полного содержимого скилла. Тестирование показало: когда description изменили с резюме рабочего процесса на просто «Use when executing implementation plans» — агент корректно прочёл блок-схему и выполнил двухэтапный процесс ревью.

# ❌ ПЛОХО: резюмирует рабочий процесс
description: Use when executing plans - dispatches subagent per task with code review

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

• Используйте конкретные триггеры, симптомы и ситуации
• Описывайте проблему, а не языко-специфичные симптомы
• Пишите от третьего лица
• Никогда не резюмируйте процесс скилла

Покрытие ключевыми словами

Используйте слова, которые агент мог бы искать: сообщения об ошибках, симптомы, синонимы, инструменты.

Именование

Активный залог, глагол первым: ✅ condition-based-waiting, а не async-test-helpers. Герундии хорошо работают для процессов.

Экономия токенов (критично)

Getting-started скиллы загружаются в КАЖДЫЙ разговор.

• Getting-started рабочие процессы: <150 слов
• Часто загружаемые скиллы: <200 слов итого
• Остальные скиллы: <500 слов

Переносите детали в --help инструментов, используйте перекрёстные ссылки на другие скиллы, сжимайте примеры.

Использование блок-схем

Используйте блок-схемы только для: неочевидных точек принятия решений, цикличных процессов, выбора «A vs B».

Никогда для справочного материала → таблицы; примеров кода → блоки кода; линейных инструкций → нумерованные списки.

Примеры кода

Один отличный пример лучше множества посредственных. Полный и рабочий код с комментариями «почему», из реального сценария. Не реализуйте на 5+ языках — вы хороши в адаптации.

Железный закон (как в TDD)

НИ ОДИН СКИЛЛ БЕЗ ПРОВАЛЬНОГО ТЕСТА СНАЧАЛА

Написали скилл до теста? Удалите. Начните сначала. Отредактировали без теста? То же нарушение.

Без исключений: ни для «простых дополнений», ни для «обновлений документации». Удалить — значит удалить.

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

RED: базовый тест

Запустите сценарий давления с подагентом БЕЗ скилла. Задокументируйте точное поведение: какие решения принял агент, какие рационализации использовал (дословно).

GREEN: минимальный скилл

Напишите скилл, обращающийся к конкретным рационализациям. Запустите те же сценарии СО скиллом — агент должен соблюдать правила.

REFACTOR: закройте лазейки

Агент нашёл новую рационализацию? Добавьте явный контраргумент. Повторяйте до пуленепробиваемости.

Выбор формы под тип провала

Запреты не работают для проблем формирования: под конкурирующим стимулом агенты «торгуются» с «не X». Рецепт не оставляет предмета для торга.

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

(Применяется только к дисциплинарным провалам — агент знает правило, но нарушает его под давлением.)

• Закрывайте каждую лазейку явно — не просто правило, а запрет конкретных обходных путей
• Устраняйте аргументы «дух vs буква»: добавляйте принцип «нарушение буквы = нарушение духа»
• Стройте таблицу рационализаций из реальных тестов
• Создавайте список красных флагов для самопроверки

Тестирование разных типов скиллов

Чек-лист создания скилла

Фаза RED:

• Создать сценарии давления (3+ комбинированных для дисциплинарных скиллов)
• Запустить сценарии БЕЗ скилла — задокументировать базовое поведение дословно
• Выявить паттерны рационализаций/провалов

Фаза GREEN:

• Имя только из букв, цифр, дефисов
• YAML frontmatter с обязательными полями name и description
• Description начинается с «Use when...» с конкретными триггерами
• Ключевые слова по всему тексту для поиска
• Обращается к конкретным провалам, выявленным в RED
• Запустить сценарии СО скиллом — проверить соответствие агентов

Фаза REFACTOR:

• Выявить НОВЫЕ рационализации из тестирования
• Добавить явные контраргументы
• Построить таблицу рационализаций из всех итераций
• Повторять тестирование до пуленепробиваемости

Стоп: до перехода к следующему скиллу

После написания ЛЮБОГО скилла вы ДОЛЖНЫ остановиться и завершить процесс развёртывания. Не создавайте скиллы пакетами без тестирования каждого.

Итог

Создание скиллов — это TDD для документации процессов. Тот же железный закон: нет скилла без провального теста сначала. Тот же цикл: RED → GREEN → REFACTOR. Те же преимущества: лучшее качество, меньше сюрпризов, пуленепробиваемые результаты.