Перейти к основному содержанию

Навыки и инструменты

Общие навыки находятся в .agents/skills/. Редактируйте эти исходники, а затем запускайте yarn ai-workflow:sync, чтобы сгенерировать .claude/skills/ для Claude Code. Codex находит навыки напрямую в каталоге .agents/skills/.

Общие промпты ролей находятся в .agents/roles/*.md. Это специфичный для репозитория формат исходников, а не нативный путь обнаружения агентов. scripts/ai-workflow-files.mjs преобразует эти исходники в файлы для конкретных приложений, перечисленные ниже, а yarn ai-workflow:sync их записывает. Коммитьте сгенерированные файлы вместе с их исходниками, чтобы свежий чекаут сразу получал нативную конфигурацию без предварительного запуска генератора. Удалив исходник, явно удалите и его устаревшие сгенерированные файлы: валидатор сообщает о них, а не удаляет их молча.

Нативные пути обнаружения​

Сверено с официальной документацией 2026-09-12:

ПриложениеИнструкции проектаНавыки, используемые в этом репозиторииКастомные агенты, используемые в этом репозитории
CodexAGENTS.md.agents/skills/<name>/SKILL.mdСгенерированный .codex/agents/<name>.toml
Claude CodeCLAUDE.md импортирует @AGENTS.mdСгенерированный .claude/skills/<name>/SKILL.mdСгенерированный .claude/agents/<name>.md

Источники: навыки Codex, субагенты Codex, память Claude, навыки Claude, субагенты Claude.

Не заменяйте нативные каталоги агентов на .agents/roles и не рассчитывайте, что Claude обнаруживает .agents/skills. При этом Claude может прочитать оттуда файл, на который есть ссылка, как обычный контекст проекта.

Каталоги для ИИ используют окончания строк LF через .gitattributes, чтобы сгенерированный текст был одинаковым на всех платформах. Вспомогательные файлы навыков копируются побайтно.

Навыки​

НавыкНазначение
commitСоздание авторизованных локальных коммитов в рамках задачи
commit-format, issue-formatПредложения по формату, когда их запрашивают
make-closed-issueСоздание авторизованного issue, коммита в рамках задачи и PR
review-and-merge-prРазбор отзывов на PR; исправление, публикация и слияние только в пределах запрошенного объёма
fix-merge-conflictsРазрешение конфликтов и проверка результата слияния
releaseПодготовка текста релиза и выполнение авторизованных шагов релиза
code-quality-reviewРевью нетривиальных диффов или явно запрошенного вопроса о качестве
retroПревращение реально допущенных ошибок в точечные проверки или рекомендации, которые не дают им повториться
refactor-pass, deslopЗапрошенная чистка уже внесённых изменений
debug-agentОтладка на основе свидетельств, при необходимости с инструментированием
you-might-not-need-an-effectТочечное ревью эффектов и memo
vercel-react-best-practicesПрименимые рекомендации по производительности React; правила только для Next.js и сервера пропускайте для этого клиента на Vite
translateГенерация переводов с последующим применением карт через единственный процесс записи
playwright-cli, inspect-elementsПроверка в браузере и сопоставление DOM с исходным кодом
profile-browsingПрофилирование браузера и React в заданных рамках
test-apkПроверка предоставленной сопутствующей Android-обёртки
impeccable, improve-threejsДизайн интерфейса в заданных рамках и ревью рендеринга Three.js
implement-planВыполнение плана с необязательным ограниченным делегированием
readmeПоддержка проверенной документации проекта
context7Получение документации библиотек для нужной версии
find-skillsПоиск дополнительных навыков по явному запросу

Роли и модели​

Сохраняйте кастомные роли для browser-check, profiler, test-apk, translator и reviewer. Для обычной реализации и поиска по коду используйте встроенные в среду агента роли worker/general-purpose или explorer. Родительский агент назначает критерии приёмки и владение; тяжёлые проверки запускает один владелец.

Файлы агентов Codex содержат name, description и developer_instructions. .codex/config.toml ограничивает число одновременно работающих дочерних агентов четырьмя через max_concurrent_threads_per_session. Общие метаданные ролей содержат имя, описание и необязательный режим песочницы; полей модели в них намеренно нет.

Не указывайте поля модели и уровня рассуждений в закоммиченных навыках и кастомных агентах. Тогда действуют выбор при вызове, пользовательские значения по умолчанию и наследование от родителя в порядке приоритета, задокументированном для каждого приложения. Алиасы семейств Claude избавляют от части обновлений при смене версий, но всё равно фиксируют семейство. При необходимости держите такие выборы в настройках пользователя или сессии. Наследование не гарантирует автоматического выбора лучшей текущей модели. Не придумывайте алиас latest и не добавляйте изучение каталога моделей в рутинные задачи. См. выбор модели в Codex и выбор модели в Claude.

sandbox-mode: read-only соответствует песочнице Codex. В Claude рабочий процесс ревью ограничивают список инструментов и инструкции роли, но доступ к Bash не является песочницей на уровне ОС.

Во фронтматтере общих навыков для рабочих процессов, которые вызывает пользователь, там, где это применимо, указывается disable-model-invocation: true. Соответствующая настройка Codex находится в agents/openai.yaml в виде policy.allow_implicit_invocation: false; валидатор требует обе. Метаданные вызова дополняют явные правила авторизации; запрос на ревью никогда не разрешает публикацию лишь потому, что навык содержит шаги публикации.

Проверки и обнаружение​

  • yarn ai-workflow:sync заново генерирует файлы совместимости с помощью установленных js-yaml и smol-toml.
  • yarn ai-workflow:check разбирает исходники, фронтматтер и конфиги, проверяет сгенерированные файлы, метаданные вызова, размещение полей модели и подключение хука, который только форматирует код. Он не сверяет идентификаторы моделей с каталогом провайдера.
  • yarn ai-workflow:test запускает изолированные фикстуры Node для полезной нагрузки хуков и для генерации и валидации рабочего процесса.
  • После обновления агентского приложения проверьте в нём обнаружение навыков и ролей. Проверки синтаксиса и соответствия копий не заменяют проверку загрузчиком. Перезагрузите приложение, если в существующей сессии остался старый каталог.
  • Хукам нужны доверие к проекту и одобрение хуков в среде агента; не обходите механизм доверия только ради того, чтобы проверка прошла. См. hooks-setup.md.

Как поддерживать инструкции полезными​

Следуйте рекомендациям OpenAI по навыкам и промптам (просмотрено 2026-09-12): пишите точные описания, подгружайте подробности только тогда, когда они нужны, и сохраняйте запрошенный пользователем объём работы. Общие навыки обслуживают разные модели; сохраняйте специфичные для проекта инварианты, оставляя свободу в рутинных решениях по реализации.

Держите в SKILL.md назначение навыка, границы принятия решений и существенные ограничения. Объёмные команды или примеры для отдельных режимов выносите в необязательные справочные файлы и ссылайтесь на них. Помещайте условия срабатывания в начало коротких описаний; одно лишь совпадение по ключевому слову не должно расширять задачу. Сохраняйте существующие метаданные вызова, если только их поведение не меняется намеренно.

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

Инструменты и владение браузером​

Отдавайте предпочтение существующему каталогу навыков и инструментов и установленным CLI проекта. Используйте gh для GitHub, playwright-cli для проверки в браузере и официальную документацию для нужной версии, когда важно поведение библиотеки. Не устанавливайте дублирующие навыки и не загружайте незакреплённый пакет только ради запуска уже имеющегося форматтера.

Накладные расходы MCP зависят от среды агента: отложенная загрузка инструментов позволяет не загружать все схемы заранее. Оставляйте только релевантные интеграции, но не считайте MCP как таковой устаревшим. Уже сделанный выбор в пользу CLI по-прежнему полезен для воспроизводимости и контроля ресурсов.

Все браузерные сессии используют ./scripts/pw-session.sh, который допускает только один активный браузер на всей машине. По умолчанию используйте свежую изолированную сессию. Доступ к текущему личному браузеру требует явной авторизации; на последующих шагах переиспользуйте уже полученную авторизацию. Выбирайте браузеры и вьюпорты по затронутому поведению, запускайте выбранные движки последовательно, при очистке закрывайте именно ту сессию, которую открыли, по её имени и никогда не используйте close-all/kill-all. См. навык playwright-cli и verification.md.