Дзе месца кожнай інструкцыі: 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. Зараз падтрымка AGENTS.md ўжо ўбудована у болей чым 60 000 рэпазітарыяў і адносна два дзесяткі інструментоў, таму жадны з стандатаў не знікне.

У рэзультаце команды цяпер пішуць адныя і тыя ж інструкцыі ў трох месцах: 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 для пераканання ў можлівасці зворачнага перадзеяўлення і прымітку на маркдауне пра рэжымы блакавання ў Postgres. Нічога з гэтага не павінна быць у AGENTS.md. Агент, які рэдагуе файл CSS у пакеце UI, не мае права отрымаць інфармацыю пра рэжымы блакавання ў сваёй сістэмнай прампцы. Механізм опісу гарантуе, што скіл ладзіцца толькі тады, калі змienяецца файл міграцыі.

Правілле маршрутацыі

Калі працэс завантажэння модэляў завершыўся, адбыцце новы фрагмент кантэксту стае механічным прыемам:

• Кантэкст праекта, які ўзаемна выкарыстоўваецца і не залежыць ад інструментаў і які неабходны ў кожны момент, кладзіцца ў AGENTS.md.
• Інструкцыі, прызначаныя толькі для Claude Code, кладзіцца ў CLAUDE.md, жадаўна як короткі файл, які імпортуе AGENTS.md.
• Рабочыя працэсы, скрыпты і апісанні сферы, якія неабходны толькі для дзеякіх задач, кладзіцца ў спецыяльны модуль, пасля апісання, якое паведамляе, калі яго адкрываць.

Контроль бюджэту «заўжды ўвімкнутага» рэжыму

Разлік межаў між умовным і «заўжды ўвімкнутым» завантажэнням адносна безпасэродзе вяліць да карыстнасці агента.

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

Такая эфекіўнасць падтрымваецца толькі тады, калі кантэкст застаецца рэлевантным. Кожны токен, які ўводзіцца ў сістэмны запрос, прывлекае увагу мадэлі. Падазроўцам, калі команда вставляе 500-словыя інструкціі па міграціі баз дадзеных у файл AGENTS.md, агенту даводзіцца чытаць іх падчас вылечвання бага ў фронтэндзе, пры чым ён аддае увагу рэжымам блакавання Postgres, калі яго ўвага патрэбна для розгляду React hooks.

Умовная загрузка захоўвае досягнутыя рэзультаты. Пераклад сітуатывных рабочых практык у файл 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 з’еднае ўсё разам, так што жадны распрацоўшчык не пішае тое самае правіла два разы.