Куда относится каждая инструкция: 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 — универсальный набор инструкций для ИИ-ассистентов по программированию. Команды по созданию кода, правила тестирования и архитектура проектов могли храниться в одном месте; идея заключалась в том, что как 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 нужна собственная копия правил сборки. Вместо этого правильная минимальная форма импортирует общепринятый стандарт в контекст 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 и стандартные инструменты командной строки не поддерживают структуру .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 объединяет всё воедино, чтобы ни один разработчик не писал одно и то же правило дважды.