/audit-agent-rules

name: audit-agent-rules
description: Audits the agent rules in the current folder (AGENTS.md, nested AGENTS.md files) and the skill descriptions the agent sees at start, then reports what to cut, move or rewrite and edits only after the user says yes. Use on «аудит правил», «проверь AGENTS.md», «почему агент не слушается правил», «проверь скиллы».

Аудит правил агента

Скилл проверяет файлы правил агента в текущей папке и каталог скиллов, который агент видит на старте. Отдаёт отчёт таблицей: что не так и как сделать лучше. Файлы меняет только после «да» человека.

Скилл обычно зовёт человек без опыта в программировании: он ведёт папку с агентом для своей работы. Отчёт пиши простыми словами, на языке человека; термин объясняй один раз через то, что он меняет в работе агента.

Что проверяется

• `AGENTS.md` в текущей папке и во всех её подпапках. Его читают Claude Code, Codex, Cursor и другие агенты, поэтому аудит строится вокруг него.
• `CLAUDE.md`, `CLAUDE.local.md` и `.claude/rules/` попадают в отчёт одной находкой, если в них свой текст: тогда Claude Code читает одни правила, остальные агенты другие. Разбирать их построчно не нужно.
• Скиллы из `.agents/skills` и `.claude/skills` этой папки (и папок выше до корня git-репозитория), `~/.agents/skills`, `~/.codex/skills`, `~/.claude/skills`.

Четыре мерила

1. **Каждая строка правил: маршрут, граница или постоянное поведение.**

| Вид | Что делает | Пример | |---|---|---| | Маршрут | Ведёт к файлу или скиллу под задачу | «Пост в канал пиши через скилл `telegram-post`» | | Граница | Что можно и что нельзя | «`archive/` только читать» | | Постоянное поведение | Действует на любой запрос | «Отвечай по-русски, коротко» |

Строка другого вида уходит из файла: процедура с шагами в скилл или `docs/`, история решений в git, справка в `docs/`, правило одной подпапки во вложенный `AGENTS.md`. Проверка строки: если её удалить, агент ошибётся? Если нет, строка лишняя.

2. **Файл до 200 строк.** Ориентир Anthropic: длинный файл занимает контекст, и агент хуже соблюдает правила. Codex читает все `AGENTS.md` от корня репозитория до папки, где его запустили, в общий бюджет 32 KiB (32 768 байт в UTF-8). Кириллическая буква весит 2 байта. Что не влезло, Codex обрезает и не читает.

3. **`AGENTS.md` работает навигатором.** Детали лежат в своих файлах и скиллах, в правилах остаётся строка-маршрут: «Для X открой Y» или «X пиши через скилл Z». Вложенный `AGENTS.md` агент гарантированно читает только в сессии, начатой в его папке, поэтому у каждого вложенного файла есть маршрут из корневого.

4. **Описание скилла отвечает на вопрос «когда меня брать».** Поле `description` говорит, что скилл делает, и когда его брать или по каким фразам. Оно короткое и не пересекается с описаниями других скиллов. Каталог описаний агент видит на старте целиком, тело скилла читает по требованию. У Codex стартовый список скиллов ограничен 2% окна контекста (8 000 символов, если окно неизвестно): при переборе он сокращает описания, и часть скиллов выпадает из списка. Claude Code обрезает описание одного скилла после 1 536 символов.

Порядок работы

1. **Замерить.** Запусти сканер из папки этого скилла: `python3 <папка скилла>/scripts/scan.py .` Он только читает и печатает разделы: файлы правил со строками и байтами, `CLAUDE.md` и `.claude/rules`, цепочки Codex, вложенные файлы без маршрута, подсказки по строкам, каталог скиллов, маршруты в никуда. Всё, что он нашёл, кандидаты: каждое срабатывание ты подтверждаешь чтением. Если Python нет, посчитай то же вручную. Готово, когда прочитан весь вывод.

2. **Отделить правила папки от образцов.** Рабочий файл подпапки (правила, по которым агент работает в ней) разбирается построчно. Образец для другой папки (шаблон, раздатка, архив, пример в материалах) идёт в отчёт одной строкой «образец, построчно не разбирал». Агент всё равно подгружает образец, когда работает в его папке; если это мешает, скажи об этом в той же строке.

3. **Разметить строки.** Прочитай корневой `AGENTS.md` и каждый вложенный файл правил целиком. Каждой строке дай вид из мерила 1 или пометку «уходит» с местом назначения по [references/where-lines-go.md](references/where-lines-go.md). Подсказки сканера (история, шаги, код, длинная строка) показывают, куда смотреть первым делом; решение по строке за тобой. Попутно отметь дубли между файлами, противоречия и маршруты на несуществующие файлы, папки и скиллы. В противоречии выбирает человек: в правке назови оба варианта и спроси, какой оставить. Готово, когда размечена каждая строка каждого рабочего файла правил.

4. **Проверить маршруты.** Для каждого вложенного `AGENTS.md` найди в корневом строку, которая к нему ведёт. Сканер ищет в тексте путь вида `папка/AGENTS.md`: найденная строка должна быть маршрутом и называть задачу, а маршрут, который называет только папку, проверь глазами. Цепочку Codex больше 32 768 байт назови с местом обрезки.

5. **Проверить каталог описаний.** Сверь сумму символов с 8 000: у модели с большим окном бюджет больше, но сумма в разы выше 8 000 значит, что Codex сокращает описания. Прочитай каждое описание: есть ли «что делает» и «когда брать». Пары из таблицы похожих описаний прочитай и реши, пересекаются ли они по задаче. Отдельно отметь копии одного скилла в нескольких папках и битые ссылки. Скиллы плагинов и встроенные скиллы сканер не видит: напиши это одной строкой в отчёте.

6. **Отчёт.** По шаблону ниже. Сначала то, чего агент не видит совсем (обрезка Codex, нет маршрута, два набора правил), потом строки не своего вида, потом скиллы. В таблице до 15 строк с самым большим эффектом, остальное коротко в «Ещё». Скилл из домашней папки помечай «общий для всех папок».

7. **Спросить «Переписать?».** Дальше ничего не меняй, пока человек не ответил «да» или не назвал номера строк таблицы.

8. **Переписать.** До первой правки сохрани исходники: в git-репозитории проверь, что изменения человека закоммичены или он согласен работать поверх них; без git скопируй фай