Работа с навыками ИИ-агентов из .agents директории
Разбираем репозиторий mattpocock/skills: как организовывать инструкции для ИИ-агентов, где хранить навыки и зачем это инженерам.
Что такое навыки ИИ-агентов и зачем они нужны
Что такое навыки ИИ-агентов и зачем они нужны
Промпт — это инструкция, которую вы вводите в чат с моделью. Навык — это оформленный, версионируемый и переиспользуемый набор таких инструкций, который агент может применить к конкретной задаче без повторного объяснения контекста.
Если провести параллель с администрированием, обычный промпт — это разовая команда в терминале. Навык — это playbook или systemd-юнит: описан один раз, хранится в репозитории, работает предсказуемо при каждом запуске.
Во-первых, навык отделяет что нужно сделать от как это сделать. Агенту не нужно каждый раз объяснять, как собирать логи из journald или как сверять конфиг Nginx с эталоном. Он вызывает навык, а навык содержит уже отработанную последовательность действий.
С практической точки зрения, это даёт предсказуемость конфигураций. Если три инженера в команде спрашивают агента, как перезапустить сервис после изменения конфига, без навыка каждый получит свой ответ: кто-то предложит systemctl restart, кто-то service nginx reload, кто-то вообще предложит убить процесс вручную. С навыком ответ один, и он записан в репозитории.
Отличие навыка от обычного промпта
Обычный промпт живёт в контексте одного разговора. Закрыли вкладку — инструкция исчезла. Навык хранится в коде, проходит код-ревью и попадает в продакшен вместе с остальным репозиторием.
Вот пример. Обычный промпт выглядит так:
Проанализируй логи Nginx, найди все 5xx ошибки за последний час и скажи, какие эндпоинты чаще всего падают.
Агент выполнит, но завтра придётся объяснять всё заново. Навык — это отдельный файл с инструкцией, входными и выходными данными:
markdown# Навык: analyze-nginx-errors
## Описание
Сбор и анализ 5xx ошибок из логов Nginx за указанный период.
## Входные параметры
- log_path — путь к файлу логов Nginx (по умолчанию /var/log/nginx/error.log)
- period — временной интервал (по умолчанию 1h)
## Шаги выполнения
1. Проверить, что файл по пути log_path существует и доступен для чтения.
2. Отфильтровать строки с кодом ответа 5xx за указанный period.
3. Сгруппировать по URL-пути и подсчитать количество вхождений.
4. Вывести топ-10 эндпоинтов с наибольшим числом ошибок в формате Markdown-таблицы.
## Ожидаемый результат
Markdown-таблица с колонками: эндпоинт, количество ошибок, процент от общего числа.
Разница очевидна: промпт — это разговор, навык — это регламент. Первый зависит от того, как сформулировал вопрос человек, второй работает одинаково независимо от того, кто вызывает агента.
Кроме того, навык можно тестировать. Вы можете запустить агента с навыком на тестовом стенде, проверить вывод и зафиксировать ожидаемый результат. С обычным промптом так не получится — каждый запуск даст немного разный ответ из-за случайности в генерации модели.
Где хранить навыки: структура .agents
Навыки удобно держать рядом с кодом, который они обслуживают. В репозитории mattpocock/skills навыки вынесены в специальную директорию .agents в корне проекта. Это позволяет версионировать их вместе с инфраструктурой и отслеживать изменения через Git.
Примерная структура:
project-root/
├── .agents/
│ ├── skills/
│ │ ├── analyze-nginx-errors/
│ │ │ ├── skill.md
│ │ │ └── examples/
│ │ │ └── input-sample.log
│ │ ├── deploy-k3s/
│ │ │ ├── skill.md
│ │ │ └── vars.yaml
│ │ └── check-ssl-cert/
│ │ └── skill.md
│ ├── agents/
│ │ ├── infra-agent.md
│ │ └── deploy-agent.md
│ └── config.yaml
├── docker-compose.yml
└── README.md
Директория .agents скрыта от посторонних глаз (точка в начале имени), но доступна для Git. Внутри она делится на две части:
skills/— сами навыки. Каждый навык — отдельная папка с файломskill.md, где описаны входные параметры, шаги выполнения и ожидаемый результат. Можно добавлять примеры входных данных и эталонные ответы для регрессионного тестирования.agents/— определения агентов. Здесь описывается, какой набор навыков доступен конкретному агенту, какая у него системная инструкция и с какими инструментами он может взаимодействовать.config.yaml— общая конфигурация: пути к навыкам, наборы прав, переменные окружения.
Пример файла конфигурации агента:
yaml# .agents/agents/infra-agent.md
name: infra-agent
description: Агент для обслуживания инфраструктуры и мониторинга
system_prompt: |
Ты — системный инженер. Твоя задача — помогать с обслуживанием серверов,
анализом логов и развёртыванием сервисов. Всегда используй навыки из
директории .agents/skills, если они подходят к задаче.
available_skills:
- analyze-nginx-errors
- check-ssl-cert
- restart-systemd-service
tools:
- read_file
- execute_command
- network_request
И пример конфигурации навыка:
markdown# .agents/skills/check-ssl-cert/skill.md
## Название
Проверка срока действия SSL-сертификата
## Вход
- domain — доменное имя (обязательно)
- port — порт (по умолчанию 443)
## Шаги
1. Выполнить команду `openssl s_client -connect {domain}:{port} -servername {domain}`.
2. Из вывода извлечь дату истечения сертификата.
3. Сравнить с текущей датой.
4. Если до истечения меньше 14 дней — вернуть статус `warning`, иначе `ok`.
## Выход
JSON с полями: domain, expiry_date, days_remaining, status.
Хранить навыки в .agents удобно ещё и потому, что они путешествуют вместе с репозиторием. Склонировал проект — получил и навыки для работы с ним. Нет необходимости искать инструкции в Wiki или спрашивать у коллеги, как он в прошлый раз чинил этот же сервис.
Если мы посмотрим на опыт больших команд, разделение на навыки и агентов позволяет одному инженеру описывать процедуры, а другому — просто вызывать их, не вникая в детали реализации. Это то же самое, что разделить код на библиотеку и приложение, которое эту библиотеку использует.
Как подключить навыки к Claude Code и другим агентам
Как подключить навыки к Claude Code и другим агентам
Навыки в директории .agents — это не просто текстовые файлы с инструкциями. Это способ зафиксировать в репозитории то, как именно агент должен вести себя в контексте вашего проекта: какие правила код-ревью применять, как мигрировать базу данных, какие паттерны использовать при написании тестов. Если инструкции лежат рядом с кодом, они версионируются, ревьюятся и доставляются вместе с деплоем. Для инженера это значит предсказуемость: один и тот же навык даст одинаковый результат на ноутбуке коллеги и в CI.
Конфигурация .agents в репозитории проекта
Структура директории .agents может быть любой, но я придерживаюсь одного правила: каждый навык — отдельная подпапка с файлом инструкций и, при необходимости, примерами. Так проще поддерживать и не бояться сломать один навык, правив другой.
Примерная структура:
.agents/
├── config.yaml
└── skills/
├── code-review/
│ ├── instructions.md
│ └── examples/
│ └── good-pr.md
└── database-migration/
├── instructions.md
└── schema/
└── before-after.sql
Файл instructions.md — это то, что агент получит в контекст перед выполнением задачи. Пишите его как техническое задание для коллеги: без воды, с конкретными критериями.
Пример инструкции для навыка код-ревью:
markdown# Навык: код-ревью
Ты — старший инженер по код-ревью. Проверяй pull request по следующим критериям:
1. Новые функции покрыты тестами. Если тестов нет — укажи это явно.
2. Публичные API имеют документацию в формате OpenAPI или JSDoc.
3. Нет хардкода секретов, ключей или строк подключения к БД.
4. Изменения в БД сопровождаются миграцией.
Если критерий не выполнен, напиши комментарий к конкретной строке кода. Не давай общих оценок вроде «код хороший» — указывай на проблемы и предлагай исправление.
Чтобы агент подхватил навыки, в корне репозитория создаём файл CLAUDE.md (для Claude Code) или конфигурацию агента. Claude Code читает CLAUDE.md и подгружает из него ссылки на навыки.
Пример CLAUDE.md:
markdown# Контекст проекта
Проект — сервис учёта расходов на Go с PostgreSQL на бэкенде.
## Навыки
- code-review: `.agents/skills/code-review/instructions.md`
- database-migration: `.agents/skills/database-migration/instructions.md`
Используй навык code-review перед каждым коммитом. Используй database-migration при изменении схемы БД.
Для других агентов (Cursor, Copilot, Zed) механизм может отличаться, но принцип тот же: указать путь к .agents/skills/*/instructions.md в настройках или в конфигурационном файле редактора. Некоторые агенты поддерживают YAML-конфиг в корне репозитория:
yaml# .agents/config.yaml
version: 1
skills:
- name: code-review
path: .agents/skills/code-review/instructions.md
trigger: pull-request
- name: database-migration
path: .agents/skills/database-migration/instructions.md
trigger: schema-change
Если мы посмотрим на этот подход с практической точки зрения, главное — не раздувать навыки до размера целой документации. Каждый навык должен решать одну задачу и быть коротким enough, чтобы агент уложил его в контекстное окно без усечения.
Передача контекста и переменных окружения
Навык без контекста — это как инструкция без чертежа: агент поймёт, что делать, но не поймёт, для чего. Поэтому важно передавать в навык информацию о проекте: имя сервиса, окружение, версию API, пути к конфигам.
Самый простой способ — переменные окружения. Агент подхватит их из оболочки или из файла .env в корне репозитория.
Пример .env:
bashPROJECT_NAME=expense-tracker DEPLOY_ENV=production DATABASE_URL=postgres://user:pass@db:5432/expenses API_VERSION=v2
В файле инструкции навыка сошлитесь на эти переменные, чтобы агент знал, в каком контексте он работает:
markdown# Навык: database-migration
Работаем с базой проекта `${PROJECT_NAME}` в окружении `${DEPLOY_ENV}`.
Строка подключения: `${DATABASE_URL}`.
Перед запуском миграции проверь, что версия API равна `${API_VERSION}`.
Если версия не совпадает — прерви выполнение и уведоми пользователя.
Некоторые агенты позволяют передавать контекст через аргументы командной строки при запуске. Например:
bashclaude --skill database-migration --context env=production project=expense-tracker
Или через конфигурационный файл агента:
yaml# .claude/settings.json (пример)
{
"skills": {
"database-migration": {
"env": {
"DEPLOY_ENV": "staging",
"API_VERSION": "v2"
}
}
}
}
С практической точки зрения, я рекомендую хранить несекретный контекст в репозитории (имена проектов, версии API), а секреты — выносить в переменные окружения или секретное хранилище. Никогда не кладите пароли и ключи в .agents/skills/*/instructions.md, даже если агент обещает их не показывать наружу. Конфиги в репозитории попадают в git, а значит — в историю коммитов.
Если мы посмотрим на опыт работы с навыками в команде, главное правило такое: контекст должен быть явно объявлен, а не подразумеваться. Агент не должен гадать, в каком окружении он запущен. Это и есть та самая предсказуемость, от которой зависят стабильные серверы.
Практика: пишем первый навык для инфраструктуры
Практика: пишем первый навык для инфраструктуры
Навык — это не скрипт, который запускает агент. Это набор инструкций, которые говорят агенту, что проверить, какую команду выполнить и как интерпретировать результат. Для инженера это способ формализовать свой опыт, чтобы не объяснять одно и то же дважды.
Пример навыка для анализа логов Nginx
Во-первых, определим, что навык должен делать. Пусть это будет сбор логов Nginx за последний час, поиск 5xx ошибок и группировка по URL и IP. Назовём его nginx-log-analysis и положим в .agents/skills/nginx-log-analysis/.
Структура директории:
.agents/skills/nginx-log-analysis/
├── skill.md
├── analyze.sh
└── README.md
Файл skill.md — это инструкция для агента. Пишем её так, чтобы агент понимал, когда навык применим и какие команды выполнять.
markdown# Навык: анализ логов Nginx
## Описание
Навык помогает найти массовые 5xx ошибки в логах Nginx и определить, какой эндпоинт или IP создаёт наибольшую нагрузку.
## Когда использовать
Пользователь жалуется на 502 Bad Gateway или 504 Gateway Timeout. Нужно понять, разовый сбой это или систематическая проблема.
## Шаги
1. Посмотреть последние ошибки в error.log.
2. Из access.log извлечь URL с кодом 5xx за последний час.
3. Сгруппировать по количеству вхождений и вывести топ-20.
4. Если ошибки концентрируются на одном эндпоинте — сообщить об этом пользователю.
## Команды
- `sudo tail -n 100 /var/log/nginx/error.log` — последние ошибки сервера.
- `sudo awk '$9 ~ /5../ {print $7}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head -20` — топ URL с 5xx.
Обратите внимание на команду с awk. Мы ищем в девятой колонке коды ответа, начинающиеся с 5, и выводим séptмую колонку — запрашиваемый URL. Потом сортируем, считаем уникальные и берём двадцать первых. Это даёт представление, какие именно страницы ломаются чаще всего.
Скрипт analyze.sh можно оставить простым:
bash#!/bin/bash
set -euo pipefail
LOG_DIR="/var/log/nginx"
HOURS=1
echo "=== Последние ошибки Nginx ==="
sudo tail -n 100 "${LOG_DIR}/error.log"
echo ""
echo "=== Топ URL с 5xx за последний час ==="
sudo awk -v hours="${HOURS}" '
$9 ~ /^5../ {
split($4, dt, "[/:]")
print $7
}
' "${LOG_DIR}/access.log" | sort | uniq -c | sort -rn | head -20
С практической точки зрения, навык должен быть предсказуемым. Агент не должен гадать, что вернёт команда. Поэтому мы явно указываем пути к логам и фиксируем формат вывода.
Проверка и отладка навыка перед запуском
Прежде чем отдавать навык агенту, проверьте его сами. Запустите команды от имени того пользователя, от которого будет работать агент. Если агент запускается под пользователем agent, убедитесь, что у него есть права на чтение /var/log/nginx/.
bashsudo -u agent tail -n 10 /var/log/nginx/error.log
sudo -u agent awk '$9 ~ /5../ {print $7}' /var/log/nginx/access.log | head -5
Если команда возвращает «Permission denied», добавьте пользователя в группу adm или настройте sudo без пароля для конкретных команд:
bash# /etc/sudoers.d/agent-nginx-logs
agent ALL=(ALL) NOPASSWD: /usr/bin/tail /var/log/nginx/error.log, /usr/bin/awk /var/log/nginx/access.log
Во-вторых, проверьте, что навык не содержит деструктивных команд. rm, dd, перенаправление вывода в системные файлы — всё это должно быть исключено из навыков, которые агент может запускать без подтверждения.
Если мы посмотрим на вывод команды выше, он должен быть стабильным. Запустите её дважды с интервалом в минуту. Если результаты сильно отличаются, значит, логи ротируются или формат изменился — навык нужно адаптировать.
Наконец, протестируйте навык на реальном сервере. У меня дома на сервере «Винни-Пух» стоит Nginx с логами, и я периодически запускаю такой анализ вручную, прежде чем доверить его агенту. Сервер не падает годами, потому что я не добавляю в автоматизацию того, чего не проверял сам.
Когда навыки агентов становятся избыточными
Когда навыки агентов становятся избыточными
Директория .agents и навыки из репозитория mattpocock/skills помогают формализовать инструкции для ИИ-агентов: как собирать логи, перезапускать сервисы, проверять конфиги. Но навык — это не панацея. Как ящик с инструментами: полезен, пока не начинаешь хранить там сломанный молоток. Каждый инструмент должен быть на своём месте и использоваться по назначению.
С практической точки зрения, избыточность навыков проявляется в трёх ситуациях:
- задача выполняется раз в полгода и никогда не повторяется в одинаковом виде;
- для принятия решения нужен контекст, которого у агента нет: бизнес-логика, история инцидентов, договорённости с командой;
- ошибка агента стоит дороже времени, которое навык должен был сэкономить.
Во-первых, не стоит оформлять навыком разовую отладку. Если сервер упал ночью, и вам нужно посмотреть логи, проверить диск и перезапустить один контейнер — проще сделать это вручную, чем писать YAML-инструкцию для агента, отлаживать её и поддерживать в актуальном состоянии.
Например, такой навык избыточен:
yamlname: restart-web-container
description: Перезапустить веб-контейнер при ошибке 502
steps:
- command: docker ps --filter name=web --format "{{.ID}}"
- command: docker restart {{ container_id }}
Если инцидент случается раз в квартал, навык будет лежать мёртвым грузом. Человек справится быстрее, потому что он видит общую картину: был ли недавний деплой, менял ли кто-то балансировщик, есть ли плановые работы у провайдера.
Границы применения: что лучше оставить человеку
Некоторые задачи по своей природе остаются человеческими. Агент может предложить вариант, но финальное решение и выполнение должны остаться за инженером.
Разовые и ад-хок задачи. Навык хорош, когда его можно переиспользовать. Если вы настраиваете Nginx в первый раз и, скорее всего, больше не будете трогать этот конфиг год, не оборачивайте это в навык. Отредактируйте файл вручную:
nginxserver { listen 443 ssl; server_name app.example.com; ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; } }
После проверки конфига команда nginx -t && systemctl reload nginx выполнится быстрее, чем агент разберётся, какой именно сервер нужно перезагрузить.
Задачи с бизнес-контекстом. Агент не знает, почему таблица orders заблокирована: может быть, бухгалтерия запустила отчёт в разгар рабочего дня, а может быть, разработчик забыл закрыть транзакцию. Навык «разблокировать таблицу» без понимания причины приведёт к повторной блокировке через десять минут. Если мы посмотрим на историю инцидентов, станет ясно: здесь нужен человек, который свяжется с коллегами и примет взвешенное решение.
Критичные для безопасности операции. Ротация паролей, изменение правил файрвола, выдача прав суперпользователя в базе данных — всё это требует человеческого одобрения. Агент может ошибиться в символе и закрыть доступ к продакшену навсегда. Предсказуемость конфигурации важнее скорости её применения.
Творческое решение проблем. Когда стандартные метрики молчат, а пользователи жалуются на медленную работу, агент не предложит нестандартное решение. Он не вспомнит, что три месяца назад кто-то подключил старый бэкап к основной сети, и теперь есть конфликт IP. Инженер с опытом соединит эти факты быстрее, чем любой навык из .agents.
Итог простой: навыки агентов оправданы для повторяющихся, формализованных и низкорисковых операций. Всё остальное — зона ответственности человека. Не пытайтесь автоматизировать то, что происходит раз в полгода и требует контекста. Лучше потратьте время на документацию и мониторинг, чем на поддержку мёртвых навыков.