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

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

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

## Как это работает {#kak-rabotaet}

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

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

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

```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» слишком расплывчата.

### Прогрессивная загрузка {#progressive-disclosure}

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

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

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

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

- **Системный промпт.** [Системный промпт](/pages/sistemnyy-prompt-neyroseti) загружается целиком в каждый запрос. Навык попадает в контекст только по описанию, а полный текст читается по требованию. Постоянные правила проекта (стиль кода, команды сборки) остаются в файлах вроде `CLAUDE.md`, а длинные процедуры выносят в навыки.
- **MCP.** [MCP](/pages/mcp-model-context-protocol) даёт агенту доступ к внешним системам: базе данных, трекеру, браузеру. Навык говорит, *как* работать: в каком порядке действовать и какие проверки сделать. Навык может ссылаться на инструменты MCP, и это разные, дополняющие друг друга механизмы.
- **Prompt template.** [Шаблон промпта](/pages/prompt-template) — текст с подстановками, который вы вызываете сами (например, командой `/review`). Навык агент может выбрать сам по описанию; в документации Pi навыки так и противопоставляют шаблонам: навык нужен, когда процессу требуется больше контекста, чем помещается в шаблон. В агентах из таблицы ниже навык можно ещё и вызвать вручную.

## Где применяются {#gde-primenyaetsya}

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

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

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

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

### Популярные репозитории {#repozitorii}

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

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

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

Что делать:

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

## Связь с RouterAI {#svyaz-s-routerai}

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

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

Навыки помогают экономить токены: вместо одного огромного промпта в контекст попадают только нужные инструкции. Больше приёмов экономии — в статье [как экономить токены в GPT, Claude и Gemini через единый API](/pages/gpt-claude-gemini-api). Цены зависят от модели и смотрятся в каталоге. Подробнее о том, как собрать контекст агента, — в статьях про [Agent Harness](/pages/agent-harness) и [контекст-инжиниринг](/pages/kontekst-inzhiniring-context-engineering).

## Что почитать {#chto-pochitat}

- [Спецификация Agent Skills](https://agentskills.io/specification) — формат `SKILL.md` и каталога навыка
- [Agent Skills в документации Anthropic](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) — архитектура, прогрессивная загрузка, безопасность
- [Skills в Claude Code](https://code.claude.com/docs/en/skills), [в Codex](https://developers.openai.com/codex/skills) и [в OpenCode](https://opencode.ai/docs/skills/)
- Статьи на сайте: [Agent Harness](/pages/agent-harness), [MCP](/pages/mcp-model-context-protocol), [Prompt Template](/pages/prompt-template), [системный промпт](/pages/sistemnyy-prompt-neyroseti)