AGENTS.md — llm-skills

Контракт репозитория для ИИ-агентов (Claude Code, OpenCode, Hermes и другие). Это первоисточник; CLAUDE.md — краткий указатель на него.

Библиотека Agent Skills (skills/<name>/SKILL.md) для Claude Code и OpenCode, распространяется как плагин. Здесь нет исполняемого продукта — контент и есть продукт, поэтому цена ошибки не «упадёт тест», а «навык молча не сработает» или «сработает не тот».

Структура

• skills/<name>/ — один навык = одна папка: SKILL.md плюс references/, scripts/, templates/ по необходимости. Имена навыков — контракт (зашиты в маршрутизацию пользовательских конфигов и память сессий).
• scripts/ — валидатор (validate_skills.py) и его тесты; только стандартная библиотека Python.
• evals/ — роутинг-eval: кейсы и раннер, проверяют, что описание навыка вызывает нужный навык (а не соседа).
• .claude-plugin/plugin.json, marketplace.json — манифесты плагина.
• Планирование — GitHub Issues: единственный источник правды для багов и фич. Отдельного ROADMAP-файла в репозитории нет и заводить его не надо.

Перед коммитом

python scripts/validate_skills.py --strict     # гейт
python scripts/test_validate_skills.py         # тесты самого валидатора

Правил описание навыка — прогони роутинг-eval, он меряет ровно то, за что описание отвечает (обращается к API, стоит денег):

python scripts/run_routing_eval.py --dry-run
python scripts/run_routing_eval.py --tier 1

--info показывает бэклог качества (крупные тела, отсутствие verified) — он намеренно не валит сборку. --list печатает таблицу метрик и суммарную стоимость описаний в токенах.

Инварианты (их проверяет валидатор — не полагайся на внимательность)

• name во фронтматтере == имя папки, kebab-case, ≤ 64 символов.
• description ≤ 1024 символов (лимит валидации Anthropic), ориентир 600–900.
• Фронтматтер только из ключей name, description, metadata, allowed-tools, license; в metadata — только version и verified.
• Все ссылки вида references/*.md разрешаются; осиротевших файлов в references/ нет.
• В корне навыка только SKILL.md (плюс references/, scripts/, templates/); никаких REFERENCE.md.
• README: каталог и бейдж «Skills: N» совпадают с составом.
• .claude-plugin/plugin.json и marketplace.json — одна и та же версия.
• Изменил навык — бампни metadata.version этого навыка и версию plugin.json (иначе кэш маркетплейса не увидит обновление).

Что важно помнить про стоимость

Описания всех навыков лежат в системном промте каждой сессии — сейчас это ~16.5 тыс. символов ≈ 9–10 тыс. токенов, включая сессии, где не нужен ни один навык. Кириллица стоит примерно вдвое дороже латиницы на символ. Отсюда правила:

• описание — дискриминатор, а не аннотация: первое предложение отличает навык от ближайшего соседа (объект + момент жизненного цикла + артефакт), а не пересказывает содержание тела;
• 3–6 сильных триггер-фраз вместо 10–15 near-синонимов — модель обобщает сама;
• анти-коллизионный указатель обязателен и сжат до формулы «Для X — см. Y»;
• каждая цитата-триггер в кавычках либо взята из реального запроса, либо является общепринятым термином индустрии. Третьего не дано: выдуманная фраза занимает место в системном промте каждой сессии и не срабатывает никогда. Формулировки берутся из практики и обезличиваются: в публичном репозитории не должно быть доменов, серверных путей и имён проектов;
• тело навыка ≤ ~150 строк; тяжёлое выносится в references/ (progressive disclosure — оно грузится только при срабатывании).

Слово «аудит» уже несут 9 навыков из 24 (шесть — в имени: django-audit, dependency-auditor, test-coverage-auditor, python-project-audit, migration-safety-auditor, aiogram-bot-auditor). Новому навыку нужен собственный глагол (диагностика, тюнинг, проектирование, runbook, настройка), иначе он растворится в общем шуме.

Язык

Описания и тела навыков — русский; он же задаёт язык взаимодействия. На английском: имена навыков и файлов, идентификаторы, сообщения коммитов (Conventional Commits), технические термины без хорошего перевода.

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

• Не переименовывать существующие навыки: имена зашиты в маршрутизацию пользовательского CLAUDE.md и в память сессий.
• Не переписывать работающие тела ради стиля.
• Не добавлять зависимости в scripts/ — только стандартная библиотека, чтобы валидатор запускался на любой ОС без venv.
• Не мутировать рабочий репозиторий из тестов: test_validate_skills.py работает только во временных копиях и защищён guard().
• Не удалять и не «оптимизировать» evals/: роутинг-eval — единственный поведенческий тест библиотеки; аналоги есть у эталонов жанра (anthropics/skills, obra/superpowers).

Целевой профиль

Навыки заточены под Python-бэкенд (Django / FastAPI / aiogram) с деплоем на одиночный Linux-сервер без Docker (systemd + nginx + postgres + redis), а не под универсальную аудиторию. Это про предметную область, а не про машину читателя.

Переносимость (библиотека публичная)

Её ставят себе люди на другой ОС, с другой оболочкой и в другом ИИ-ассистенте. Поэтому в отслеживаемых git файлах не должно быть:

• утверждений о среде пользователя как о факте («машина пользователя — X», «у тебя — да»): на чужой машине это ложь, и агент строит на ней команды;
• команд одной оболочки без кросс-платформенной ветки. Предпочитай инструменты агента (Read/Grep/Glob) и голый git/uvx; если без оболочки никак — дай обе ветки;
• личных данных: имён, машинных путей, доменов, имён рабочих проектов. Авторство в LICENSE и манифестах плагина — исключение;
• зависимостей от внешнего CLI или слэш-команд конкретной сборки без объявленного предусловия и fallback.

Исключение — навыки, которым платформа посвящена по теме (vps-ops — systemd, nginx, Linux-сервер). Там конкретика и есть предмет, а не предположение о читателе.

Проверка: python scripts/validate_skills.py --strict — правило portability.