skills

Скиллы лежат в категориях под skills/:

• autonomy/ — работа, когда человека нет за компьютером;
• deprecated/ — выведенные из обращения, не ставятся и не публикуются.

Каждый скилл вне deprecated/ обязан иметь: запись в массиве skills файла .claude-plugin/plugin.json, ссылку в корневом README.md и в README.md своей категории, страницу в docs/<категория>/<имя>.md. Скиллы из deprecated/ не должны появляться нигде из перечисленного. scripts/validate.sh проверяет эти инварианты и гоняется в CI.

Репозиторий публичный — значит, ничего личного в файлах: адреса серверов, логины, токены и пути вида /home/имя/ живут в ~/.config/claude-skills/, а в репозитории от них остаются только переменные и SETUP.md.

Соглашение, на котором держится установщик

skills/<категория>/<имя>/SKILL.md   обязателен; каталог линкуется в <область>/skills/<имя>
skills/<категория>/<имя>/bin/*      → ~/.local/bin/ по одному файлу
skills/<категория>/<имя>/claude/*   → ~/.claude/ по одному файлу
skills/<категория>/<имя>/SETUP.md   если нужна разовая настройка руками
skills/<категория>/<имя>/setup.sh   разовая настройка вопросом при установке
skills/<категория>/<имя>/lib/*      общий код скилла; никуда не линкуется
skills/<категория>/<имя>/permissions.json  правила → ~/.claude/settings.json
skills/<категория>/<имя>/hooks.json        хуки   → ~/.claude/settings.json
skills/<категория>/<имя>/requires.txt      команды, без которых скилл неполон

requires.txt — строки вида команда — зачем она нужна; установщик проверяет их наличие и предлагает доставить пакетным менеджером. setup.sh установщик запускает следом, передав SKILLS_ASSUME_YES; скрипт спрашивает своё и пишет ответ в ~/.config/claude-skills/<имя>.env, а при повторной установке молчит, если ответ уже есть. Установщик при этом по-прежнему не знает, о чём спрашивают. permissions.json — список правил (["Bash(afk:*)", …]), hooks.json — объект {событие: [группы хуков]}. Установщик добавляет их в пользовательские настройки, снятие убирает. Хук, который скилл включает и выключает по ходу дела, всё равно ставится заранее: дописанный в настройки посреди сессии, он может не подхватиться.

Область — ~/.claude (по умолчанию) либо <проект>/.claude (--local, --project). Скилл — единственное, что кладётся в проект: команды и файлы окружения всегда общие, потому что $PATH один на систему, а скрипты ищут окружение по путям от $HOME. Отсюда правило снятия: из проекта уходит только сам скилл, см. .agents/adr/0002-окружение-всегда-глобальное.md.

install.sh не содержит перечня скиллов и знать про них не должен. Если новому скиллу не хватает этого соглашения — сначала подумай, как обойтись им, и только потом расширяй установщик: правило, действующее для всех, лучше частного случая в коде.

Добавление скилла

./scripts/new-skill.sh <категория>/<имя> [--bin], затем правка SKILL.md, затем ./scripts/validate.sh. Заводить каталоги руками не нужно. После добавления, переименования или смены поведения скилла — пересобрать его страницу в docs/ по .agents/writing-docs.md и обновить оба README.md и plugin.json.

description во фронтматтере — главный текст скилла: по нему модель решает, открывать его или нет. Пиши поводы словами человека («ухожу спать», «доделай без меня»), а не терминами скилла. Действие в начале, поводы после. Про то, кем скилл вызывается, — .agents/invocation.md.

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

./scripts/validate.sh должен проходить без ошибок. Замечания (!) не валят проверку, но просто так не заводятся.

Скрипты в bin/ — bash со set -euo pipefail, комментарий-справка вверху файла в том же виде, что у существующих: строчка «что делает», пустая, примеры вызова.

Версия плагина в .claude-plugin/plugin.json и запись в CHANGELOG.md меняются вместе: по версии Claude Code решает, показывать ли обновление тем, кто поставил плагином.

Язык репозитория — русский, включая комментарии в скриптах и сообщения об ошибках.