Навыки для ИИ-агентов из .agents директории

Разбираем репозиторий mattpocock/skills: готовые навыки для ИИ-агентов, как они устроены и зачем инженерам хранить инструкции в .agents.

Что такое skills в контексте ИИ-агентов

Навык (skill) — это не просто текстовый промпт, который кидают в модель. Это структурированный набор инструкций, примеров и метаданных, который агент может подгрузить и применить к конкретной задаче. Если промпт — это инструкция «на лету», то skill — уже готовый модуль с версионированием, входными и выходными данными, который можно переиспользовать между разными агентами и проектами.

Представьте, что вы настраиваете новый сервер. Можно каждый раз писать в чат с ИИ: «помоги настроить Nginx, проксируй на 8080, добавь SSL». А можно один раз описать процедуру в виде навыка, положить в репозиторий и подключать его к любому агенту, который будет разворачивать инфраструктуру. Второе даёт предсказуемость — конфигурация не зависит от настроения модели и формулировки вопроса.

Откуда взялась идея .agents

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

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

Пример структуры может выглядеть так:

.my-project/
├── .agents/
│   ├── code-review.md
│   ├── commit-messages.md
│   └── testing.md
├── src/
├── tests/
└── README.md

Файл code-review.md может содержать чек-лист для проверки кода, а commit-messages.md — правила оформления коммитов в стиле Conventional Commits. Агент, перед тем как предложить изменения, сверяется с этими навыками.

Репозиторий mattpocock/skills развивает эту мысль дальше: вместо разрозненных markdown-файлов предлагается единый формат навыков, который можно установить, обновить и распространять как обычный пакет. Подробнее о концепции можно посмотреть в исходном репозитории mattpocock/skills.

Чем отличаются навыки от промптов

Промпт — это текст, который вы вводите в чат с моделью. Он зависит от того, как вы сформулировали вопрос, и часто требует уточнений. Навык — это формализованный артефакт с чёткой структурой, который агент подгружает автоматически.

Различие проще показать на примере. Допустим, нужно, чтобы агент проверял коммиты перед пушем.

Промпт в чате:

Проверь мой коммит на соответствие правилам проекта. 
Напиши, что исправить.

Результат будет зависеть от модели, от того, какой контекст она успела подхватить, и от того, насколько точно вы опишете правила.

Навык в .agents/commit-review.md:

markdown
# Навык: review-commit

## Описание
Проверяет коммит на соответствие стандартам оформления и качеству кода.

## Входные данные
- diff коммита
- список изменённых файлов
- правила из .agents/commit-messages.md

## Шаги выполнения
1. Проверить сообщение коммита на соответствие Conventional Commits.
2. Убедиться, что в коммите нет отладочного кода (console.log, print, debugger).
3. Проверить, что для изменённой логики есть тесты.
4. Выдать краткий отчёт: «Одобрено» или «Требуются правки» с перечислением замечаний.

## Пример вывода
Одобрено. Сообщение соответствует формату feat(scope): описание. Тесты покрывают изменённый код.

Агент вызывает этот навык автоматически перед каждым коммитом. Не нужно напоминать ему правила каждый раз — они зафиксированы в репозитории.

Ещё одно отличие — версионирование. Промпт меняется неявно: вы поправили формулировку в чате, и всё. Навык лежит в Git, его можно закоммитить, откатить, просмотреть diff между версиями. Это даёт ту же предсказуемость, что и инфраструктура как код.

Если говорить кратко: промпт — это разговор, навык — это инструкция по эксплуатации. Первый подходит для разовых задач, второй — для систем, где важно, чтобы агент вёл себя одинаково независимо от того, кто и когда с ним работает.

Структура репозитория mattpocock/skills

Как организованы файлы навыков

Репозиторий mattpocock/skills построен вокруг одной идеи: инструкции для ИИ-агента должны лежать рядом с кодом, а не размазаны по истории чата. В корне репозитория находится директория .agents, внутри неё — отдельная папка на каждый навык.

Во-первых, каждый навык — это самодостаточный блок. В папке навыка обычно лежат три файла: описание того, что делает навык и когда его применять, системный промпт для агента и файл с примерами использования. Такой подход даёт предсказуемость: агент точно знает, в каком контексте он работает, и не начинает выдумывать команды, которых нет в репозитории.

С практической точки зрения, структура выглядит так:

.agents/
  skill-name/
    README.md        # что делает навык и когда его применять
    system.md        # инструкция для агента (системный промпт)
    examples.md      # примеры запросов и ожидаемых ответов

Если мы посмотрим на содержимое любого навыка, первое, что бросается в глаза — отсутствие лишнего. Нет общих вступлений вроде «в этой статье мы рассмотрим». Есть только конкретное описание задачи и набор правил, которым агент должен следовать.

Пример навыка для Claude Code

Claude Code читает файлы из .agents и подгружает их как контекст перед выполнением задачи. Ниже пример навыка, который заставляет агента вести себя как опытный инженер по инфраструктуре: он не предлагает быстрые костыли, а предлагает правильное решение с мониторингом и документацией.

Создаём папку .agents/infrastructure-review/ и кладём туда файл system.md:

markdown
# Инфраструктурный ревью

Ты — старший системный инженер с опытом работы с Linux, Docker и Kubernetes.
Твоя задача — проверить предложенное решение инженера и дать обратную связь.

Правила:
1. Не предлагай решения «на коленке». Если инженеру предлагают что-то быстрое, но ненадёжное, укажи на риски.
2. Требуй мониторинга и алертов для любого нового компонента.
3. Требуй документации: если изменение не задокументировано, считается, что оно не сделано.
4. Отвечай по существу, без вводных фраз.

Затем файл examples.md, чтобы агент понимал, как именно реагировать на типичные запросы:

markdown
## Пример 1

Пользователь: «Нужно быстро развернуть PostgreSQL в Docker, чтобы потестировать»

Агент: Перед запуском контейнера определите, где будут лежать данные. Без постоянного тома все данные пропадут после удаления контейнера. Используйте именованный том или привяжите директорию хоста:

docker run --name postgres-test \
  -e POSTGRES_PASSWORD=secret \
  -v pgdata:/var/lib/postgresql/data \
  -d postgres:15

После тестирования не забудьте удалить контейнер и том, иначе они будут занимать место на диске.

Файл README.md описывает, когда этот навык подключать:

markdown
# infrastructure-review

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

Теперь, когда инженер вызывает Claude Code с этой задачей, агент подгружает инструкции из .agents/infrastructure-review/ и отвечает уже не как чат-бот, а как коллега, который не пропустит костыль в продакшен.

Главное преимущество такого подхода — в том, что инструкции хранятся в репозитории вместе с кодом. Любой член команды может посмотреть, какие правила применяются к агенту, и предложить правку через pull request. Это делает работу с ИИ-помощником прозрачной и управляемой, а не чёрным ящиком.

Как подключить навыки к своему агенту

Навыки из репозитория mattpocock/skills не подключаются сами по себе — их нужно положить в то место, где агент их увидит. Для большинства инструментов это директория .agents в корне проекта. Агент сканирует её, подхватывает markdown-файлы с инструкциями и использует их как контекст при генерации кода или ответах на вопросы.

С практической точки зрения, это работает так же, как системные промпты, но версионируется вместе с кодом. Изменил навык — закоммитил, и все разработчики в команде получили обновлённую инструкцию. Хранить навыки в .agents — как держать инструкцию по сборке мебели в той же коробке, что и детали. Не нужно искать её в отдельном ящике стола.

Настройка Claude Code

Claude Code ищет навыки в поддиректории .agents. Во-первых, создайте её в корне репозитория:

bash
mkdir -p .agents/skills

Положите туда markdown-файлы с описанием навыка. Например, файл .agents/skills/review-code.md:

markdown
# code-review

Инструкция для проверки кода перед коммитом.

Проверяй:
- нет закомментированного кода и отладочных print-выражений;
- каждая публичная функция покрыта тестом;
- логирование ведётся через структурированный логгер, а не через console.log;
- нет хардкода секретов и ключей доступа.

Затем укажите путь к навыкам в конфигурации Claude Code. В файле .claude/settings.json (или эквивалентном для вашей версии) добавьте секцию с путями:

json
{
  "skills": {
    "directory": ".agents/skills"
  }
}

После этого агент будет подгружать инструкции из .agents/skills автоматически при каждом запросе. Если что-то пошло не так, проверьте, что файлы имеют расширение .md и не попали в .gitignore.

Интеграция с другими инструментами

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

В Cursor, например, навыки подключаются через настройки проекта. Добавьте в .cursor/rules или через интерфейс IDE путь к .agents/skills. Агент будет использовать их как дополнительный контекст при генерации кода в редакторе.

Для Continue (расширение для VS Code и JetBrains) настройка выглядит так. В файле config.json укажите путь к навыкам:

json
{
  "skills": {
    "paths": [".agents/skills"]
  }
}

Инструменты вроде Aider или Continue поддерживают подгрузку инструкций из локальных файлов, поэтому достаточно положить markdown в .agents и сослаться на него в конфиге.

С практической точки зрения, хранение навыков в .agents даёт предсказуемость: все в команде работают с одними и теми же инструкциями, и не нужно объяснять каждому новому сотруднику, как именно проверять код или писать тесты. Изменил навык в репозитории — обновил инструкцию для всего агентского контекста сразу.

Почему инженерам стоит хранить навыки отдельно

Когда я впервые заглянул в репозиторий с готовыми навыками для ИИ-агентов, первое, что бросилось в глаза, — это скрытая директория .agents в корне. Не docs, не scripts, а именно .agents. В ней лежат инструкции, которые агент читает перед тем, как выполнить действие: как перезапустить сервис, где посмотреть логи, как сделать откат деплоя. Для инженера это очевидная мысль: если процесс можно формализовать, его нужно хранить рядом с кодом, а не держать в голове или в закрытом вики.

У меня дома серверы названы в честь персонажей советских мультфильмов — Винни-Пух, Пятачок, Сова, Кролик. На Винни-Пухе крутится основное хранилище, на Пятачке — мониторинг. Когда я добавляю нового агента в эту инфраструктуру, я не хочу объяснять ему устно, где лежат конфиги каждого сервера. Проще положить инструкцию в .agents и забыть.

Предсказуемость и версионирование

Во-первых, это версионирование. Когда навык лежит в репозитории, он версионируется вместе с кодом приложения. Вы влили пул-реквест, который меняет API, и в том же коммите обновили навык для агента: теперь он знает про новый эндпоинт и не пытается позвать старый. Без такого подхода агент действует по устаревшей инструкции, и вы получаете инцидент в продакшене, который объяснять придётся долго.

С практической точки зрения, это означает, что изменение навыка проходит код-ревью, проходит через CI и попадает в продакшен только вместе с кодом, который он описывает.

Пример из практики. На одном из проектов мы использовали клон репозитория с навыками для внутреннего агента, который помогает дежурному инженеру разбирать инциденты. В навыке был прописан порядок действий при ротации сертификатов: проверить срок действия, обновить секрет в Kubernetes, перезагрузить поды. Когда мы перешли с cert-manager на ручное управление сертификатами, забыли обновить навык. Агент продолжал советовать дежурному запускать cert-manager, которого уже не было. Инцидент занял на два часа больше, чем должен был.

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

.agents/
  skills/
    deploy/
      instructions.md
      schema.json
    incident-response/
      instructions.md
    certificate-rotation/
      instructions.md

Каждый навык — это отдельный файл с инструкциями и, опционально, JSON-схемой для валидации аргументов. Если агент вызывает навык с неверными параметрами, он получит ошибку ещё до выполнения, а не после.

Вот как может выглядеть простой навык для перезапуска сервиса:

markdown
# skill: restart-service

Описание: Перезапускает systemd-сервис на целевом хосте через SSH.

Аргументы:
  - host: строка, имя хоста из инвентаря Ansible
  - service: строка, имя systemd-юнита

Шаги:
  1. Подключиться к хосту по SSH.
  2. Выполнить `sudo systemctl restart <service>`.
  3. Подождать 10 секунд.
  4. Проверить статус через `systemctl is-active <service>`.
  5. Если статус не active, вернуть ошибку с выводом журнала.

Важный момент: навык не содержит жёстко зашитых IP-адресов или паролей. Он принимает аргументы, а реальные значения подставляются из переменных окружения или секретов CI. Это делает навык переносимым между окружениями — разработкой, стадием и продакшеном.

Версионирование навыков даёт ещё один практический эффект: откат. Если новый навык ломает поведение агента, вы откатываете коммит, и агент снова работает по старой инструкции. Не нужно звонить коллеге и спрашивать, «а как там было раньше».

Когда навыки не нужны

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

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

Ещё один случай — когда навык дублирует уже существующую автоматизацию. Если у вас есть Ansible-плейбук или GitHub Action, который делает то же самое, не нужно оборачивать его в навык для агента. Агент может вызвать плейбук напрямую, если у него есть доступ к CI, но хранить дублирующую инструкцию в .agents — это лишняя сущность, которую нужно поддерживать.

Наконец, навыки не нужны там, где требуется контекст, который невозможно формализовать. Решение о том, стоит ли перезагружать продакшн-сервер в три часа ночи, зависит от множества факторов: текущая нагрузка, окно изменений, согласование с командой. Агент может предложить варианты, но принимать решение должен человек. В таких случаях навык только создаст иллюзию автоматизации, а реальная ответственность останется на инженере.

Критерий простой: если действие повторяется регулярно, имеет чёткие входные и выходные данные и влияет на стабильность системы — выносите в навык. Если нет — оставьте как есть.

Хранение навыков в .agents — это не дань моде, а способ сделать поведение ИИ-агента предсказуемым и подконтрольным. Как и любой код, навыки нужно версионировать, ревьюить и удалять, когда они устарели.

Часто задаваемые вопросы

Чем навык отличается от обычного промпта в чате с ИИ?

Промпт вы пишете каждый раз заново, и результат зависит от формулировки и настроения модели. Навык — это зафиксированный модуль с входными и выходными данными, который лежит в репозитории и подключается к агенту как готовый компонент. С практической точки зрения это даёт предсказуемость: одна и та же задача решается одинаково независимо от того, кто и когда запустил агента.

Куда класть файлы навыков и как агент их подхватывает?

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

Нужно ли версионировать навыки и зачем?

Да, потому что навык — это часть инфраструктуры, а не разовая записка. Если вы измените правила код-ревью в .agents/code-review.md, все агенты в команде начнут применять новые критерии сразу после пуша. Хранить навыки в Git позволяет откатить неудачное изменение и посмотреть, кто и когда правил инструкции.

Можно ли использовать один навык в разных репозиториях?

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

Что делать, если агент не следует инструкциям из .agents?

Сначала проверьте, что агент вообще сканирует директорию .agents и видит файлы с навыками. Затем убедитесь, что инструкции написаны однозначно: модель не угадывает, она следует буквальному тексту. Если проблема остаётся, стоит разбить навык на более мелкие части с чёткими входными и выходными данными.