Урок 17.4. Как это устроено: скиллы, хуки и бутстрап сессии

Дополнительные источники: https://github.com/obra/superpowers/blob/main/docs/porting-to-a-new-harness.md (Part 1–3), https://github.com/obra/superpowers/blob/main/AGENTS.md, https://github.com/obra/superpowers/tree/main/hooks, https://github.com/obra/superpowers#visual-companion-telemetry

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

Уроки 17.2 и 17.3 показали поведение: скиллы «срабатывают сами». В этом уроке — механика: почему markdown-файл заставляет агента остановиться перед кодом, зачем нужен хук старта сессии, что происходит при компакции контекста и почему один набор файлов работает в ~16 каркасах без изменений. Это переводчески важный урок и главный инженерный урок модуля: Superpowers — хрестоматийный пример «инструкция как интерфейс», то же самое, что курс разбирает в модуле 6 (скиллы) на общих основаниях.

Ответ на вопрос «как это устроено» документирует и docs/porting-to-a-new-harness.md — руководство по переносу Superpowers на новые каркасы: оно сознательно объясняет инварианты, то есть то, что должно быть правдой в любом каркасе.

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

Superpowers состоит из трех слоев (по porting-документу, Part 1):

Скиллы — все из skills/, источник правды, общий для всех каркасов дословно. Скиллы описывают действия («вызови скилл», «прочитай файл», «диспетчеризуй сабагента»), а не имена инструментов.
Отображение инструментов (tool mapping) — для каждого каркаса словарь «действие → реальный инструмент каркаса» (например, «диспетчеризуй сабагента» → вызвать task с subagent_type); живет в skills/using-superpowers/references/<harness>-tools.md.
Бутстрап — при старте каждой сессии полный текст skills/using-superpowers/SKILL.md инжекится в контекст модели в обертке <EXTREMELY_IMPORTANT> с приложенным отображением инструментов. «The bootstrap is the entire integration» — бутстрап и есть вся интеграция: без него файлы скиллов мертвы — лежат на диске и не вызываются.

flowchart TD A["Старт сессии"] --> B["Хук SessionStart (hooks/session-start)"] B --> C["Инъекция using-superpowers + tool mapping каркаса"] C --> D["Агент проверяет скиллы перед любым ответом"] D --> E["Запрос на фичу → brainstorming"] D --> F["Сообщение о баге → systematic-debugging"] D --> G["Наличие плана → исполнение"] E --> H["Дисциплина процесса"] F --> H G --> H

Формат SKILL.md

Каждый скилл — это каталог с файлом SKILL.md и опциональными вспомогательными файлами. Файл начинается с YAML frontmatter:

yaml
---
name: using-superpowers
description: Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
---

Два обязательных поля — name и description:

description — это триггер. Агент (и хост-каркас) решают по тексту описания, когда скилл применим. Отсюда стиль описаний: третье лицо, «Use when…», конкретные симптомы и ситуации, без пересказа процесса (подробнее — урок 17.15: тесты показали, что описание, пересказывающее workflow, провоцирует агента следовать описанию, не читая скилл).
Тело файла — поведенческая инструкция агенту: правила, чек-листы, диаграммы, таблицы «отмазка → реальность». Это не документация для человека — это код, формирующий поведение.

Тело using-superpowers — яркий пример тона. Ключевой блок (перевод):

<EXTREMELY-IMPORTANT>
Если вы считаете, что есть хотя бы 1% вероятности, что скилл
применим к тому, что вы делаете, вы ОБЯЗАНЫ вызвать скилл.

ЕСЛИ СКИЛЛ ПРИМЕНИМ К ВАШЕЙ ЗАДАЧЕ, У ВАС НЕТ ВЫБОРА. ВЫ ДОЛЖНЫ ЕГО ИСПОЛЬЗОВАТЬ.
Это не обсуждается.
</EXTREMELY-IMPORTANT>

И главное правило (The Rule): «Invoke relevant or requested skills BEFORE any response or action — including clarifying questions, exploring the codebase, or checking files» — вызвать применимый скилл до любого ответа или действия, включая уточняющие вопросы, исследование кодовой базы и проверку файлов. Если скилл окажется неуместен — его не обязательно применять; но проверка — до ответа.

Бутстрап: хук SessionStart

Инъекцию using-superpowers в контекст выполняет хук старта сессии — скрипт hooks/session-start (bash) с конфигами hooks.json/hooks-cursor.json. Скрипт читает skills/using-superpowers/SKILL.md, экранирует его в JSON и выводит как additionalContext в формате, который ожидает текущий каркас (Claude Code — вложенный hookSpecificOutput, Cursor — additional_context, Copilot CLI и SDK-стандарт — additionalContext; пример из скрипта):

"<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n
Below is the full content of your 'superpowers:using-superpowers' skill —
your introduction to using skills. For all other skills, use the 'Skill' tool:\n
...полный текст скилла...\n</EXTREMELY_IMPORTANT>"

Следствия, важные пользователю:

Бутстрап грузится на каждый старт сессии — поэтому после установки нужен перезапуск (урок 17.2).
Компакция контекста стирает инъекцию. Длинная сессия, сжав контекст, может потерять бутстрап — скиллы перестанут срабатывать. Решения: повторная инъекция после компакции в каркасах с post-compaction hook; иначе — свежая сессия (наблюдаемая слабость Hermes; диагностика — урок 17.14).
Скиллы, кроме using-superpowers, в контекст заранее не грузятся — агент подгружает их по мере срабатывания триггеров, поэтому набор почти не ест контекст до применения.

Приоритет скиллов и приоритет инструкций

Два правила приоритета из using-superpowers:

Процессные скиллы прежде имплементационных. Если применимы несколько скиллов, сначала идут процессные — они задают подход, а имплементационные (frontend-design, mcp-builder и т.п.) его исполняют:

"Let's build X"  → сначала superpowers:brainstorming, потом имплементационные скиллы
"Fix this bug"   → сначала superpowers:systematic-debugging, потом доменные скиллы

Инструкции пользователя выше скиллов. Порядок: явные инструкции пользователя (CLAUDE.md, AGENTS.md, GEMINI.md, прямые запросы) → скиллы → поведение по умолчанию. Пропускать workflow скиллов можно только когда человек явно попросил.

Отмазки, или зачем таблицы «Red Flags»

using-superpowers и большинство скиллов содержат таблицы рационализаций — мыслей агента, которыми он оправдывает пропуск правила, и «реальности», которая их опровергает. Примеры (перевод):

Мысль	Реальность
«Это просто простой вопрос»	Вопросы — задачи. Проверь скиллы.
«Мне нужен контекст сначала»	Проверка скиллов — ДО уточняющих вопросов.
«Я помню этот скилл»	Скиллы эволюционируют. Прочитай текущую версию.
«Скилл избыточен для этого»	Простое становится сложным. Используй его.
«Это не считается задачей»	Действие = задача. Проверь скиллы.

Это не украшение: в тестах проекта (AGENTS.md: «Skills are not prose — they are code that shapes agent behavior») такие таблицы — откалиброванный инструмент против обхода правил; убирать или перефразировать их без эвал-доказательств запрещено вклад-политикой. Методология их построения — в уроке 17.15.

Один набор файлов — шестнадцать каркасов

Как один skills/ работает везде (porting-документ, Part 1–2):

Скиллы называют действия, не инструменты. Тело скилла никогда не пишет «вызови тул X» — только «диспетчеризуй сабагента»; конкретное имя подставляет отображение каркаса. Поэтому тело не редактируется при портировании.
Все ставится через собственный механизм каркаса. Бутстрап, скиллы и отображение доставляются плагином/расширением/маркетплейс-записью — порт никогда не редактирует пользовательские конфиги напрямую. «The harness owns what it loads» — каркас владеет тем, что грузит.
Инвариант один: бутстрап при старте сессии. AGENTS.md задает приемочный тест нового каркаса: чистая сессия + Let's make a react todo list → brainstorming срабатывает до кода. «Интеграция», где пользователь обязан включать скиллы в каждой сессии, интеграцией не считается.

Отсюда ~16 каталогов-манифестов в корне репозитория (.claude-plugin/, .opencode/, .codex-plugin/, .cursor-plugin/, …) при едином skills/: манифесты — тонкая обертка доставки, скиллы — общий источник правды.

Телеметрия и ее отключение

Логотип визуального компаньона brainstorming (необязательная фича показа мокапов в браузере, урок 17.6) подгружается с сайта авторов и передает версию Superpowers. Не передается ничего о проекте, промпте или каркасе. Отключение:

SUPERPOWERS_DISABLE_TELEMETRY=<любое true-значение>

Проект также уважает opt-out переменные Claude Code: DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC.

Практика

Откройте репозиторий Superpowers и прочитайте skills/using-superpowers/SKILL.md целиком (65 строк) — это самый короткий способ увидеть «тон проекта».
В своем каркасе начните сессию с вопросом «что ты знаешь о скиллах Superpowers?» и проверьте: отвечает ли агент в духе «проверю применимость скиллов»?
Найдите в выводе хука (или в логах каркаса) момент инъекции бутстрапа при старте сессии.

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

Механика Superpowers — три слоя: скиллы (общий источник правды), отображение инструментов (по каркасу) и бутстрап (инъекция using-superpowers при старте сессии). Бутстрап — вся интеграция: без него скиллы мертвы.

SKILL.md = frontmatter (name, description-триггер) + поведенческая инструкция; описание говорит «когда», тело — «что делать».
Правило: применимый скилл вызывается ДО любого ответа; процессные скиллы прежде имплементационных; инструкции пользователя выше скиллов.
Компакция стирает бутстрап: в каркасах без post-compaction hook длинная сессия его теряет — лечится свежей сессией.
Таблицы «отмазка → реальность» — калиброванный код против обхода правил, не проза.
Один skills/ на все каркасы: скиллы называют действия, доставку делает тонкая обертка манифеста каркаса.

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

Из каких трех слоев состоит Superpowers? Почему «bootstrap is the entire integration»?
Какое поле SKILL.md решает, когда скилл срабатывает, и почему оно не должно пересказывать процесс?
Что происходит с бутстрапом при компакции контекста и какие есть пути решения?
Почему тело скилла никогда не называет конкретные инструменты каркаса? Что это дает при портировании?
Приемочный тест интеграции: какой запрос он использует и что должно произойти?
Зачем в скиллах таблицы рационализаций и почему их нельзя «улучшать» без эвалов?

Что дальше

Теперь, когда механика ясна, следующий урок, 17.5, даст карту всей библиотеки: все 15 скиллов по категориям — триггеры, действия, артефакты — как справочник перед разбором каждого шага процесса в уроках 17.6–17.12.

Источники

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