Навички та інструменти
Спільні навички зберігаються в .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:
| Застосунок | Інструкції проєкту | Навички, які використовує цей репозиторій | Власні агенти, які використовує цей репозиторій |
|---|---|---|---|
| Codex | AGENTS.md | .agents/skills/<name>/SKILL.md | Згенерований .codex/agents/<name>.toml |
| Claude Code | CLAUDE.md імпортує @AGENTS.md | Згенерований .claude/skills/<name>/SKILL.md | Згенерований .claude/agents/<name>.md |
Джерела: навички Codex, субагенти Codex, пам’ять Claude, навички Claude, субагенти Claude.
Не замінюйте нативні каталоги агентів на .agents/roles і не припускайте, що Claude знаходить .agents/skills. Claude однаково може прочитати файл звідти, на який є посилання, як звичайний контекст проєкту.
Каталоги AI використовують закінчення рядків 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.