Перейти до основного вмісту

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

Спільні навички зберігаються в .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 однаково може прочитати файл звідти, на який є посилання, як звичайний контекст проєкту.

Каталоги 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.