Agent Skills: настройка .claude/skills и .agents/skills

Если команда работает с одним репозиторием через Claude Code, Codex, Cursor и Gemini CLI, храните общие навыки Agent Skills в .agents/skills/<skill-name>/. Для Claude Code создайте в .claude/skills/ относительную символическую ссылку на каталог каждого навыка. Прежде чем внедрять такую структуру в команде, проверьте в каждом клиенте, что навык появился в списке и его можно вызвать.

Навык (skill) — это набор инструкций для повторяемой задачи. Такая схема позволяет редактировать одну копию инструкций и учитывать разные правила поиска файлов в клиентах. Если команда пользуется только Claude Code, можно оставить существующую структуру .claude/skills/: перенос имеет смысл, когда те же навыки нужны другому клиенту.

Стало ли имя каталога обязательным после передачи в AAIF?

Agent Skills стал проектом AAIF, но путь к навыкам по-прежнему определяет каждый клиент. Anthropic объявила о передаче Agent Skills 22 октября 2026 года, а AAIF подтвердила принятие проекта.

В руководстве для разработчиков клиентов прямо сказано: спецификация не определяет, где должны находиться каталоги навыков. Для совместимости авторы рекомендуют поддерживать .agents/skills/ наряду с собственным каталогом клиента. Из этой рекомендации не следует, что все существующие клиенты уже ищут навыки по этому пути.

Переносимый элемент — каталог с файлом SKILL.md, блоком метаданных YAML в его начале и инструкциями в Markdown. Спецификация формата требует поля name и description; рядом можно хранить дополнительные ресурсы. Способ вызова, среда выполнения скриптов и разрешения зависят от клиента. В частности, allowed-tools остаётся экспериментальным полем с разной поддержкой, поэтому использовать его как единую для всех клиентов политику разрешений нельзя.

Где Claude Code, Codex, Cursor и Gemini CLI ищут навыки?

Используйте локальные каталоги, перечисленные в официальной документации. Пути и способы управления ниже проверены по состоянию на 2026-10-26; для структуры из этой инструкции добавьте к каждому пути <skill-name>/SKILL.md.

Инструмент	Каталоги в репозитории	Каталоги пользователя	Что выбрать для общего репозитория
Claude Code	.claude/skills/	~/.claude/skills/	Создайте в .claude/skills/ отдельную ссылку на каждый общий навык.
Codex CLI и расширение для IDE	.agents/skills/	~/.agents/skills/	Используйте общий каталог напрямую.
Cursor Agent	.agents/skills/, .cursor/skills/; для совместимости также .claude/skills/ и .codex/skills/	Те же четыре каталога внутри ~/	Используйте .agents/skills/; дополнительная ссылка для Cursor не нужна.
Gemini CLI	.agents/skills/ и .gemini/skills/	~/.agents/skills/ и ~/.gemini/skills/	Используйте .agents/skills/ напрямую. В пределах одной области действия этот путь имеет приоритет над .gemini/skills/.

В текущем руководстве Claude Code поиск непосредственно в .agents/skills/ не указан, а запрос функции #31005 остаётся открытым. В руководствах Codex и Gemini, наоборот, среди каталогов поиска нет .claude/skills/. Опирайтесь на документированные пути: эти два каталога нельзя считать взаимозаменяемыми для всех клиентов.

Таблица описывает локальный поиск. Навык из домашней папки на вашем ноутбуке не появится автоматически на удалённом исполнителе или в новом контейнере — файлы нужно передать и в эту среду.

Создайте общий навык и ссылку для Claude Code

Разместите весь навык в .agents/skills/, а ссылку создайте на его каталог целиком, чтобы через неё были доступны и будущие скрипты, и справочные материалы. Отдельная ссылка для каждого навыка позволяет сохранить рядом навыки, предназначенные только для Claude Code.

Для начала нужны Git и установленный клиент, в котором вы уже прошли авторизацию и можете работать с репозиторием. Настройка каталогов не требует нового ключа API; обычные условия доступа к клиенту и разрешения на использование инструментов сохраняются.

Напишите переносимый навык

Создайте в редакторе файл .agents/skills/review-staged/SKILL.md и, если нужно, родительские каталоги. Если такой навык уже существует, выберите другое имя и согласованно замените его в пути, метаданных и командах.

Вставьте полный текст файла:

---
name: review-staged
description: "Review staged Git changes for correctness before a commit. Use when the user asks to review the Git index or staged changes."
---

Begin the answer with `Skill loaded: review-staged`.

1. Locate the repository root with `git rev-parse --show-toplevel`.
   Run all following commands from that directory.
2. Run `git diff --cached --name-only`. If it prints no paths,
   report `No staged changes.` and stop.
3. Run `git diff --cached --check` and `git diff --cached --`.
   Treat a nonzero `--check` exit as evidence to report, not a reason
   to skip reading the diff.
4. Read relevant files as needed. Report concrete correctness issues
   with file and line references. Separate confirmed issues from questions.
5. Finish with suggested verification commands. Do not claim they ran.

Do not edit files, stage changes, or create a commit.

Этот навык проверяет индекс Git — изменения, подготовленные для следующего коммита. В справочнике git diff параметр --cached описывает такое сравнение, а --check выявляет проблемы с пробельными символами и маркеры конфликтов. В примере агенту предлагается выполнить обычные команды; специальные механизмы подстановки команд в запрос, доступные лишь в отдельных клиентах, не используются.

Добавьте ссылку через Bash в macOS или Linux

Создайте для навыка относительную символическую ссылку, или симлинк. Claude Code прямо документирует поддержку ссылок на каталоги навыков.

Выполните следующий блок в Bash из любого каталога внутри нужного Git-репозитория:

(
  set -eu
  cd "$(git rev-parse --show-toplevel)"
  test -f .agents/skills/review-staged/SKILL.md
  mkdir -p .claude/skills

  skill_link=.claude/skills/review-staged
  if [ -e "$skill_link" ] || [ -L "$skill_link" ]; then
    printf '%s\n' "Already exists: $skill_link" >&2
    exit 1
  fi

  ln -s ../../.agents/skills/review-staged "$skill_link"
  test -L "$skill_link"
  test -f "$skill_link/SKILL.md"
  readlink "$skill_link"
)

Ожидаемый вывод — ../../.agents/skills/review-staged, код завершения — 0. Обе части .. отсчитываются от родительского каталога ссылки, .claude/skills/, и поднимают путь до корня репозитория.

Если путь для ссылки уже занят, сначала выясните, что там находится. Правильную ссылку оставьте; содержимое обычного каталога навыка сначала сравните с основной копией и согласуйте изменения. Команды не заменят ни существующий каталог, ни ссылку с отсутствующей целью.

Создайте такую же ссылку в Windows

Для относительной ссылки на каталог используйте PowerShell 7.1 или новее. Это требование к версии указано в документации Microsoft по New-Item. Для создания символических ссылок в Windows обычно нужны повышенные права либо включённый режим разработчика в поддерживаемой версии Windows.

Сохраните основной файл SKILL.md и выполните из корня репозитория:

New-Item -ItemType Directory -Force -Path '.claude/skills' -ErrorAction Stop | Out-Null
Push-Location '.claude/skills' -ErrorAction Stop
try {
    New-Item -ItemType SymbolicLink -Path 'review-staged' `
        -Target '../../.agents/skills/review-staged' -ErrorAction Stop | Out-Null
    Get-Item 'review-staged' | Select-Object LinkType, Target
    Test-Path 'review-staged/SKILL.md' -PathType Leaf
}
finally {
    Pop-Location
}

В результате LinkType должен иметь значение SymbolicLink, а проверка файла должна вернуть True. Если создание ссылки завершилось ошибкой прав доступа, используйте разрешённый в вашей организации способ включения режима разработчика или запуска с повышенными правами.

Не рассчитывайте, что обычный Git Bash в Windows ведёт себя как Linux: согласно документации Git for Windows, по умолчанию ln -s создаёт копии. Воспользуйтесь инструкцией для PowerShell и проверьте тип созданного объекта.

После клонирования возможна другая проблема. При core.symlinks=false Git создаёт в рабочем дереве обычный файл с текстом целевого пути ссылки. Проверьте это в PowerShell:

git config --show-origin --get core.symlinks
Get-Item '.claude/skills/review-staged' |
    Select-Object LinkType, Target, PSIsContainer
Test-Path '.claude/skills/review-staged/SKILL.md' -PathType Leaf

Если вместо ссылки получился текстовый файл, прочитайте его содержимое, прежде чем заменять именно этот файл настоящей ссылкой. Перед следующим клонированием настройте создание символических ссылок поддерживаемым способом. Само изменение настройки Git не превращает уже созданный текстовый файл в ссылку на каталог.

Проверьте обнаружение, вызов и результат

Сначала найдите навык в списке клиента, затем вызовите его явно. Наличие файла на диске ещё не означает, что клиент его обнаружил, а запись в списке не доказывает, что инструкции навыка были загружены.

Откройте репозиторий в каждом клиенте или запустите клиент из его корня. Следующие действия выполняются внутри клиента, а не в командной строке Bash или PowerShell:

Клиент	Как проверить обнаружение	Как вызвать пример
Claude Code	Выполните /skills; при необходимости используйте /reload-skills из справочника команд.	Отправьте /review-staged.
Codex CLI или расширение для IDE	Откройте /skills или меню выбора навыка через $.	Отправьте $review-staged Review my staged changes.
Cursor Agent	Откройте Customize → Skills, затем найдите навык в меню /.	Выберите review-staged и попросите проверить изменения, подготовленные к коммиту.
Gemini CLI	Выполните /skills list; после добавления файлов используйте /skills reload.	Отправьте запрос: Use the review-staged skill to review my staged changes.

В Gemini документированный процесс активации включает вызов activate_skill и интерактивный запрос согласия. Когда появится запрос, подтвердите доступ к каталогу нужного навыка. Команды просмотра списка и повторного сканирования описаны в руководстве по управлению навыками.

Ожидаемый ответ начинается с Skill loaded: review-staged. Далее должны идти найденные проблемы и предлагаемые проверки либо No staged changes., если индекс пуст. Помимо этой строки, проверьте журнал активации или чтения файла и выполненные команды Git. Так можно убедиться, что инструкции загрузились; правильность каждого замечания при проверке кода нужно оценивать отдельно.

При такой структуре Cursor видит оба пути. В заметках к выпуску IDE 3.25 от 14 октября 2026 года указано, что навыки с одинаковым именем могут отображаться отдельными строками меню. Проверьте наличие дублей в установленной версии: нельзя рассчитывать, что все клиенты одинаково распознают несколько ссылок на один навык.

Организуйте навыки в монорепозитории и CI

Храните общие навыки в корне репозитория и при первой проверке запускайте оттуда все клиенты. Если процедура относится к отдельному пакету, укажите его в описании и инструкциях навыка, чтобы обозначить область применения, не полагаясь на одинаковые правила поиска во вложенных каталогах. Пример выше намеренно проверяет весь индекс Git.

Распределите файлы так, чтобы у каждого пути было понятное назначение:

Путь	Назначение
.agents/skills/review-staged/SKILL.md	Основная редактируемая копия общих инструкций.
.agents/skills/review-staged/references/	Необязательные справочные материалы, поставляемые вместе с навыком.
.claude/skills/review-staged	Относительная ссылка на весь каталог общего навыка.
packages/mobile/	Код приложения, указанного в задаче.

Правила области действия различаются. Claude Code и Codex ищут свои каталоги навыков, поднимаясь от стартового каталога до корня репозитория. Cursor также поддерживает навыки во вложенных каталогах проекта: они действуют для файлов внутри соответствующего каталога. Руководство Gemini описывает навыки рабочего пространства относительно текущего каталога. Запуск всех четырёх клиентов из корня позволяет не зависеть от этих различий.

Размещайте каталог каждого общего навыка непосредственно внутри каталога навыков, без промежуточных папок-категорий. В начальном руководстве Gemini поиск ограничен этим уровнем вложенности. Рекурсивный поиск в Cursor не делает дополнительный уровень совместимым с остальными клиентами.

Если рабочая область открыта только для отдельного пакета, повторите в ней проверку обнаружения и при необходимости установите или подключите ссылкой общий навык. Не переносите целевой путь с ../../ из корневой ссылки в более глубокий каталог без пересчёта.

Добавьте основной каталог и относительную символическую ссылку в коммит, если среды, в которых команда получает рабочую копию, поддерживают такие ссылки. Цель ссылки должна оставаться внутри репозитория: тогда свежему клону не понадобится доступ к домашней папке конкретного разработчика.

После получения рабочей копии в Linux CI выполните эту проверку в Bash:

test -f .agents/skills/review-staged/SKILL.md &&
test -L .claude/skills/review-staged &&
test -f .claude/skills/review-staged/SKILL.md

Код завершения 0 означает, что нужные файлы и ссылка доступны. Проверки обнаружения и вызова, описанные выше, всё равно нужно выполнить в клиенте именно в той среде, где он будет работать.

Что проверить, если навык не загружается?

Исправляйте тот этап, на котором возникла проблема. Ниже перечислены разные ветки диагностики; менять все настройки подряд не нужно.

• Навыка нет в списке. Проверьте корень рабочей области, написание каталогов и точное имя SKILL.md. Прочитайте файл по тому пути, который сканирует клиент. Если основной путь доступен, а путь для Claude — нет, исправьте ссылку или способ получения рабочей копии.
• Файл найден, но метаданные не приняты. Проверьте разделители YAML, непустое поле description длиной не более 1024 символов и совпадение имени каталога с name. Допустимая длина имени — 1–64 символа; используйте строчные буквы, цифры и дефисы. Дефис не должен стоять в начале или конце, а несколько дефисов — идти подряд.
• Новый файл пока не появился в списке. Повторно загрузите навыки Claude или Gemini указанными выше командами. Codex документирует автоматическое обнаружение изменений; если оно не сработало, перезапустите клиент. Перезапустите Cursor, если нужно повторить сканирование при старте.
• Gemini не видит навык рабочего пространства. Проверьте доверие к папке через /permissions trust. В текущем справочнике настроек для skills.enabled указано значение true по умолчанию, но политика администратора может запрещать навыки. Проверьте, не отключены ли они настройкой или решением о доверии, и измените соответствующий параметр через предусмотренные для него средства.
• Запускается другой навык. Найдите личные и проектные копии с тем же именем. В Claude личные навыки имеют приоритет над проектными; Codex может показать обе записи; Gemini отдаёт приоритет навыкам рабочего пространства перед пользовательскими. Для разных процедур лучше выбирать разные имена.
• Навык есть в списке, но не выбирается автоматически. Сначала вызовите его явно. Если это работает, уточните в описании, для какой задачи он нужен. Более точное описание помогает выбору; перенос уже обнаруженного файла проблему не решает.
• Инструкции загружены, но команды завершаются ошибкой. Проверьте наличие Git, рабочий каталог и текст ошибки разрешений. Совместимая структура каталогов не устанавливает среду выполнения и не даёт права запускать команды.