Сводка

Тесто-ориентированное документирование для создания переиспользуемых техник, паттернов и справочных руководств для agent.

Сначала напишите неудачные сценарии тестов (базовое поведение agent без skill), затем напишите минимальную документацию skill для устранения конкретных нарушений, следуя циклу RED-GREEN-REFACTOR
Skills находятся в специализированных директориях agent и должны включать YAML frontmatter (name, description), обзор, основные паттерны, быструю справку и разделы типичных ошибок
Поле description должно начинаться с "Use when..." и перечислять только условия срабатывания — никогда не резюмировать workflow, поскольку Claude может следовать description вместо чтения полного содержимого skill
Требует понимания superpowers:test-driven-development; skills, обеспечивающие дисциплину, должны содержать явное закрытие лазеек и таблицы рационализаций для противодействия обходным путям под давлением
Держите skills для начала работы (getting-started) в пределах 150 слов, другие часто загружаемые skills — в пределах 200 слов суммарно; используйте перекрёсные ссылки и справку инструментов для экономии токенов

Написание skills

Обзор

Написание skills — это Test-Driven Development, применённый к документированию процессов.

Личные skills находятся в директории skills вашего runtime (~/.claude/skills/ в Claude Code) — см. codex-tools.md или gemini-tools.md для путей в этих runtime. Codex, Copilot CLI и Gemini CLI также распознают ~/.agents/skills/ как кросс-runtime алиас.

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

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

ОБЯЗАТЕЛЬНЫЙ ФОН: Вы ДОЛЖНЫ понимать superpowers:test-driven-development перед использованием этого skill. Этот skill определяет фундаментальный цикл RED-GREEN-REFACTOR. Этот skill адаптирует TDD для документирования.

Официальные рекомендации: Для официальных best practices Anthropic по написанию skills см. anthropic-best-practices.md. Этот документ предоставляет дополнительные паттерны и руководства, дополняющие подход с упором на TDD в этом skill.

Что такое skill?

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

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

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

Соответствие TDD для skills

Концепция TDD	Создание skill
Тестовый кейс	Сценарий давления с subagent
Продуктовый код	Документ skill (SKILL.md)
Тест падает (RED)	agent нарушает правило без skill (базовый случай)
Тест проходит (GREEN)	agent соблюдает при наличии skill
Рефакторинг	Закрытие лазеек при поддержании соблюдения
Сначала напишите тест	Запустите базовый сценарий ПЕРЕД написанием skill
Наблюдайте его падение	Документируйте точные рационализации, которые использует agent
Минимальный код	Напишите skill, устраняющий конкретные нарушения
Наблюдайте прохождение	Убедитесь, что agent теперь соблюдает
Цикл рефакторинга	Найдите новые рационализации → устраните → повторно проверьте

Весь процесс создания skill следует циклу RED-GREEN-REFACTOR.

Когда создавать skill

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

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

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

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

Типы skills

Техника

Конкретный метод с шагами для выполнения (condition-based-waiting, root-cause-tracing)

Паттерн

Способ мышления о проблемах (flatten-with-flags, test-invariants)

Справка

API docs, руководства по синтаксису, документация инструментов (документация office)

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

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

Плоское пространство имён — все skills в одном пространстве для поиска

Отдельные файлы для:

Тяжёлой справки (100+ строк) — API docs, полный синтаксис
Переиспользуемых инструментов — Скрипты, утилиты, шаблоны

Оставляйте встроенно:

Принципы и концепции
Паттерны кода (< 50 строк)
Всё остальное

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

Frontmatter (YAML):

Два обязательных поля: name и description (см. agentskills.io/specification для всех поддерживаемых полей)
Максимум 1024 символа суммарно
name: Используйте только буквы, цифры и дефисы (без скобок, спецсимволов)
description: От третьего лица, описывает ТОЛЬКО когда использовать (НЕ что делает)

Начните с "Use when..." для фокусировки на условиях срабатывания

Включите конкретные симптомы, ситуации и контексты
НИКОГДА не резюмируйте процесс или workflow skill (см. раздел SDO для объяснения)
Сохраняйте в пределах 500 символов, если возможно

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

# Название Skill

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

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

Список с СИМПТОМАМИ и сценариями использования
Когда НЕ использовать

## Основной паттерн (для техник/паттернов)
Сравнение кода до/после

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

## Реализация
Встроенный код для простых паттернов
Ссылка на файл для тяжёлой справки или переиспользуемых инструментов

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

## Влияние на реальный мир (опционально)
Конкретные результаты

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

Критически важно для обнаружения: Будущим agent необходимо НАЙТИ ваш skill

1. Насыщенное поле description

Назначение: Ваш agent читает description, чтобы решить, какие skills загрузить для данной задачи. Сделайте так, чтобы оно отвечало: "Стоит ли мне читать этот skill прямо сейчас?"

Формат: Начните с "Use when..." для фокусировки на условиях срабатывания

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

Description должно описывать ТОЛЬКО условия срабатывания. НЕ резюмируйте процесс или workflow skill в description.

Почему это важно: Тестирование показало, что когда description резюмирует workflow skill, agent может следовать description вместо чтения полного содержимого skill. Description, говорящее "code review между задачами", заставило agent выполнить ОДИН обзор, хотя диаграмма skill ясно показывала ДВА обзора (соответствие спецификации, затем качество кода).

Когда description было изменено на просто "Use when executing implementation plans with independent tasks" (без резюме workflow), agent правильно прочитал диаграмму и следовал двухэтапному процессу обзора.

Ловушка: Description, резюмирующие workflow, создают ярлык, который agent будут использовать. Тело skill превращается в документацию, которую agent пропускают.

❌ ПЛОХО: Резюмирует workflow - agent могут следовать этому вместо чтения skill

description: Use when executing plans - dispatches subagent per task with code review between tasks

❌ ПЛОХО: Слишком много деталей процесса

description: Use for TDD - write test first, watch it fail, write minimal code, refactor

✅ ХОРОШО: Только условия срабатывания, без резюме workflow

description: Use when executing implementation plans with independent tasks in the current session

✅ ХОРОШО: Только условия срабатывания

description: Use when implementing any feature or bugfix, before writing implementation code


**Содержание:**

- Используйте конкретные триггеры, симптомы и ситуации, сигнализирующие о применимости этого skill

- Опишите *проблему* (race conditions, непоследовательное поведение), а не *симптомы, привязанные к конкретному языку* (setTimeout, sleep)

- Сохраняйте триггеры, не привязанные к технологиям, если сам skill не является технологически специфичным

- Если skill технологически специфичный, укажите это явно в триггере

- Пишите от третьего лица (внедряется в системный промпт)

- **НИКОГДА не резюмируйте процесс или workflow skill**

❌ ПЛОХО: Слишком абстрактно, расплывчато, не включает когда использовать

description: For async testing

❌ ПЛОХО: От первого лица

description: I can help you with async tests when they're flaky

❌ ПЛОХО: Упоминает технологию, но skill не специфичен для неё

description: Use when tests use setTimeout/sleep and are flaky

✅ ХОРОШО: Начинается с "Use when", описывает проблему, без workflow

description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

✅ ХОРОШО: Технологически специфичный skill с явным триггером

description: Use when using React Router and handling authentication redirects


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

Используйте слова, которые agent будут искать:

- Сообщения об ошибках: "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`

### 4. Эффективность по токенам (Критически важно)

**Проблема:** getting-started и часто используемые skills загружаются в КАЖДЫЙ разговор. Каждый токен на счету.

**Целевые счётчики слов:**

- getting-started workflows: <150 слов каждый

- Часто загружаемые skills: <200 слов суммарно

- Другие skills: <500 слов (будьте всё равно кратки)

**Техники:**

**Перемещайте детали в справку инструментов:**

❌ ПЛОХО: Документировать все флаги в SKILL.md

search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

✅ ХОРОШО: Ссылка на --help

search-conversations supports multiple modes and filters. Run --help for details.


**Используйте перекрёсные ссылки:**

❌ ПЛОХО: Повторять детали workflow

When searching, dispatch subagent with template... [20 lines of repeated instructions]

✅ ХОРОШО: Ссылка на другой skill

Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.


**Сжимайте примеры:**

❌ ПЛОХО: Многословный пример (42 слова)

your human partner: "How did we handle authentication errors in React Router before?" You: I'll search past conversations for React Router authentication patterns. [Dispatch subagent with search query: "React Router authentication error handling 401"]

✅ ХОРОШО: Минимальный пример (20 слов)

Partner: "How did we handle auth errors in React Router?" You: Searching... [Dispatch subagent → synthesis]


**Устраняйте избыточность:**

- Не повторяйте то, что уже есть в перекрёсно связанных skills

- Не объясняйте очевидное из команды

- Не включайте несколько примеров одного и того же паттерна

**Проверка:**

wc -w skills/path/SKILL.md

getting-started workflows: aim for <150 each

Другие часто загружаемые: цель — менее 200 всего


**Называйте по тому, ЧТО вы делаете, или по ключевой инсайт:**

- ✅ `condition-based-waiting` > `async-test-helpers`

- ✅ `using-skills` не `skill-usage`

- ✅ `flatten-with-flags` > `data-structure-refactoring`

- ✅ `root-cause-tracing` > `debugging-techniques`

**Действительные причастия (-ing) хорошо работают для процессов:**

- `creating-skills`, `testing-skills`, `debugging-with-logs`

- Активный залог, описывает действие, которое вы выполняете

### 5. Взаимные ссылки на другие skills

**При написании документации, которая ссылается на другие skills:**

Используйте только имя skill, с явными маркерами требований:

- ✅ Хорошо: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development`

- ✅ Хорошо: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging`

- ❌ Плохо: `See skills/testing/test-driven-development` (непонятно, обязательно ли)

- ❌ Плохо: `@skills/testing/test-driven-development/SKILL.md` (принудительная загрузка, сжигает контекст)

**Почему не @-ссылки:** синтаксис `@` принудительно загружает файлы сразу, потребляя 200k+ контекста ещё до того, как они понадобятся.

## Использование диаграмм потоков

digraph when_flowchart { "Need to show information?" [shape=diamond]; "Decision where I might go wrong?" [shape=diamond]; "Use markdown" [shape=box]; "Small inline flowchart" [shape=box];

"Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
"Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
"Decision where I might go wrong?" -> "Use markdown" [label="no"];

}


**Используйте диаграммы потоков ТОЛЬКО для:**

- Неочевидных точек принятия решений

- Циклов процесса, где вы можете остановиться слишком рано

- Решений «когда использовать A, а когда B»

**Никогда не используйте диаграммы потоков для:**

- Справочных материалов → Таблицы, списки

- Примеров кода → Markdown-блоки

- Линейных инструкций → Нумерованные списки

- Меток без семантического значения (step1, helper2)

Смотрите `graphviz-conventions.dot` в этой директории для правил стиля graphviz.

**Визуализация для вашего human-партнёра:** используйте `render-graphs.js` в этой директории для рендеринга диаграмм skill в SVG:

node ./render-graphs.js ../some-skill # Каждая диаграмма отдельно node ./render-graphs.js ../some-skill --combine # Все диаграммы в одном SVG


## Примеры кода

**Один отличный пример лучше множества посредственных**

Выберите наиболее релевантный язык:

- Техники тестирования → TypeScript/JavaScript

- Системная отладка → Shell/Python

- Обработка данных → Python

**Хороший пример:**

- Полный и запускаемый

- Хорошо прокомментированный с объяснением ПОЧЕМУ

- Из реального сценария

- Чётко демонстрирует паттерн

- Готов к адаптации (не шаблонная заглушка)

**Не стоит:**

- Реализовывать на 5+ языках

- Создавать шаблоны «заполните пропуск»

- Писать надуманные примеры

Вы хорошо переносите — одного отличного примера достаточно.

## Организация файлов

### Самостоятельный Skill

defense-in-depth/ SKILL.md # Всё инлайн


Когда: весь контент помещается, тяжёлая справочная часть не нужна

### Skill с переиспользуемым инструментом

condition-based-waiting/ SKILL.md # Обзор + паттерны example.ts # Рабочие хелперы для адаптации


Когда: инструмент — переиспользуемый код, а не просто повествование

### Skill с объёмной справочной частью

pptx/ SKILL.md # Обзор + рабочие процессы pptxgenjs.md # 600 строк справочника API ooxml.md # 500 строк XML-структуры scripts/ # Исполняемые инструменты


Когда: справочный материал слишком велик для инлайна

Вызывайте встроенные скрипты через их интерпретатор в тексте (`bash scripts/tool.sh`, `node scripts/script.js`), никогда по голому пути: некоторые упаковщики плагинов harness-систем снимают биты исполнения, и голый `scripts/tool.sh` там падает с `Permission denied`.

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

NO SKILL WITHOUT A FAILING TEST FIRST


Это относится к НОВЫМ skills И к РЕДАКТИРОВАНИЮ существующих skills.

Написали skill до тестирования? Удалите. Начните заново.

Отредактировали skill без тестирования? То же нарушение.

**Без исключений:**

- Не для «простых дополнений»

- Не для «просто добавления раздела»

- Не для «обновления документации»

- Не храните нетестированные изменения как «справочный материал»

- Не «адаптируйте» во время прохождения тестов

- Удалить значит удалить

**REQUIRED BACKGROUND:** skill superpowers:test-driven-development объясняет, почему это важно. Те же принципы применимы к документации.

## Тестирование всех типов skills

Разные типы skills требуют разных подходов к тестированию:

### Skills для соблюдения дисциплины (правила/требования)

**Примеры:** TDD, verification-before-completion, designing-before-coding

**Тестируйте с помощью:**

- Академических вопросов: понимают ли они правила?

- Сценариев давления: соблюдают ли они правила под стрессом?

- Сочетания множественных давлений: время + вложенные усилия + истощение

- Выявления рационализаций и добавления явных контрмер

**Критерий успеха:** Agent соблюдает правило при максимальном давлении

### Skills-техники (гайдлайны)

**Примеры:** condition-based-waiting, root-cause-tracing, defensive-programming

**Тестируйте с помощью:**

- Сценариев применения: могут ли они правильно применить технику?

- Сценариев вариаций: обрабатывают ли они пограничные случаи?

- Тестов на отсутствие информации: есть ли пробелы в инструкциях?

**Критерий успеха:** Agent успешно применяет технику к новому сценарию

### Skills-паттерны (ментальные модели)

**Примеры:** reducing-complexity, концепции information-hiding

**Тестируйте с помощью:**

- Сценариев распознавания: распознают ли они, когда паттерн применим?

- Сценариев применения: могут ли они использовать ментальную модель?

- Контрпримеров: знают ли они, когда НЕ применять?

**Критерий успеха:** Agent корректно определяет, когда/как применить паттерн

### Skills-справочники (документация/API)

**Примеры:** документация API, справочники команд, гайды по библиотекам

**Тестируйте с помощью:**

- Сценариев извлечения: могут ли они найти нужную информацию?

- Сценариев применения: могут ли они правильно использовать найденное?

- Тестов на пробелы: покрыты ли типичные случаи использования?

**Критерий успеха:** Agent находит и правильно применяет справочную информацию

## Частые рационализации для пропуска тестирования

| Отговорка | Реальность |
| --- | --- |
| «Skill очевидно понятен» | Понятно ВАМ ≠ понятно другим agents. Тестируйте. |
| «Это просто справочный материал» | Справочники могут иметь пробелы, неясные разделы. Тестируйте извлечение. |
| «Тестирование — это перебор» | Нетестированные skills имеют проблемы. Всегда. 15 минут тестирования экономят часы. |
| «Протестирую, если возникнут проблемы» | Проблемы = agents не могут использовать skill. Тестируйте ДО развёртывания. |
| «Слишком утомительно тестировать» | Тестирование менее утомительно, чем отладка плохого skill в production. |
| «Я уверен, что всё хорошо» | Чрезмерная уверенность гарантирует проблемы. Тестируйте всё равно. |
| «Академической проверки достаточно» | Чтение ≠ использование. Тестируйте сценарии применения. |
| «Нет времени на тестирование» | Развёртывание нетестированного skill тратит больше времени на его исправление потом. |

**Всё это означает: тестируйте перед развёртыванием. Без исключений.**

## Соответствуйте форму проблеме

Перед написанием рекомендаций классифицируйте исходную проблему. Форма, которая защищает от одного типа проблем, заметно ухудшает другую.

| Исходная проблема | Правильная форма | Неправильная форма |
| --- | --- | --- |
| Пропускает/нарушает правило под давлением (знает лучше, всё равно делает) | Запрет + таблица рационализаций + красные флаги (см. раздел Bulletproofing ниже) | Мягкие рекомендации («предпочитайте...», «рассмотрите...») |
| Соблюдает, но результат имеет неверную форму (раздутый prompt, скрытый вердикт, переформулированная спецификация) | Позитивный рецепт или контракт: укажите, ЧТО является результатом — его части, в порядке | Список запретов («не переформулируйте», «никогда не пересказывайте») |
| Опускает обязательный элемент из того, что уже производит | Структурное: обязательное поле или слот в шаблоне, который они заполняют | Текстовые напоминания рядом с шаблоном |
| Поведение должно зависеть от условия | Условие, привязанное к наблюдаемому предикату («если бриф существует, сославшись на него») | Безусловное правило + исключения |

**Почему запреты дают обратный эффект на проблемы формообразования:** под конкурирующим стимулом («сделай prompt самодостаточным») agents ведут переговоры с «не делай X». В прямых сравнительных тестах формулировок для guidance по dispatch-prompt запретный вариант давал заметно больше нежелательного контента, чем рецептурный (полностью разделённые распределения), и ухудшался даже относительно контроля без guidance — микро-тестируйте свой случай вместо того, чтобы предполагать, но никогда не выбирайте запрет по умолчанию. Рецепт не оставляет места для переговоров: результат либо соответствует указанной форме, либо нет.

**Правила для любой выбранной вами формы:**

- **Ни одного отступления.** «Не делай X, если это не важно» возобновляет переговоры — добавление одного отступления к выигрышному рецепту деградировало его от последовательного к шумному в тех же сравнительных тестах формулировок. Выражайте реальное исключение как отдельное условие на наблюдаемом предикате.

- **Клаузы-исключения не ограничивают область.** «Это ограничение не применяется к блокам кода» всё равно подавляет блоки кода. Если часть вывода должна быть исключена, переструктурируйте так, чтобы правило не могло до неё дотянуться.

## Защита skills от рационализации

Skills, обеспечивающие дисциплину (например, TDD), должны сопротивляться рационализации. Agents умны и найдут лазейки под давлением.

**Область:** этот инструментарий для нарушений дисциплины — agent, который знает правило и пропускает его под давлением. Для результатов неверной формы или пропущенных элементов защита запретами даёт обратный эффект; используйте формы из раздела «Соответствуйте форму проблеме».

**Психологическая заметка:** понимание ТОГО, ПОЧЕМУ техники убеждения работают, помогает применять их системно. Смотрите persuasion-principles.md для научной основы (Cialdini, 2021; Meincke et al., 2025) по принципам авторитета, привязанности, дефицита, социального доказательства и единства.

### Закрывайте каждую лазейку явно

Не просто утверждайте правило — запрещайте конкретные обходные пути:

**Без исключений:**

- Не храните это как «справочный материал»

- Не «адаптируйте» это во время написания тестов

- Не смотрите на это

- Удалить значит удалить

</Good>

Обращайте аргументы «буква vs дух»

Добавьте основополагающий принцип в самом начале:

**Нарушение буквы правил — это нарушение духа правил.**

Это отсекает целый класс рационализаций «я следую духу».

Составляйте таблицу рационализаций

Фиксируйте рационализации из baseline-тестирования (см. раздел Тестирование ниже). Каждая отговорка agents попадает в таблицу:

| Отговорка | Реальность |
|-----------|------------|
| «Слишком просто для тестирования» | Простой код ломается. Тест занимает 30 секунд. |
| «Протестирую потом» | Успешные тесты сразу ничего не доказывают. |
| «Тесты после дают те же цели» | Тесты после = «что это делает?». Тесты сначала = «что это должно делать?» |

Создайте список красных флагов

Сделайте так, чтобы agents легко могли самопроверяться при рационализации:

Красные флаги — СТОП, начинай сначала

Код до теста
«Я уже протестировал вручную»
«Тесты после достигают той же цели»
«Речь о духе, а не о ритуале»
«Это по-другому, потому что...»

Всё это означает: Удали код. Начни сначала с TDD.


### Обнови SDO для симптомов нарушений

Добавь в описание: симптомы, когда вы СОБИРАЕТЕСЯ нарушить правило:

description: use when implementing any feature or bugfix, before writing implementation code


## RED-GREEN-REFACTOR для Skills

Следуй циклу TDD:

### RED: Напиши падающий тест (базовый сценарий)

Запусти стрессовый сценарий с subagent БЕЗ skill. Задокументируй точное поведение:

- Какие решения они приняли?

- Какие рационализации они использовали (дословно)?

- Какое давление привело к нарушениям?

Это «наблюдай, как тест падает» — ты должен увидеть, что делают агенты естественно, прежде чем писать skill.

### GREEN: Напиши минимальный skill

Напиши skill, который решает именно эти рационализации. Не добавляй лишнее содержимое для гипотетических случаев.

Запусти те же сценарии С skill. Агент теперь должен подчиняться.

### REFACTOR: Закрой дыры

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

### Микротестирование формулировок перед полными сценариями

Полные прогоны стрессовых сценариев — это финальный контроль, но они медленные и дорогие на каждой итерации. Сначала проверь саму формулировку микротестами:

- **Один свежий образец на вызов** — сырой вызов API или одноразовый subagent, если у тебя нет доступа к API. System prompt = реалистичный контекст, в котором будет использоваться руководство (полный skill или шаблон промпта, а не руководство само по себе); user message = задача, которая соблазняет на провал.

- **Всегда включай контрольную группу без руководства.** Если контрольная группа не проявляет провала — чинить нечего: остановись, не пиши руководство.

- **5+ повторов на каждый вариант.** Одиночные образцы врут.

- **Вручную читай каждое отмеченное совпадение.** Можно считать программно, но эхо шаблонов и процитированные контрпримеры маскируются под совпадения; автоматические подсчёты завышают и провалы, и успехи.

- **Дисперсия — это метрика.** Когда руководство работает, повторы сходятся к одной и той же форме. Пять разных интерпретаций на пять повторов означают, что формулировка не связывает — подтяни форму, прежде чем добавлять слова.

Микротесты проверяют формулировки; они не заменяют стрессовые сценарии для скилл-дисциплины.

**Методология тестирования:** См. [testing-skills-with-subagents.md](https://github.com/obra/superpowers/blob/HEAD/skills/writing-skills/testing-skills-with-subagents.md) для полной методологии тестирования:

- Как писать стрессовые сценарии

- Типы давления (время, потраченные ресурсы, авторитет, истощение)

- Систематическое заделывание дыр

- Техники мета-тестирования

## Антипаттерны

### ❌ Нарративный пример

«В сессии 2025-10-03 мы обнаружили, что пустой projectDir вызвал...»
**Почему плохо:** Слишком специфично, не переиспользуемо

### ❌ Размазывание по нескольким языкам

example-js.js, example-py.py, example-go.go
**Почему плохо:** Посредственное качество, бремя поддержки

### ❌ Код в диаграммах потока

step1 [label="import fs"]; step2 [label="read file"];


**Почему плохо:** Нельзя копировать и вставлять, трудно читать

### ❌ Обобщённые метки

helper1, helper2, step3, pattern4
**Почему плохо:** Метки должны иметь семантический смысл

## СТОП: Прежде чем переходить к следующему skill

**После написания ЛЮБОГО skill ты ОБЯЗАН ОСТАНОВИТЬСЯ и завершить процесс развёртывания.**

**НЕЛЬЗЯ:**

- Создавать несколько skills пачкой без тестирования каждого

- Переходить к следующему skill, пока текущий не проверен

- Пропускать тестирование, потому что «пачками эффективнее»

**Чек-лист развёртывания ниже ОБЯЗАТЕЛЕН для КАЖДОГО skill.**

Развёртывание нетестированных skills = развертывание нетестированного кода. Это нарушение стандартов качества.

## Чек-лист создания skill (адаптированный под TDD)

**ВАЖНО: Создай задачу для КАЖДОГО пункта чек-листа ниже.**

**Фаза RED — Напиши падающий тест:**

-  Создай стрессовые сценарии (3+ комбинированных давления для skill-дисциплины)

-  Запусти сценарии БЕЗ skill — задокументируй базовое поведение дословно

-  Выяви паттерны в рационализациях/провалах

**Фаза GREEN — Напиши минимальный skill:**

-  Имя использует только буквы, цифры, дефисы (без скобок/спецсимволов)

-  YAML frontmatter с обязательными полями `name` и `description` (макс. 1024 символов; см. [спецификацию](https://agentskills.io/specification))

-  Описание начинается с «Используй, когда...» и включает конкретные триггеры/симптомы

-  Описание написано от третьего лица

-  Ключевые слова для поиска по всему тексту (ошибки, симптомы, инструменты)

-  Понятный обзор с основным принципом

-  Решаются конкретные провалы базового сценария, выявленные в RED

-  Форма руководства соответствует типу провала (см. «Подбери форму под провал»)

-  Для формирования поведения: формулировки микротестированы по сравнению с контрольной группой без руководства (5+ повторов, каждое отмеченное совпадение прочитано вручную) — Н/Д для чисто справочных skills

-  Код инлайн ИЛИ ссылка на отдельный файл

-  Один отличный пример (не многоязычный)

-  Запусти сценарии С skill — проверь, что агенты теперь подчиняются

**Фаза REFACTOR — Закрой дыры:**

-  Выяви НОВЫЕ рационализации из тестирования

-  Добавь явные контраргументы (если skill-дисциплина)

-  Построй таблицу рационализаций со всех итераций тестирования

-  Создай список красных флагов

-  Повторяй тесты, пока не будешь уверен в непроницаемости

**Проверки качества:**

-  Маленькая диаграмма потока только если решение неочевидно

-  Таблица быстрой справки

-  Раздел «частые ошибки»

-  Без нарративного повествования

-  Вспомогательные файлы только для инструментов или объёмных справок

**Развёртывание:**

-  Закоммить skill в git и запушь в свой форк (если настроено)

-  Рассмотри возможность внести вклад обратно через PR (если полезно широкой аудитории)

## Процедура обнаружения

Как будущие агенты найдут твой skill:

- **Столкнется с проблемой** («тесты нестабильные»)

- **Найдёт skill** (отфильтрует по описаниям, просмотрит категории)

- **Найдёт SKILL** (описание совпадает)

- **Просмотрит обзор** (релевантно ли это?)

- **Прочитает паттерны** (таблица быстрой справки)

- **Загрузит пример** (только при реализации)

**Оптимизируй под этот поток** — ставь искомые термины рано и часто.

Установка

npx skills add https://github.com/obra/superpowers --skill writing-skills