| name | skill-authoring |
| description | Как добавлять и менять скиллы/промпты ассистента в .agents/: формат SKILL.md, каталог scripts/, зеркала (.claude, AGENTS.md, README) и проверка check_agents_sync.py. |
Skill: skill-authoring
Правила пополнения библиотеки материалов ассистента разработки. Источник истины по структуре и зеркалированию — .agents/README.md; формат SKILL.md — _docs/skills.md §3.
Когда использовать
- Добавляешь или меняешь скилл в
.agents/skills/ или промпт в .agents/prompts/.
- Добавляешь скрипт в
scripts/ скилла ассистента.
- Проверяешь синхронность зеркал (
.claude/skills/, AGENTS.md, таблицы README).
Алгоритм
- Скилл — каталог
.agents/skills/<name>/SKILL.md: kebab-case имя, frontmatter name (= имени каталога) и description (≤ 200 символов), тело «Когда использовать → Алгоритм → Чего избегать».
- Промпт — файл
.agents/prompts/<name>.prompt.md: заголовок # Промпт: ..., самодостаточный текст (копируется ассистенту вместе с контекстом).
- Скрипт скилла —
.agents/skills/<name>/scripts/<script>.py|.sh: детерминированная механика скилла (сверка, прогон проверок), а не суждения. Конвенция: запуск из корня репозитория, человекочитаемый статус в stderr/stdout, выход 0 = успех, ненулевой = проблема с деталями. Скрипт описывается в теле SKILL.md (когда и как запускать).
- Зеркала (для нового скилла):
- symlink
.claude/skills/<name> → ../../.agents/skills/<name>;
- строка в таблице скиллов
.agents/README.md;
- строка в
AGENTS.md (раздел «Skills», при необходимости — «Рекомендуемый порядок загрузки»).
Для нового промпта — строка в таблице промптов .agents/README.md.
- Проверка —
python3 .agents/skills/skill-authoring/scripts/check_agents_sync.py: валидирует формат (frontmatter, длина description, обязательные секции) и зеркала (symlink'и, упоминания в AGENTS.md и README). Зелёный скрипт — критерий готовности; входит в preflight.sh (git-discipline).
Чего избегать
- Править зеркала вместо источника: источник —
.agents/skills/ и AGENTS.md, symlink'и подхватывают изменения сами.
- Дублировать в скилле содержимое
_docs/ — скилл ссылается на документ, а не копирует его.
- Скриптов с побочными эффектами (запись, сеть, мутация состояния) — только проверки и чтение.
- Ручной сверки зеркал глазами — для этого есть
check_agents_sync.py (automation-discipline).
