AGENTS.md

Структура репозитория

• skills/<name>/ — скиллы: SKILL.md, references/, при необходимости workflows/ или references/workflows/, subagents/.
• shared-files/ — эталоны для копирования в скилл; из файлов скиллов на них не ссылаются.
• plugin.json — манифест Agent Plugins.
• .cursor-plugin/plugin.json — манифест Cursor Plugin.
• .cursor-plugin/marketplace.json — манифест Import from Repo.
• README.md — описание набора для пользователей.

Cursor plugin

При работе со скиллами не забывай актуализировать плагин.

Когда обновлять

После любого изменения набора скиллов или метаданных плагина обязательно подними version и синхронизируй все три манифеста:

• plugin.json — Agent Plugins
• .cursor-plugin/plugin.json — Cursor Plugin
• .cursor-plugin/marketplace.json — Import from Repo

Уровень один на всё изменение — старший из сработавших:

• патч — совместимое изменение того, что уже есть: формулировки, правила, шаги, STOP, внутренняя ветка уже выбранного workflow, а также правки метаданных (description, keywords, logo и т.п.). И косметика, и смена поведения уже существующего способа начать работу — патч.
• минор — у пользователя появился новый способ начать работу: новый скилл, новая публичная команда или новый режим. Новый режим — минор, даже если он дописан в существующий SKILL.md, а не вынесен в новый файл. Узнавай это по команде, списку выбора workflow и описанию «когда применять», а не по появлению файла и не по размеру правки.
• мажор — только вручную. Сам мажор не ставь.

Если скилл удалён, публичная команда переименована или режим пропал так, что прежний вызов больше не делает то же самое, не выбирай патч или минор. Остановись и отдай выбор мажора пользователю. После его решения подними выбранный им уровень.

Что обновить

1. Подними version по semver одним значением во всех трёх файлах по уровню из раздела выше.
2. Общие поля держи одинаковыми в plugin.json и .cursor-plugin/plugin.json: name, version, description, author, homepage, repository, license, keywords.
3. В .cursor-plugin/marketplace.json синхронизируй name / description / version / owner с тем же смыслом.
4. В .cursor-plugin/plugin.json проверь, что skills указывает на каталог скиллов, путь logo существует, displayName актуален. Эти поля не копируй в корневой plugin.json: схема Agent Plugins закрытая ($schema, name, version, description, author, homepage, repository, license, keywords; при необходимости extensions).
5. В корневом plugin.json обязателен "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json". JSON во всех трёх файлах должен быть валидным.
6. После повышения version явно скажи пользователю вызвать внутренний скилл /create-release из .agents/skills/create-release. Сам этот скилл не вызывай: выпуск идёт только прямым вызовом. В skills/ его не клади: это не часть поставки.

Запрещено

• Коммитить изменения набора скиллов, оставляя любой из трёх манифестов на устаревшей версии, с рассинхроном общих полей или с устаревшими метаданными.
• Невалидный JSON в plugin.json, .cursor-plugin/plugin.json или .cursor-plugin/marketplace.json.

Skills: frontmatter

У каждого SKILL.md YAML frontmatter между --- обязан быть валидным YAML.

Обязательно

• После любой правки frontmatter проверяй валидность (парсером YAML), а не только «на глаз».
• Не оставляй в незакавыченных значениях символы, из‑за которых YAML становится невалидным (типично :, #, кавычки, {, }, [, ] и др.). Заключай такие значения в кавычки ("..." / '...') либо используй блок-скаляр (> / |).

Запрещено

• Невалидный frontmatter: сохранять или коммитить SKILL.md с синтаксической ошибкой YAML.
• Неэкранированные специальные символы YAML в незакавыченных скалярах (типичный случай — : внутри description: без кавычек).

Skills: изоляция

Скиллы НЕ МОГУТ ссылаться на файлы других скиллов.

Каждый скилл — самодостаточный модуль. Все пути, ссылки и упоминания файлов допустимы только внутри каталога этого скилла (например skills/bro-do-it/**).

Вызов другого установленного скилла через его публичную команду (например /bro-review) не является файловой ссылкой. Такой вызов разрешён в инструкциях скилла и в промпте субагента: вызываемый скилл самостоятельно применяет свои внутренние инструкции.

Запрещено

• Относительные или абсолютные ссылки на другой скилл: ../bro-give-me-plan/..., ../../bro-do-it/..., skills/bro-* чужого имени.
• Markdown-ссылки, «загрузи», «см.» и аналоги, указывающие на SKILL.md, references/, workflows/, references/workflows/, subagents/ другого скилла.
• Упоминания путей вида bro-<name>/..., если <name> — не текущий скилл (даже без ссылки).

Разрешено

• Ссылки и include внутри одного скилла: SKILL.md → ./references/..., ./workflows/..., ./references/workflows/..., ./subagents/....
• Ссылки на корень репозитория: AGENTS.md, README.md — если это не обход изоляции скиллов.
• Явный вызов другого установленного скилла через публичную команду /bro-<name>, в том числе как часть промпта для субагента.
• Передача в такой вызов задачи, входных данных, ограничений и требуемого формата результата без ссылок на внутренние файлы вызываемого скилла.

Если нужен общий текст

1. Дублируй нужный фрагмент в каталог текущего скилла (например references/), или
2. Вынеси общее в корень репозитория (shared-files/ или другой файл в корне), скопируй в скилл и ссылайся только на локальную копию.
3. Не клади в скилл этапа A правила исполнения этапа B «для удобства» — в A только то, что нужно оркестратору A; исполнение — в скилле B.

Примеры

# ❌ bro-do-it/workflows/generic-plan.md
Правила диалога — [dialog-rules.md](../../bro-give-me-plan/references/dialog-rules.md)

# ✅ bro-think-with-me/SKILL.md
Правила диалога — [dialog-rules.md](./references/dialog-rules.md)
(файл живёт в bro-think-with-me/references/)

Эталон для тиров субагентов

Если скилл использует субагентов и ему нужны тиры или семейства моделей:

1. Эталонный файл — shared-files/subagent-model-tiers.md.
2. Перед использованием в конкретном скилле скопируй его в ./references/subagent-model-tiers.md внутри этого скилла.
3. В локальной копии допускается только удалить тиры, которые не используются в этом скилле.
4. Текст оставшихся разделов и общих правил сохраняй без изменений.
5. SKILL.md и файлы workflow такого скилла могут ссылаться только на ./references/subagent-model-tiers.md.
6. Не ссылайся из файлов скилла напрямую на shared-files/subagent-model-tiers.md.
7. subagents/*-prompt.md не должны ссылаться на subagent-model-tiers.md и не должны содержать инструкции по выбору тира или семейства модели. Выбор тира и модели оркестратор выполняет до запуска субагента.

Эталон для правил диалога

Если скилл задаёт вопросы пользователю или предлагает варианты ответов:

1. Эталонный файл — shared-files/dialog-rules.md.
2. Перед использованием в конкретном скилле скопируй его в ./references/dialog-rules.md внутри этого скилла.
3. Текст локальной копии сохраняй без изменений.
4. SKILL.md, workflow-файлы и другие файлы скилла могут ссылаться только на ./references/dialog-rules.md.
5. Не ссылайся из файлов скилла напрямую на shared-files/dialog-rules.md.

Эталон для гигиены реализации

Если скилл составляет шаги реализации или запускает developer-субагента:

1. Эталонный файл — shared-files/implementation-hygiene.md.
2. Перед использованием в конкретном скилле скопируй его в ./references/implementation-hygiene.md внутри этого скилла.
3. Текст локальной копии сохраняй без изменений.
4. SKILL.md, workflow-файлы и другие файлы скилла могут ссылаться только на ./references/implementation-hygiene.md.
5. Не ссылайся из файлов скилла напрямую на shared-files/implementation-hygiene.md.
6. Если скилл передаёт работу developer-субагенту, полный текст файла обязан быть внутри промпта Task. Ссылка в промпте субагента недостаточна.

spec и plan

bro-give-me-spec и bro-give-me-plan используют один каркас общих разделов и одинаковое наполнение. У плана дополнительно есть только шаги реализации.

При правке шаблонов, обязательных разделов, правил наполнения или промптов ревью этих скиллов согласуй оба: те же названия разделов, тот же смысл наполнения общих разделов, тот же формат критериев приемки. Не разводи отдельные правила для общих разделов. Отдельный общий файл для согласования не заводи.

При правке любого файла под skills/** проверяй: нет ли ссылок за пределы каталога текущего скилла.

Skills: содержимое

Файлы под skills/<name>/ — конечные инструкции для агента в рантайме, не документация сопровождения репозитория.

Запрещено

• Заметки для мейнтейнера: «при правке X обнови Y», «держи в синхроне», «дублировано в …».
• Правила исполнения чужого этапа в reference планирующего скилла (и наоборот).
• Один и тот же смысл в нескольких файлах одного скилла с отсылками «см. …» вместо одного канонического references/*.md и кратких проверок в SKILL.md.

Разрешено

• Один канонический references/*.md на тему.
• В SKILL.md (Quality Control, STOP) — суть проверки своими словами, без «по файлу X».

Субагенты (Task)

Промпт для Task содержит полный контекст задачи. Субагент не читает напрямую SKILL.md, references/ и остальные внутренние файлы скиллов, но может явно вызвать установленный скилл через его публичную команду.

Запрещено в теле промпта субагента

• Ссылки на внутренние файлы скилла и формулировки «примени правила из файла …», «см. dialog-rules».
• Указания напрямую «загрузить» или «прочитать» внутренний файл скилла вместо передачи контекста в Task или явного вызова публичной команды скилла.

Обязательно

• Все сведения о задаче, входные данные, ограничения и ожидаемый результат находятся внутри передаваемого промпта.
• Правила выполнения либо включены в промпт, либо делегированы явным вызовом установленного скилла через /bro-<name>. Простое упоминание скилла без команды вызова не заменяет передачу правил.

Skills: язык

Скиллы на русском — формулировки на русском. Технические идентификаторы ([CHECKPOINT], CreatePlan, пути к файлам) — как есть.

Избегай разговорных англицизмов, если есть нормальный русский термин (не «prose», а «только в тексте плана»; не «implementation-шаг», а «шаг реализации»).