support@routerai.ru

Загрузка...

Agent Skills (навыки ИИ-агента, SKILL.md): что это и как работают

Содержание статьи

Agent Skills (навыки ИИ-агента) — это папки с инструкциями, скриптами и справочными файлами, которые coding-агент подгружает только тогда, когда они нужны для задачи. Главный файл навыка называется SKILL.md: в нём короткое описание («что умеет и когда применять») и подробная инструкция. Агент видит только описания, а полный текст читает по необходимости.

Навыки появились как способ «обучить» универсального агента узкой работе: оформить релиз по правилам команды, заполнить PDF-форму, провести ревью кода по чек-листу. Формат описан в открытой спецификации Agent Skills, поэтому один и тот же навык можно положить в разные агенты: Claude Code, Codex, OpenCode, Pi и другие. Навыки работают на стороне агента, а модели для них можно подключать через RouterAI.

Как это работает

Навык — это каталог, в котором обязателен только SKILL.md:

pdf-processing/
├── SKILL.md          # обязательно: метаданные + инструкции
├── scripts/          # необязательно: исполняемый код
│   └── fill_form.py
├── references/       # необязательно: документация
│   └── FORMS.md
└── assets/           # необязательно: шаблоны, ресурсы

Файл SKILL.md начинается с YAML-заголовка (frontmatter), дальше идёт текст в Markdown:

---
name: pdf-processing
description: Извлекает текст и таблицы из PDF, заполняет формы, объединяет файлы. Используй, когда пользователь работает с PDF-документами или упоминает формы.
---

# Работа с PDF

1. Для извлечения текста используй pdfplumber.
2. Для заполнения форм прочитай `references/FORMS.md`.
3. Проверку формы запускай скриптом `scripts/fill_form.py`.

По спецификации обязательны два поля: name (до 64 символов, строчные латинские буквы, цифры и дефисы, совпадает с именем каталога) и description (до 1024 символов). Необязательные поля: license, compatibility, metadata и экспериментальное allowed-tools. Описание определяет, когда агент решит применить навык, поэтому в нём пишут и что навык делает, и в каких случаях его брать: фраза «Помогает с PDF» слишком расплывчата.

Прогрессивная загрузка

Навыки загружаются в три уровня (так их описывают спецификация и документация Anthropic):

Уровень Когда загружается Что занимает в контексте
Метаданные При старте, для всех навыков name и description, около 100 токенов на навык
Инструкции Когда агент решил применить навык Тело SKILL.md, рекомендуется до 5000 токенов
Ресурсы Только по ссылке из инструкции Файлы из references/, assets/; у скриптов в контекст попадает лишь их вывод

Поэтому можно установить десятки навыков и не «платить» за них в каждом запросе: пока навык не понадобился, он занимает в контексте пару строк. Сам агент читает SKILL.md обычной командой чтения файла или через специальный инструмент, а скрипты запускает как shell-команды.

Чем отличаются от системного промпта, MCP и шаблонов

  • Системный промпт. Системный промпт загружается целиком в каждый запрос. Навык попадает в контекст только по описанию, а полный текст читается по требованию. Постоянные правила проекта (стиль кода, команды сборки) остаются в файлах вроде CLAUDE.md, а длинные процедуры выносят в навыки.
  • MCP. MCP даёт агенту доступ к внешним системам: базе данных, трекеру, браузеру. Навык говорит, как работать: в каком порядке действовать и какие проверки сделать. Навык может ссылаться на инструменты MCP, и это разные, дополняющие друг друга механизмы.
  • Prompt template. Шаблон промпта — текст с подстановками, который вы вызываете сами (например, командой /review). Навык агент может выбрать сам по описанию; в документации Pi навыки так и противопоставляют шаблонам: навык нужен, когда процессу требуется больше контекста, чем помещается в шаблон. В агентах из таблицы ниже навык можно ещё и вызвать вручную.

Где применяются

Поддержка навыков заявлена в документации самих инструментов:

Агент Где лежат навыки Как вызвать вручную
Claude Code ~/.claude/skills/ (личные), .claude/skills/ (проект) /имя-навыка
Codex .agents/skills в репозитории, $HOME/.agents/skills /skills или $ и имя навыка
OpenCode .opencode/skills/, .claude/skills/, .agents/skills/ и глобальные аналоги через инструмент skill, при настройке — как /имя
Pi ~/.agents/skills/, .agents/skills/ и каталоги Pi /skill:имя

Claude Code, Codex, OpenCode и Pi следуют спецификации Agent Skills, поэтому пути вроде .agents/skills/ и .claude/skills/ понимают сразу несколько агентов. Подробные правила (приоритеты, одинаковые имена, дополнительные поля) смотрите в документации конкретного инструмента: у каждого агента есть свои расширения формата.

Типичные задачи для навыков: методика разработки (спецификация, план, TDD, ревью), работа с форматами (PDF, Word, Excel), инструкции по деплою и релизам, дизайнерские и маркетинговые чек-листы.

Популярные репозитории

  • obra/superpowers — набор навыков и методология разработки: уточнение задачи, план, TDD, работа субагентов. Лицензия MIT; в README есть инструкции установки для Claude Code, Codex, OpenCode, Pi, Qwen Code, Hermes Agent и других агентов.
  • addyosmani/agent-skills — инженерные навыки по этапам разработки (спецификация, план, реализация, тесты, ревью, релиз). Устанавливаются командой npx skills add addyosmani/agent-skills через открытый CLI vercel-labs/skills.
  • Leonxlnx/taste-skill — навыки, которые учат агента аккуратному веб-дизайну вместо шаблонных «ИИ-страниц».
  • coreyhaines31/marketingskills — навыки для маркетинговых задач: копирайтинг, SEO, оптимизация конверсии, аналитика.
  • anthropics/skills — публичный репозиторий Anthropic с примерами навыков.

Риски: навык — это исполняемые инструкции

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

Что делать:

  • перед установкой прочитать весь каталог навыка: SKILL.md, скрипты, вложенные файлы;
  • обращать внимание на сетевые вызовы, чтение секретов и действия, не связанные с задачей навыка;
  • ставить сторонние навыки в проект, а не глобально, и запускать агента в изолированном окружении;
  • фиксировать версию (коммит) репозитория и обновлять её осознанно.

Связь с RouterAI

Навыки хранятся и исполняются в агенте на вашей машине. RouterAI в этой схеме отвечает за модель: агент отправляет запросы (с описаниями навыков и прочитанными инструкциями) на https://routerai.ru/api/v1 для OpenAI-совместимых клиентов или https://routerai.ru/api для Anthropic Messages API. Ключ и оплата в рублях общие, работает из России без VPN, а каталог моделей один для всех агентов. Навыки не привязаны к модели, но агенту нужна модель с вызовом инструментов: она должна читать файлы и запускать команды.

Задача Пример модели из каталога
Основная работа агента с навыками anthropic/claude-sonnet-5.5
Быстрые и недорогие шаги anthropic/claude-haiku-5.5, deepseek/deepseek-v4-flash
Альтернатива от OpenAI openai/gpt-5.5

Навыки помогают экономить токены: вместо одного огромного промпта в контекст попадают только нужные инструкции. Больше приёмов экономии — в статье как экономить токены в GPT, Claude и Gemini через единый API. Цены зависят от модели и смотрятся в каталоге. Подробнее о том, как собрать контекст агента, — в статьях про Agent Harness и контекст-инжиниринг.

Что почитать