Agent Skills: как создать скилл для ИИ-агента — структура, правила и тесты

Agent Skills — открытый формат, в котором ИИ-агенту передают готовую процедуру: как развернуть сайт, провести аудит, собрать отчет. Навык описывают один раз в виде папки с файлом SKILL.md, и он без переделок работает в Claude Code, OpenAI Codex, Cursor, GitHub Copilot, VS Code, Gemini CLI и других агентах.

Формат придумала компания Anthropic, а 22 октября 2026 года передала его в Agentic AI Foundation — фонд под управлением Linux Foundation. Раньше туда же ушел протокол MCP. Задачи у них разные: MCP подключает ИИ к внешним данным и API, а Agent Skills хранит переносимые процедурные знания — то, что в компаниях называют регламентами (SOP). Сам формат SKILL.md при передаче не изменился.

Ниже — руководство по проектированию, упаковке и проверке скиллов по официальной спецификации agentskills.io.

Как устроен скилл

В основе Agent Skills лежит прогрессивное раскрытие контекста (progressive disclosure). Контекстное окно модели ограничено, а избыток инструкций снижает точность: модель хуже удерживает то, что находится в середине длинного текста. Поэтому скилл загружается в три приема:

1. Метаданные — всегда в контексте. При старте сессии агент читает у каждого установленного скилла только поля name и description из YAML-шапки SKILL.md. Это около 100 токенов на скилл. По ним модель понимает, какие навыки у нее есть.
2. Инструкции — при активации. Тело SKILL.md попадает в контекст, только когда скилл понадобился. Здесь алгоритм действий, ограничения, ссылки на дополнительные файлы и список типичных ошибок.
3. Ресурсы — по требованию. Файлы в references/, scripts/ и assets/ сами не читаются. Агент открывает их, когда доходит до нужного шага.

Структура папки

deploy-static-astro/
├── SKILL.md                 # обязательный файл: YAML-шапка и инструкции
├── references/              # документация, которую агент читает по необходимости
│   ├── nginx-vhost.conf
│   └── cache-headers.md
├── scripts/                 # исполняемые скрипты для точных операций
│   └── validate-build.sh
├── assets/                  # шаблоны и другие статические файлы
└── evals/                   # тестовые сценарии (не часть спецификации, см. ниже)
    └── evals.json

Что требует спецификация

Жесткие ограничения здесь только у полей шапки. 500 строк и 5000 токенов — рекомендация: скилл длиннее будет работать, но займет больше контекста, чем нужно.

Шесть правил разработки скиллов

1. Сначала решенная задача, потом скилл

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

Рабочий порядок такой:

1. Пройдите реальную задачу вместе с агентом в обычной сессии.
2. Поправьте его там, где он ошибся: выбрал не тот флаг утилиты, нарушил формат вывода.
3. Зафиксируйте команды, которые сработали, пути к файлам и граничные условия.
4. После успешного завершения упакуйте эту сессию в скилл.

Второй источник материала — то, что уже накоплено в проекте: внутренние регламенты, разборы инцидентов, история правок в Git.

2. Каждая строка проходит тест на ошибку

Когда черновик SKILL.md готов, проверьте каждую строку вопросом из руководства: ошибется ли агент, если этой инструкции не будет?

• Если нет — модель и так знает синтаксис Git и коды HTTP — строку удаляйте.
• Оставляйте то, что меняет поведение модели под ваши требования: нестандартную инфраструктуру, внутренние соглашения, бизнес-логику.

Короткая пошаговая инструкция с одним рабочим примером обычно работает лучше исчерпывающей документации.

3. Поле description — это триггер

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

• Лимит — 1024 знака. Это жесткое ограничение спецификации.
• Повелительная форма. Начинайте с «Используй этот скилл, когда…» (Use this skill when…), а не с «Этот скилл делает…».
• Намерение пользователя, а не реализация. Описывайте, с какой задачей к агенту придут, а не как устроен скилл внутри.
• Неявные запросы. Перечислите ситуации, где предметная область прямо не названа. Скилл для аудита Core Web Vitals должен срабатывать не только на «проверь CWV», но и на «почему медленно грузится страница» и «оптимизируй LCP и CLS».

Пример шапки:

---
name: nginx-php-fpm-hardening
description: Используй этот скилл, когда требуется настроить, оптимизировать или провести аудит связки Nginx + PHP-FPM на Linux-сервере (Debian/Ubuntu). Срабатывает при запросах на настройку виртуальных хостов, устранение ошибок 502 Bad Gateway и 504 Gateway Timeout, тюнинг пулов pm.max_children, настройку FastCGI-кэширования, ограничение частоты запросов или закрытие доступа к служебным директориям.
---

Триггер стоит проверить. Руководство советует собрать около 20 запросов: половина должна активировать скилл, половина — нет. Особенно полезны «почти подходящие» отрицательные примеры. Каждый запрос прогоняют несколько раз и смотрят, как часто скилл срабатывает.

4. SKILL.md не превращается в документацию

Держите основной файл в пределах 500 строк и 5000 токенов. Шаблоны конфигов, длинные SQL-запросы, справочники API и таблицы ошибок уходят в references/. В SKILL.md остается маршрутизация с точным условием: «Перед генерацией конфига прочитай references/nginx-vhost.conf и используй его как шаблон». Без условия агент либо не откроет файл, либо прочитает все подряд.

5. Точность там, где ошибка дорога, свобода — где нужен выбор

Конкретность инструкции должна соответствовать хрупкости операции.

• Операция хрупкая — давайте точную команду или скрипт. Вместо «сделай бэкап базы перед миграцией» пишите: mysqldump --single-transaction --routines --triggers "$DB_NAME" | gzip > "/var/backups/${DB_NAME}_$(date +%F_%H%M).sql.gz". Еще надежнее вынести логику в scripts/ и прямо запретить менять команду и добавлять флаги.
• Возможны варианты — задайте один по умолчанию. Не перечисляйте три равноправных способа. Назовите основной и коротко укажите, когда переходить на запасной.

6. Раздел Gotchas — самая ценная часть

Раздел «Типичные ошибки» (Gotchas) хранит то, чего модель знать не может: где она путает версии синтаксиса, забывает флаг, выбирает неочевидно неверный путь. Руководство называет такой список самым ценным содержимым многих скиллов.

Скилл — живой документ. Когда агент ошибся и вам пришлось его поправить, не ограничивайтесь правкой в чате: допишите правило в Gotchas.

Проверка скилла: evals/evals.json

Папка evals/ в спецификацию не входит — это прием из руководства agentskills.io по оценке качества. В файле evals/evals.json лежат тестовые запросы и описание ожидаемого результата. По ним видно, не сломался ли скилл после правки инструкций или смены модели.

{
  "skill_name": "nginx-php-fpm-hardening",
  "evals": [
    {
      "id": 1,
      "prompt": "На сервере с 4 ГБ RAM и 2 vCPU при пиковом трафике сыпятся ошибки 502 Bad Gateway от Nginx. В логах upstream prematurely closed connection. Посчитай настройки пула PHP-FPM и обнови конфиг.",
      "expected_output": "Обновленный конфиг пула PHP-FPM с расчетом pm.max_children и обоснованием выбранного режима pm.",
      "files": ["evals/files/www.conf"],
      "assertions": [
        "Измерено среднее потребление памяти одним процессом php-fpm",
        "pm.max_children рассчитан с резервом RAM под ОС и Nginx",
        "Перед перезапуском выполнены php-fpm -t и nginx -t"
      ]
    },
    {
      "id": 2,
      "prompt": "Подними виртуальный хост для example.com в /var/www/example/dist с долгим кэшированием статики и редиректом с www.",
      "expected_output": "Конфиг виртуального хоста Nginx на основе шаблона из references/.",
      "assertions": [
        "Использован шаблон references/nginx-vhost.conf",
        "Настроен 301-редирект с www.example.com на example.com",
        "Для ассетов задан Cache-Control: public, max-age=31536000, immutable"
      ]
    }
  ]
}

Как проходит проверка:

• Два прогона на сценарий. Один со скиллом, второй без него или с предыдущей версией. Без сравнения не понять, помогает ли скилл вообще.
• Чистый контекст. Каждый прогон начинается с нуля, иначе на результат влияет предыдущий разговор. В Claude Code для этого удобны субагенты.
• Оценка по утверждениям. Каждый пункт assertions получает «выполнено» или «не выполнено» с доказательством. Там, где возможно, проверку делает код, а не модель.
• Сводка. Сравнивают долю пройденных утверждений, время и расход токенов со скиллом и без него.

Смотрите не только итог, но и ход выполнения: по нему видно, какую инструкцию агент пропустил или понял не так.

Сборники скиллов: польза и риски

Скиллов уже очень много. По отчету Vercel от 25 сентября 2026 года, в реестре skills.sh опубликован миллион скиллов и набралось почти 280 миллионов установок. При этом почти половину скиллов установили всего один раз, а 62% установок приходится на 0,04% скиллов. Большая часть реестра — балласт.

На GitHub появляются и тематические сборники. Например, gamedev-skills/awesome-gamedev-agent-skills — 79 скиллов и скилл-маршрутизатор для 12 игровых движков, среди которых Godot, Unity, Unreal Engine, Roblox, three.js и Phaser. Он пригодится тем, кто делает игру в одиночку с ИИ-агентами. Работая с такими наборами, учитывайте три ограничения.

Не ставьте набор целиком. Каждый скилл добавляет в контекст около 100 токенов метаданных. Набор из 79 скиллов — это примерно 8000 токенов еще до первого запроса и риск конфликта триггеров: скилл оптимизации рендеринга для Unity начнет срабатывать в проекте на Godot. Берите только скиллы под стек проекта.

Отсеивайте скиллы без опыта. Многие скиллы в сборниках написаны в нарушение первого правила: это общие советы без обкатки на реальной задаче. Откройте SKILL.md. Если там нет конкретных команд, путей, версий и раздела Gotchas, такой скилл только займет контекст.

Проверяйте содержимое перед установкой. В scripts/ лежит исполняемый код, а текст SKILL.md агент воспринимает как инструкцию. Чужой скилл может увести переменные окружения с ключами API и SSH или заставить агента выполнить посторонние команды. Это тот же класс угроз, что и у MCP-серверов. Аудит Snyk в феврале 2026 года нашел вредоносный код в 76 из 3984 проверенных скиллов. Перед установкой читайте SKILL.md и все вложенные файлы.

Готовый промпт: упаковать сессию в скилл

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

Следуя спецификации https://agentskills.io/specification и руководству https://agentskills.io/skill-creation/best-practices, упакуй задачу, которую мы только что выполнили, в переносимый Agent Skill.

Требования:
1. Источник данных: используй только те команды, шаги, форматы данных и решения, которые реально сработали в этой сессии, мои исправления, а также относящиеся к задаче правила из CLAUDE.md, AGENTS.md и истории Git этого репозитория. Не восполняй пробелы общими знаниями и банальными советами.
2. Имя: придумай короткое имя скилла (строчные латинские буквы, цифры и дефисы, до 64 знаков). Создай папку с этим именем в каталоге скиллов проекта.
3. Триггер: напиши поле description в форме «Используй этот скилл, когда…». Включи и прямые сценарии запуска, и неявные формулировки проблем, при которых скилл должен активироваться. Не больше 1024 знаков.
4. Объем: SKILL.md — до 500 строк и 5000 токенов. Удали каждую строку, без которой ты и так не ошибся бы. Длинные шаблоны, конфиги, схемы и справочники вынеси в references/ и укажи в SKILL.md точное условие, когда читать каждый файл. Сложные команды и проверки оформи скриптами в scripts/.
5. Точность: для критичных операций дай точные команды; там, где возможны варианты, укажи один по умолчанию и условия перехода на запасной.
6. Типичные ошибки: сделай раздел Gotchas и перенеси в него все ошибки и исправления из этой сессии.
7. Проверка: создай evals/evals.json с 2–3 реалистичными сценариями (поля prompt, expected_output, assertions). Прогони каждый сценарий со скиллом и без него в чистом контексте, покажи результаты по каждому утверждению и коротко опиши созданные файлы.

Скиллы в рабочем проекте

• Храните скиллы в репозитории. Проектные скиллы лежат рядом с кодом под Git: в .claude/skills/ у Claude Code или в .agents/skills/ у других агентов. Точный путь смотрите в документации своего агента.
• Обновляйте скилл вместе с кодом. Поменялась инфраструктура или стек — правьте скилл тем же коммитом. Устаревший скилл хуже отсутствующего: агент уверенно выполнит неверную процедуру.
• Пополняйте Gotchas. Каждая ошибка агента, которую пришлось исправлять вручную, — новая строка в разделе.
• Перепроверяйте после смены модели. Прогоните evals/evals.json: инструкция, которая была нужна прежней модели, новой может мешать.