bear-new-skill — Новый скилл по шаблону коллекции

Шаг 1. Проверь, что скилл нужен

Задай себе три вопроса и, если ответы не сходятся, скажи об этом прямо:

• Задача действительно повторяется, или это разовый случай? Скилл на разовую задачу — мёртвый груз, конкурирующий за срабатывание.
• Нет ли уже подходящего? Проверь bear-skills list. Расширить существующий обычно лучше, чем завести соседний: два похожих скилла делят триггеры и мешают друг другу.
• Это скилл или правило? Правило — то, что действует всегда (rules/). Скилл — то, что запускается под задачу.

Шаг 2. Выбери домен и имя

Имя начинается с префикса домена: sre-, git-, content-, obsidian-, agentops-, code-, bear-. Имя каталога и name во фронтматтере совпадают — это проверяется тестом.

Если задача не ложится ни в один домен — обсуди с пользователем новый домен, не запихивай в ближайший.

Шаг 3. Напиши фронтматтер

---
name: <домен>-<имя>
description: >
  Что делает, одним-двумя предложениями. Используй, когда пользователь говорит
  «<фраза>», «<фраза>», «<фраза>». Для смежного случая — <другой-скилл>, не этот.
---

description — единственное, по чему модель решает, звать скилл или нет. Это самая важная часть файла.

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

Проверь пересечения: bear-skills doctor покажет, если новый скилл делит триггер с существующим. При пересечении добавь в оба описания взаимные отсылки.

Шаг 4. Напиши тело

Структура, принятая в коллекции:

1. Заголовок и одна фраза о цели
2. Границы применимости — когда скилл не нужен, со ссылкой на подходящий
3. Алгоритм по шагам, с командами там, где они есть
4. Раздел «чего не делать»

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

Если скилл что-то сокращает или упрощает — обязателен раздел Auto-Clarity со ссылкой на ../../rules/agentops-auto-clarity.md.

Пиши в императиве и по-русски. Технические термины — английские.

Шаг 5. README для человека

Рядом с SKILL.md, отдельным файлом. Другая аудитория: SKILL.md читает модель, README.md — человек, который листает GitHub и решает, нужно ли это ему.

Что внутри: зачем это вообще (проблема), когда срабатывает, как устроено, где границы. Не копия SKILL.md другими словами.

Шаг 6. Каркас evals

evals/evals.json рядом со скиллом:

{
  "skill_name": "<имя>",
  "evals": [
    { "id": 1, "prompt": "<реалистичный запрос>", "expected_output": "<что должно получиться>", "files": [] }
  ]
}

Промпты бери настоящие, из живых сценариев. Тепличный промпт даёт тепличный результат.

Шаг 7. Свяжи с остальным

• строка в docs/domains/<домен>/README.md
• если появился новый домен — docs/domains/<домен>/README.md целиком и строка в корневом README.md
• упоминание в AGENTS.md в карте компонентов

Шаг 8. Прогони проверки

make check    # манифесты и фронтматтер
make test     # тесты, включая наличие README и уникальность имён
make mirror   # пересборка плоского зеркала
bear-skills doctor

Зелёные проверки — часть работы, а не необязательный финал.

Чего не делать

• Не пиши скилл «на всякий случай». Мёртвый скилл ухудшает срабатывание живых.
• Не копируй описание с соседнего скилла: получишь конкуренцию за триггеры.
• Не делай скилл, дублирующий чужой из skills-lock.json, не разведя триггеры.
• Не оставляй скилл без README и без записи в документации — тест не пропустит, а человек не найдёт.
• Не забывай пересобрать зеркало: иначе CI покажет расхождение.