Авторское примечание: Подробно разбираем различия в назначении конфигурационных папок .agents и .claude при разработке AI Agent, правила хранения Skills, сравниваем структуру каталогов, а также сценарии использования AGENTS.md и CLAUDE.md.
Разработка AI Agent набирает обороты, и в корневых каталогах проектов начинают появляться различные конфигурационные папки — .agents, .claude, .cursor… Среди них .agents и .claude могут использоваться для размещения Skills, но их назначение, концепция дизайна и область применения совершенно разные. Неправильный выбор места хранения может привести к тому, что Skills не будут работать, или, в худшем случае, к конфликтам конфигурации при командной работе. В этой статье мы подробно разберем ключевые различия между ними, исходя из их базовой архитектуры, и предложим лучшие практики.
Ключевая ценность: Прочитав эту статью, вы точно определите, следует ли размещать ваши Skills в .agents или .claude, а также научитесь эффективно управлять конфигурацией Agent в команде, использующей несколько инструментов.
Ключевые моменты папок .agents и .claude
Сначала ответим на главный вопрос: эти две папки не конкурируют, а представляют собой разные уровни конфигурации.
| Аспект сравнения | Папка .claude/ |
Папка .agents/ |
|---|---|---|
| Принадлежность | Anthropic (эксклюзивно для Claude Code) | Фонд Agentic AI / Фонд Linux |
| Назначение | Каталог конфигурации проекта для Claude Code | Стандарт конфигурации агентов, не зависящий от инструментов |
| Формат Skills | SKILL.md (Markdown + YAML front matter) |
SKILL.yaml (чистый YAML) |
| Зрелость | Готов к производству, официально поддерживается Claude Code | Стандарт в разработке (Work In Progress) |
| Поддержка кросс-инструментов | Только Claude Code | Цель — поддержка всех инструментов AI Agent |
Различия в философии дизайна папок .agents и .claude
Фундаментальное различие между этими папками заключается в философии дизайна:
Папка .claude/ следует подходу "эксклюзивной глубокой интеграции". Она создана специально для Claude Code и предоставляет полный набор возможностей, таких как Skills, Subagents, Hooks, Permissions, глубоко интегрированных с инструментарием Claude Code. Преимущество — полнота функций и готовность к использованию "из коробки"; недостаток — привязка к экосистеме Claude Code.
Папка .agents/ следует подходу "общего стандарта для кросс-инструментального использования". Она пытается определить спецификацию конфигурации, которую могут читать все инструменты AI Agent, подобно тому, как .editorconfig работает для редакторов. Преимущество — одна конфигурация для нескольких инструментов; недостаток — стандарт все еще развивается, и степень поддержки разными инструментами варьируется.
Обе папки могут сосуществовать в одном проекте: эксклюзивные глубокие конфигурации для Claude Code помещаются в .claude/, а общие конфигурации, которые можно использовать с разными инструментами, — в .agents/.
Полная структура каталога .claude
Сначала рассмотрим нативный каталог .claude/ для Claude Code — это наиболее зрелая реализация на данный момент.
Подробное описание структуры каталога .claude
.claude/
├── CLAUDE.md # Инструкции для проекта (заменяет CLAUDE.md в корневом каталоге)
├── settings.json # Настройки проекта (коммитятся в git, общие для команды)
├── settings.local.json # Локальные настройки (в gitignore, индивидуальные настройки)
├── skills/ # Каталог навыков (Skills)
│ └── <имя-навыка>/
│ ├── SKILL.md # Файл определения навыка (обязательный)
│ ├── scripts/ # Вспомогательные скрипты
│ ├── references/ # Справочные материалы
│ └── templates/ # Файлы шаблонов
├── agents/ # Определения под-агентов
│ └── <имя-агента>.md # Файл определения под-агента
├── commands/ # Старые команды слэша (объединены в skills)
│ └── <имя-команды>.md
└── agent-memory/ # Персистентная память под-агентов
└── <имя-агента>/
└── MEMORY.md
Также существует пользовательский каталог ~/.claude/, где личные навыки могут быть доступны во всех проектах:
~/.claude/
├── CLAUDE.md # Инструкции пользователя (кросс-проектные)
├── settings.json # Настройки пользователя
├── skills/ # Личные навыки (доступны во всех проектах)
├── agents/ # Личные под-агенты
└── projects/ # История сеансов и данные
Формат SKILL.md для навыков в папке .claude
Навыки Claude Code определяются с помощью файла Markdown с YAML front matter:
---
name: my-skill
description: Описание навыка, помогающее Claude определить, когда его активировать
user-invocable: true # Пользователь может вызвать через /my-skill
allowed-tools: Read, Grep # Ограничение доступных инструментов
context: fork # Запуск в отдельном под-агенте
model: sonnet # Модель для переопределения
---
Вы — профессиональный помощник по ревью кода...
(Инструкции навыка в формате Markdown)
Ключевые поля:
- Skill с
user-invocable: trueрегистрируется как/slash-command. context: forkозначает запуск в отдельном контексте, не загрязняющем основной диалог.allowed-toolsможет ограничивать набор инструментов, которые может использовать Skill.- Поддерживается подстановка параметров
$ARGUMENTS,$0,$1.
🎯 Рекомендации по разработке: Система Skills Claude Code следует открытому стандарту Agent Skills (agentskills.io), синтаксис которого универсален для Claude Code, Claude API и VS Code Copilot.
Если вы разрабатываете AI-приложения с помощью Claude Code, рекомендуется получить API-ключ через APIYI apiyi.com для унифицированного управления вызовами нескольких моделей.
Полная структура каталога .agents
Спецификация каталога .agents (AGENTS-1 Spec) поддерживается фондом Agentic AI под эгидой Linux Foundation. Её цель — определить стандарт универсальной конфигурации, понятный всем инструментам для написания кода с использованием ИИ.
Детальное описание структуры каталога .agents
.agents/
├── manifest.yaml # Обязательно: реестр конфигураций, объявляет все доступные конфигурации
├── prompts/ # Обязательно: инструкции (промпты)
│ ├── base.md # Общие инструкции для Agent
│ ├── project.md # Инструкции для конкретного проекта
│ └── snippets/ # Фрагменты инструкций для модульности
├── modes/ # Обязательно: режимы поведения (аналогично .claude/agents/)
│ ├── plan.md # Режим планирования
│ ├── code.md # Режим кодирования
│ └── review.md # Режим ревью
├── policies/ # Обязательно: политики безопасности и ограничения возможностей
├── skills/ # Обязательно: определения навыков (согласно спецификации Agent Skills)
│ └── <name>/
│ └── SKILL.yaml # Определение навыка в формате YAML
├── scopes/ # Обязательно: переопределение конфигурации на уровне путей (поддержка Monorepo)
├── profiles/ # Обязательно: именованные наложения конфигураций (dev/ci/staging)
├── schemas/ # Обязательно: проверка JSON Schema
└── state/ # Локальное состояние (не добавляется в git)
├── .gitignore
└── state.yaml
В отличие от .claude/, где навыки используют SKILL.md (Markdown), в .agents/ навыки используют формат SKILL.yaml (чистый YAML).
Уникальные особенности дизайна каталога .agents
Спецификация .agents включает несколько концепций, отсутствующих в .claude/:
- Scopes (Области видимости): Позволяют определять разные конфигурации для различных под-каталогов в Monorepo. Наиболее конкретный путь имеет наивысший приоритет.
- Profiles (Профили): Поддерживают именованные наложения конфигураций, такие как
dev,ci,prod, аналогично переменным окружения. - Policies (Политики): Отдельный каталог для ограничений безопасности. Правила запрета (deny) всегда имеют приоритет над правилами разрешения (allow).
- Determinism (Детерминизм): Одинаковый ввод должен приводить к одинаковому выводу, без зависимости от внешнего состояния.
Сравнение правил хранения навыков в каталогах .agents и .claude
Это самый актуальный вопрос для разработчиков: куда же мне положить мои навыки?
Сравнение навыков в .agents и .claude
| Аспект сравнения | .claude/skills/ |
.agents/skills/ |
|---|---|---|
| Файл определения | SKILL.md (Markdown + YAML frontmatter) |
SKILL.yaml (чистый YAML) |
| Поддержка Claude Code | Нативная поддержка, автоматическое обнаружение | Требуется ручная настройка или ожидание официальной поддержки |
| Команды через слэш | user-invocable: true автоматически регистрирует /command |
Зависит от реализации конкретного инструмента |
| Запуск под-агентов | context: fork запускает в отдельном контексте |
Конфигурируется через modes/ |
| Переопределение модели | model: sonnet указывает напрямую |
Конфигурируется через profiles/ |
| Ограничения инструментов | allowed-tools: Read, Grep |
Конфигурируется через policies/ |
| Вспомогательные файлы | Подкаталоги scripts/, references/, templates/ |
Зависит от реализации |
| Передача аргументов | Замена переменных $ARGUMENTS, $0, $1 |
Спецификация явно не определяет |
Как .agents и .claude могут сосуществовать
В реальных проектах оба каталога могут использоваться совместно, дополняя друг друга. На примере нашего проекта:
.claude/skills/ для навыков, тесно интегрированных с Claude Code:
apiyi-article-generator— генерация статей, глубокая интеграция с шаблонами и спецификациями проекта.apiyi-svg-generator— генерация SVG-иллюстраций, зависит от шаблонов SVG проекта.apiyi-content-reviewer— проверка контента, использует стандарты качества проекта.
.agents/skills/ для универсальных переносимых навыков:
markdown-proxy— получение Markdown по URL с помощью Python-скрипта.nano-banana-pro-image-gen— генерация изображений, вызов внешнего API.
Принцип разделения прост: то, что глубоко интегрировано с Claude Code, помещаем в .claude/, а то, что может быть использовано с другими ИИ-инструментами, — в .agents/.
🎯 Рекомендация по выбору: Если ваша команда использует только Claude Code, достаточно поместить всё в
.claude/skills/для максимальной функциональности.
Если же в команде используются разные ИИ-инструменты (Cursor, Windsurf, Codex и т.д.), то размещение универсальных навыков в.agents/skills/упростит совместную работу.
Для вызовов API в разработке AI-агентов рекомендуется унифицированное управление через APIYI apiyi.com, где один API-ключ покрывает множество моделей.
Сравнение файлов инструкций для .agents и .claude
Помимо папки Skills, обе системы имеют свои собственные файлы инструкций для проектов.
Различия между CLAUDE.md и AGENTS.md
| Параметр сравнения | CLAUDE.md | AGENTS.md |
|---|---|---|
| Поддерживаемые инструменты | Claude Code | Claude Code, OpenAI Codex, Google Jules, Cursor, GitHub Copilot и др. |
| Уровень вложенности файлов | Пользовательский (~/.claude/) → Проектный (./) → Подкаталоги |
Проектный (./) → Подкаталоги |
| Локальное переопределение | CLAUDE.local.md (добавляется в gitignore) |
Нет |
| Официальная стандартизация | Нет (документация продуктов Anthropic) | Есть (Фонд Agentic AI под эгидой Linux Foundation) |
| Размер экосистемы | Растет (используется в Next.js, LangChain, Deno и т.д.) | Масштабный (n8n 178K звезд, llama.cpp 97K звезд, Bun 82K звезд) |
| Инициализация | Команда /init в Claude Code |
Ручное создание |
Практический совет: Оба файла могут сосуществовать. CLAUDE.md можно использовать для инструкций, специфичных для Claude Code (например, конфигурация хуков, правила разрешений), а AGENTS.md — для общих контекстных данных проекта, применимых ко всем AI-инструментам (например, команды сборки, стандарты кодирования, описание архитектуры).
Обзор экосистемы файлов для .agents и .claude
| Файл/Каталог | Система | Назначение | Отправляется в git |
|---|---|---|---|
CLAUDE.md |
.claude | Инструкции проекта для Claude Code | Да |
CLAUDE.local.md |
.claude | Локальные пользовательские инструкции | Нет |
.claude/settings.json |
.claude | Разрешения, хуки, MCP | Да |
.claude/settings.local.json |
.claude | Локальные пользовательские настройки | Нет |
AGENTS.md |
.agents | Общие инструкции проекта для агентов | Да |
.agents/manifest.yaml |
.agents | Реестр конфигураций | Да |
.agents/state/state.yaml |
.agents | Локальное состояние выполнения | Нет |
.cursorrules |
Cursor | Правила, специфичные для Cursor | Да |
Примечание: Исследование ETH Zurich 2026 года показало, что сгенерированные AI файлы контекста иногда могут снижать производительность агентов. Рекомендуется писать их вручную и ограничиваться неявной информацией, которую нельзя вывести из кода (пользовательские цепочки инструментов, нестандартные шаблоны и т. д.).
Частые вопросы
В1: Может ли Claude Code читать Skills из директории .agents/skills/?
В настоящее время Claude Code нативно автоматически обнаруживает и загружает Skills только из директории .claude/skills/. Содержимое из .agents/skills/ не распознается автоматически. Сообщество уже подало запрос в GitHub (Issue #31005) с просьбой добавить поддержку директории .agents/ в Claude Code. Если ваши Skills должны работать в Claude Code, их необходимо разместить в .claude/skills/.
В2: Является ли спецификация директории .agents/ зрелой? Можно ли ее использовать для продакшн-проектов?
Спецификация директории .agents/ (AGENTS-1 Spec) все еще находится в разработке (Work In Progress). Однако файл AGENTS.md уже широко используется — его применяют такие крупные open-source проекты, как n8n (178 тыс. звезд), llama.cpp (97 тыс. звезд), Bun (82 тыс. звезд) и другие. Рекомендуется пока использовать AGENTS.md как общий файл инструкций, а полную структуру директории .agents/ и другие спецификации использовать после их стабилизации.
В3: Как управлять конфигурацией, если члены команды используют разные AI-инструменты (Claude Code + Cursor)?
Рекомендуется многоуровневое управление:
AGENTS.mdсодержит общую информацию по проекту (команды сборки, правила кодирования), которую читают все инструменты.CLAUDE.mdсодержит инструкции, специфичные для Claude Code..cursorrulesсодержит правила, специфичные для Cursor.
Общие Skills размещайте в.agents/skills/, а специфичные для инструментов — в их собственных директориях. Используйте сервис-прокси API APIYI apiyi.com для унифицированного управления AI API-вызовами команды, чтобы одна платформа охватывала все модели.
В4: В чем разница в формате между SKILL.md и SKILL.yaml?
SKILL.md — это формат для Claude Code, использующий файл Markdown с YAML-метаданными в заголовке (frontmatter). Инструкции пишутся в Markdown, что делает их более читаемыми для человека. SKILL.yaml — это формат спецификации .agents/, где все определяется в структурированном виде с помощью YAML, что упрощает машинную обработку. Основная информация (название, описание, условия срабатывания) в обоих форматах одинакова, различается только сам формат.
Заключение
Ключевые отличия директорий .agents и .claude:
- Разное назначение:
.claude/— это эксклюзивная директория конфигурации проекта для Claude Code, глубоко интегрирующая все его функции..agents/— это кросс-инструментальный универсальный стандарт под эгидой Linux Foundation. - Разный формат Skills:
.claude/skills/используетSKILL.md(Markdown), который Claude Code загружает нативно..agents/skills/используетSKILL.yaml(YAML), разработанный как независимый от инструментов. - Могут сосуществовать и дополнять друг друга: Глубокие функции Claude Code (Hooks, под-агенты, разрешения) размещайте в
.claude/. Универсальные переносимые навыки — в.agents/. Базовые инструкции проекта используйте вAGENTS.md.
Ключевой фактор при выборе директории — это состав инструментов вашей команды и потребность в переносимости навыков.
Рекомендуем использовать APIYI apiyi.com для унифицированного управления вызовами моделей при разработке AI-агентов. Платформа предоставляет бесплатные лимиты и единый интерфейс для множества моделей, поддерживая интеграцию основных моделей, таких как Claude, GPT, Gemini, в одном месте.
📚 Справочные материалы
-
Официальная документация Claude Code Skills: Полное описание, формат и способы использования Skills.
- Ссылка:
code.claude.com/docs/en/skills - Описание: Изучите формат SKILL.md, правила триггеров и передачу параметров.
- Ссылка:
-
Документация Claude Code Subagents: Описание и способы настройки Subagents.
- Ссылка:
code.claude.com/docs/en/sub-agents - Описание: Изучите формат файлов в директории
.claude/agents/.
- Ссылка:
-
Официальный сайт AGENTS.md: Стандарт файла инструкций для кросс-инструментальных агентов.
- Ссылка:
agents.md - Описание: Изучите правила написания AGENTS.md и список поддерживаемых инструментов.
- Ссылка:
-
Спецификация папки
.agents/: Полное определение структуры каталогов AGENTS-1 Spec.- Ссылка:
github.com/agentsfolder/spec - Описание: Изучите дизайн manifest.yaml, modes, policies, scopes.
- Ссылка:
-
Центр документации APIYI: Единое управление вызовами API в разработке AI-агентов.
- Ссылка:
docs.apiyi.com - Описание: Поддерживает унифицированный интерфейс для нескольких моделей, подходит для сценариев разработки агентов.
- Ссылка:
Автор: Техническая команда APIYI
Техническое общение: Приглашаем к обсуждению в комментариях, больше материалов можно найти в центре документации APIYI docs.apiyi.com.
