Де має знаходитися кожна інструкція: AGENTS.md, CLAUDE.md та SKILL.md

Понад 4 300 інженерів проголосували за один питання на GitHub, у якому пропонується, щоб Claude Code завантажував файл AGENTS.md без додаткової допомоги. У липні 2026 року, у версії 2.1.201, це все ще не відбувається. Власна документація щодо пам’яті від Anthropic тепер пояснює розробникам, як все одно змусити програму діяти так, як потрібно: потрібно виконати команду ln -s AGENTS.md CLAUDE.md у терміналі. Фактично виробник надає обхідний спосіб для файлу, який його власний інструмент відмовляється читати.

Аргументи є менш цікавою частиною. Справжня інженерна майстерність проявляється у одному рядку документа claude-api SKILL.md у публічному репозиторії навичок Anthropic, у полі опису його YAML-файлу. На відміну від CLAUDE.md та AGENTS.md, саме цей опис визначає, чи буде Claude взагалі читати решту файлу. У справі задіяні три файли та три моделі завантаження, а питання щодо їх розташування знаходить відповідь, як тільки стає видно відповідний механізм.

Як виник розподіл

Часова шкала показує, як індустрія дійшла до цього стану. У серпні 2025 року була оприлюднена специфікація AGENTS.md як універсальний набір інструкцій для AI-асистентів з програмування. Команди створення, правила тестування та архітектура проєкту могли знаходитися в одному місці, ідея полягала у тому, щоб як Cursor, Copilot, так і самостійні агенти використовували цей єдиний файл.

У жовтні 2025 року, через два місяці, Anthropic представила Agent Skills, яка використовувала інший підхід до роботи з контекстом. Замість простого markdown-файлу з правилами скілл є каталогом із власними метаданими, скриптами та документами для посилань.

До грудня 2025 року обидві формати стали відкритими стандартами. Специфікація навичок була опублікована на agentskills.io, тоді як специфікація AGENTS.md була передана Linux Foundation як основний проект для Agentic AI Foundation. Зараз понад 60 000 репозиторіїв та близько двох десятків інструментів підтримують AGENTS.md без додаткових налаштувань, тому жоден зі стандартів не зникне.

У результаті команди тепер пишуть однакові інструкції у трьох місцях: AGENTS.md для редактора, CLAUDE.md для терміналу та SKILL.md для складних робочих процесів. Потім вони дивуються, чому агенти працюють повільніше та чому зростають витрати на токени. Рішення починається з того, як ці інструменти насправді аналізують текст.

Бар’єр для навички

Сесія не починається з того, що агент читає кожен файл у проекті, оскільки це спричинить переповнення вікна контексту та знизить увагу моделі. Натомість він шукає певні точки входу та навички, які за цими точками входу діють за принципом поступового розкриття інформації.

Під час запуску агент завантажує метадані кожної встановленої навички до системного запиту. Ці метадані включають назву та опис, що коштує приблизно 100 токенів на навичку. Потім агент читає запит користувача, порівнює його з завантаженими описами та вирішує, чи потрібно розкрити основну частину навички. Опис виступає як бар’єр, а додаткові матеріали залишаються закритими позаду нього.

Нижче наведено фронтматер навички claude-api, як він опублікований у відкритому репозиторії Anthropic.

---
name: claude-api
description: |
  Reference for the Claude API / Anthropic SDK — model ids, pricing, params,
  streaming, tool use, MCP, agents, caching, token counting, model migration.
  TRIGGER — read BEFORE opening the target file; don't skip because it "looks
  like a one-liner" — whenever: the prompt names Claude/Anthropic in any form
  (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`,
  `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/
  model choice/limits/caching) — never answer from memory; OR the task is
  LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/
  RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/
  converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens).
  SKIP only when another provider is being worked on (overrides all triggers):
  OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR
  `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|
  cohere|ollama'` over the project hits (run this grep FIRST if no provider
  named — don't Read the file).
license: Complete terms in LICENSE.txt
---

# Claude API reference

Model IDs, pricing, request/response shapes, tool use, MCP, caching,
streaming, and migration notes for the Anthropic SDK.

... (body continues; only loaded if the description above passes the gate)

Поле опису виконує подвійну функцію. Воно пояснює агенту, що робить ця навичка, і водночас слугує інтерфейсом програмування, через який автор навички кодує логіку запуску.

TRIGGER та SKIP — це узгоджені назви, а не поля, визначені схемою. Автор просто пише інструкції звичайною англійською мовою про те, коли слід активувати цей механізм. Текст цієї навички може налічувати сотні рядків посилань на API. Якщо є запитання щодо бази даних Postgres, перевірка опису провалюється, і посилальний текст залишається невикористаним.

CLAUDE.md та AGENTS.md функціонують інакше. У них немає еквівалентного механізму активації. Як тільки агент знаходить їх у шляху виконання, він вставляє їх на початок сеансу, і вони залишаються активними протягом усієї розмови.

Що має знаходитися в кожному файлі

Модель завантаження визначає зміст. Вставлений файл має містити лише те, що потрібно агенту на кожному кроці. Файл із контролем доступу має містити спеціалізовані знання, які застосовуються до певних завдань.

Репозиторій під назвою orchard демонструє, як ці файли можуть існувати разом на диску без дублювання інформації.

orchard/
├── AGENTS.md                          # root: shared, tool-agnostic project context
├── CLAUDE.md                          # 6 lines: imports + Claude-specific memory tiers
├── README.md                          # for humans
├── .github/
│   └── workflows/
│       └── skills-to-agents.yml       # dave1010/skills-to-agents@v2 → emits <skills> block into AGENTS.md
├── .agents/
│   └── skills/
│       └── db-migration/
│           ├── SKILL.md               # YAML frontmatter + body; loads only when description gate matches
│           ├── scripts/
│           │   └── check_reversibility.py
│           └── references/
│               └── postgres-lock-modes.md
├── services/
│   └── payments/
│       └── AGENTS.md                  # nested: subproject-specific rules; nearest-file-wins
└── packages/
    └── ui/

AGENTS.md містить спільні правила створення проекту, включаючи рекомендації щодо стилю, структуру монорепозиторію, інструкції щодо запуску тестів та примітки про залежності. Це базовий контекст, необхідний кожному агенту, незалежно від інструменту, який його читає. Його характерною рисою є пріоритет найближчого файлу: агент, який працює у директорії services/payments/, спочатку читає вкладений AGENTS.md та віддає перевагу його локальним правилам перед правилами кореневої директорії. OpenAI керує своїм внутрішнім контекстом за допомогою моделі монорепозиторію з 88 файлами, і вкладені файли дозволяють зберігати лаконічність, завантажуючи лише те, що потрібно поточній директорії.

CLAUDE.md має вужчу функцію. Він містить директиви, які мають сенс лише тоді, коли активним агентом є Claude Code.

Надмірний об’єм — це поширена проблема з файлами CLAUDE.md. Розробники вставляють усі свої файли AGENTS.md до CLAUDE.md, припускаючи, що Claude потребує власної копії правил компіляції. Натомість правильна мінімальна форма імпортує спільний стандарт у контекст Claude.

# Project instructions for Claude Code

@AGENTS.md

## Claude-specific

- Prefer `Explore` subagent for cross-file searches over 3 files; single grep otherwise.
- User-level memory lives at ~/.claude/CLAUDE.md — do not duplicate its rules here.

<!--
Alternative if you do not want an @ import and prefer one file on disk:

    ln -s AGENTS.md CLAUDE.md

This is Anthropic's own recommendation for repos that keep AGENTS.md canonical
and have nothing Claude-specific to add. See docs.claude.com/en/docs/claude-code/memory.
-->

Правило, яке застосовується до кількох інструментів, має знаходитися у AGENTS.md. Імпорт з @AGENTS.md є основним паттерном, рекомендованим у документації Anthropic щодо пам’яті, тоді як символічний посилання є альтернативою для репозиторіїв, у яких немає нічого специфічного для Claude, але які просто хочуть, щоб інструмент читав стандартний файл.

SKILL.md — це шар умовних можливостей, місце для повторюваних робочих процесів, одноразових функцій та глибокого лексикону конкретної галузі. У orchard папка .agents/skills/db-migration/ містить усе необхідне для безпечної міграції в Postgres, а саме скрипт на Python для перевірки зворотності та примітку у форматі markdown про режими блокування в Postgres. Жоден з цих елементів не належить до AGENTS.md. Агент, який редагує файл CSS у пакеті UI, не повинен отримувати інформацію про режими блокування у своєму системному запиті. Механізм опису гарантує, що ця функція завантажуватиметься лише тоді, коли буде змінений файл міграції.

Правило маршрутизації

Як тільки процес завантаження моделей завершиться, додавання нового контексту стає механічним процесом:

• Спільний контекст проекту, незалежний від інструментів, який потрібен на кожному кроці, розміщується у файлі AGENTS.md.
• Інструкції, призначені лише для Claude Code, потрібно помістити у файл CLAUDE.md, бажано у вигляді короткого файлу, який імпортує AGENTS.md.
• Ситуативні робочі процеси, скрипти та посилання на конкретні сфери, необхідні лише для деяких завдань, розміщуються у окремому модулі, після опису, який вказує, коли його використовувати.

Контроль бюджету постійної активності

Різниця між умовним та постійним завантаженням безпосередньо пов’язана з продуктивністю агента.

Дослідження від січня 2026 року (arXiv:2601.20404), проведене дослідниками з Кінгс-коледжу Лондона, Університету управління Сінгапуру, Університету Гейдельберга та Університету Бамберга, вивчало фактичну роботу файлів AGENTS.md. Час виконання агентами скоротився на 28,64%, кількість вихідних токенів — на 16,58%, при цьому завдання виконувалися з подібною швидкістю. Спільний рівень інструкцій робить агентів більш ефективними. Вони перестають вигадувати команди для створення та запускати неправильні набори тестів, оскільки модель один раз читає канонічні правила та приступає до виконання завдання.

Ця ефективність зберігається лише тоді, коли контекст залишається релевантним. Кожен токен, який додається до системного запиту, привертає увагу моделі. Припустимо, команда вставляє 500-слівний посібник з міграції баз даних у файл AGENTS.md. Тоді агент змушений читати його під час виправлення помилок у фронтенд-частині, приділяючи увагу режимам блокування Postgres, тоді як йому слід думати про хуки React.

Умовне завантаження захищає досягнуті результати. Переміщення ситуативних робочих процесів у файл SKILL.md зберігає файл AGENTS.md легким, що дозволяє скористатися перевагами спільного контексту під час виконання та уникає витрат на обробку інструкцій, які не є актуальними.

Міст, який існує, та той, що немає

У екосистемі існує прогалина у підтримці перекладу. Claude Code розуміє навички та механізми їхнього розкриття, але Cursor, Copilot та окремі інструменти CLI не підтримують структуру .agents/skills/ за замовчуванням.

Команда, яка створює навичку міграції баз даних, хоче, щоб користувачі Cursor також могли від неї скористатися. Ручне копіювання цієї навички до AGENTS.md зруйнує єдине джерело істини, тому рішенням є її компіляція.

Потім агенти, які не є Claude, зможуть бачити ці навички без необхідності їх ручного копіювання. Створений блок у AGENTS.md проекту Orchard виглядає ось так.

# Project agents

Build with `pnpm build`. Test with `pnpm test`. Migrations under
`services/payments/migrations/` must run through the db-migration skill.

## Style

- TypeScript 5.x, strict mode on. No `any` in new code.
- Errors surface as structured `AppError` with a `code` field, never raw strings.

<!-- BEGIN skills-to-agents (auto-generated; edit .agents/skills/*/SKILL.md) -->
<skills>
  <skill name="db-migration" path=".agents/skills/db-migration/">
    Run a Postgres migration end-to-end. TRIGGER whenever the user asks to
    add/modify a migration, backfill a column, or lock-analyze a schema
    change. SKIP if the query is purely a read-only SELECT / EXPLAIN.
  </skill>
  <skill name="release-notes" path=".agents/skills/release-notes/">
    Draft the release notes for a merged PR. TRIGGER on "cut a release",
    "write release notes", or "prep the changelog". SKIP if the PR is a
    dependency bump.
  </skill>
</skills>
<!-- END skills-to-agents -->

## Repo layout

- `services/` — deployable services, each with its own AGENTS.md
- `packages/` — shared libraries
- `.agents/skills/` — Conditional workflows

Цей міст виводить назву, шлях та опис кожної навички. Агенти, що не є Claude, не мають вбудованої функції поступового розкриття цих директорій, тому резюме у блоку навичок виступає їхнім інтерфейсом: інструмент, який читає AGENTS.md, знаходить цей блок, читає умови активації та визначає, де на диску шукати інформацію для міграції.

Міст, якого все ще бракує, — це можливість для Claude Code читати AGENTS.md безпосередньо, без необхідності імпорту чи створення символічних посилань. На ринку прогнозів Manifold продовжуються торги щодо того, чи запровадить Anthropic таку підтримку до кінця року. Ця прогалина свідчить про те, що розробники інструментів хочуть контролювати власний шар контексту. Anthropic володіє CLAUDE.md, а спільнота — AGENTS.md. Міжсистемна сумісність буде залежати від інструментів та процесів CI, а не від обов’язкових специфікацій.

Система в кінцевому підсумку

При перегляді monorepo саду видно, що конфігурація працює належним чином. Вкладені файли AGENTS.md містять спільні структурні правила. Один-рядковий файл CLAUDE.md відповідає за імпорт елементів, специфічних для Claude. Файл SKILL.md з механізмом міграції баз даних чекає за своїм „блокувальним“ описом на завдання з бази даних, щоб його активувати, а GitHub Action об’єднує все це так, щоб жоден розробник не писав одне й те саме правило двічі.