Выложил в опенсорс свой агентский пресет для создания документации

https://github.com/AlexJameson/agent-user-doc-preset

В этом августе исполняется год с момента, когда я впервые показал команде, на что могут быть способны агенты в плане создания документации. Вероятно, это была самая нелепая демонстрация за всю историю —в прямом эфире я в течение нескольких минут набирал промпт, который должен был заменить фрагмент одного регулярного выражения, и ждал окончания работы. В процессе пошло не так абсолютно всё, а результат оказался закоммичен не в ту ветку.

С тех пор я многому научился, много сделал сам и помог со множеством запросов, в которых была одна и та же тема — как объяснить агентам, что нужно для создания хорошей доки. Интересно, что этот вопрос беспокоит не только техписов, но и других специалистов — я окончательно решил допилить свой пресет до готового состояния в ходе дискуссии в чате канале Ивана Бегтина.

В общем, я сформировал набор из двух скиллов и одного agent definition, которые, на мой взгляд, закрывают минимальные потребности большинства проектов. Я противник подборок типа Superpowers, которые по умолчанию забивают контекст десятками скиллов и целятся во все возможные юзкейсы сразу.

Мой пресет работает иначе, создавая фундамент, который можно потом достроить:

1. Самая важная часть пресета —навык scan-user-docs, который анализирует содержимое репозитория и фиксирует контракты в виде Markdown KV. Это обычный маркдаун, в котором есть понятная структура данных, адаптированная для чтения как агентами, так и людьми. При сканировании он определяет размер репозитория и примерный тип, то есть разделяет продуктовую документацию с условными репозиториями с кодом, где дока —один README. Результат записывается в виде трёх контрактов —STRUCTURE.md, TOOLING.md и STYLE.md, которые потом можно расширять и изменять по своему усмотрению.

2. Навык maintain-user-docs призван дать агентам минимальное руководство по тому, как в принципе создавать документацию. Агент с этим навыком пытается сразу определить тип документа, с которым сейчас работает, по топологии Diataxis. В качестве базовых стилистических рекомендаций для русского и английского языков используются отдельные рекомендации в стиле STE100 с примиерами хороших и плохих текстов (можно и нужно добавлять свои примеры). Также переиспользуются контракты, создаваемые scan-user-docs.

3. Последняя часть —primary agent для OpenCode. Он содержит некоторые дополнительные правила и рекомендации, но в целом опционален. Его главная цель —по умолчанию загружать в контекст все контракты. Его рекомендуется адаптировать для своих правил и особенно для других харнесов.

Я уверен, что примерно так может выглядеть скелет системы контекста для любого проекта, который в дальнейшем можно развивать и адаптировать. Посмотреть на результат генерации для моего тестового сайта с документацией можно в моем репозитории на SourceCraft. Помимо этого проекта, я запускал генерацию в публичном репозитории Yandex Cloud, в нескольких опенсорсных репозиториях (с той самой докой в README) и даже для своей базы знаний. Модели для агентов тоже использовал разные — точно были GPT-5.6, Kimi K3, Qwen 3.8 27b, и везде получались достаточно полезные результаты.

Подробнее обо всех деталях и установке пресета смотрите в репозитории, ну и оставляйте обратную связь