Скилы в ИИ-агентах

Как агент вроде Claude Code узнаёт о сотне инструкций, но держит в контексте только нужную. Что такое SKILL.md, как модель решает его загрузить, что при этом попадает в разговор и как написать скил, который срабатывает.

Листайте стрелками ← →, свайпом или кнопками внизу. В схемах нажимайте кнопки и двигайте ползунки.

Агент — это цикл

Модель не «помнит» ничего между вызовами. Агент — это программа, которая каждый раз отправляет модели весь разговор, получает ответ, выполняет запрошенный инструмент и дописывает результат в разговор.

  • Контекстное окно — единственная память. Что не попало в него, модель не знает.
  • Каждый шаг заново обрабатывает весь контекст: системный промпт, описания инструментов, историю.
  • Окно конечно: 200 тыс. токенов у большинства моделей Claude, до 1 млн у некоторых.

Почему не положить всё в системный промпт

У команды десятки регламентов: как писать миграции, как оформлять релиз, как разбирать инцидент. Положить их все в системный промпт или CLAUDE.md — значит платить за них на каждом шаге и размывать внимание модели посторонним текстом.

  • Длинный промпт — всё и всегда; кэш снижает цену, но не занятое место.
  • RAG — поиск кусков по похожести; инструкцию, разрезанную на куски, легко собрать не целиком.
  • Инструменты и MCP — дают действия и доступ, но не знание, как делать задачу.

Скил — это папка

Обязателен один файл, SKILL.md: YAML-фронтматтер с именем и описанием и markdown-инструкции. Рядом — что угодно: справочники, шаблоны, скрипты. Агент читает их с диска сам, когда инструкции на них ссылаются.


pdf-forms/
├── SKILL.md         # метаданные + инструкции
├── forms.md         # читается по ссылке
├── reference.md     # 600 строк про pdfplumber
├── assets/
│   └── w9-fields.json
└── scripts/
    ├── analyze_form.py  # запускается
    └── fill_form.py

Стандарт (agentskills.io) советует папки scripts/, references/, assets/, но не требует их.


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

# PDF: формы и извлечение

## Извлечь текст
Используй pdfplumber:
    with pdfplumber.open(path) as pdf:
        text = pdf.pages[0].extract_text()

## Заполнить форму
1. `python scripts/analyze_form.py in.pdf`
   → JSON с полями формы
2. Сопоставь поля с данными пользователя.
3. `python scripts/fill_form.py in.pdf f.json out.pdf`
Подводные камни — в [forms.md](forms.md).

Фронтматтер: что в нём бывает

Открытый стандарт
name
до 64 символов: a-z, 0-9, дефис; совпадает с именем папки
description
до 1024 символов: что делает и когда применять
license, compatibility, metadata
лицензия, требования к окружению (до 500 символов), произвольные ключи
allowed-tools
заранее одобренные инструменты; помечено экспериментальным

API и claude.ai: name и description обязательны, без XML-тегов, имя не может содержать «anthropic» и «claude».

Только Claude Code
when_to_use
дописывается к описанию; вместе обрезаются до 1536 символов
disable-model-invocation
true — только ручной вызов /имя, описание не попадает в контекст
user-invocable
false — скрыть из меню /, вызывает только модель
argument-hint, arguments
подсказка и имена аргументов для $name
context: fork, agent
выполнить скил в сабагенте с отдельным контекстом
paths, model, effort, hooks, disallowed-tools
автоактивация по glob, модель, усилие, хуки, запрет инструментов

В Claude Code все поля необязательны: имя по умолчанию — имя папки. Неизвестные поля молча игнорируются.

Прогрессивное раскрытие

Скил грузится в контекст по уровням, и каждый следующий — только если нужен.

  1. Метаданные, ~100 токенов на скил: имя и описание всех скилов всегда в контексте.
  2. Тело SKILL.md, рекомендуют до 5 тыс. токенов и 500 строк: читается, когда скил выбран.
  3. Остальные файлы: справочник читается, только если на него сослались; скрипт запускается, и в контекст попадает лишь его вывод.

Выберите запрос и проходите по шагам. Следите, какие файлы остаются на диске.

Сто скилов в одном окне

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

Двигайте ползунки и сравните, сколько контекста занимают те же знания в двух подходах.

Описания всё же не бесплатны: Claude Code отводит списку скилов около 1% окна и при переполнении выбрасывает описания у редко вызываемых скилов — остаются одни имена. Посмотреть стоимость: /context и /skill-doctor.

Кто выбирает скил

Ни роутера, ни эмбеддингов, ни поиска по словам. Список описаний лежит в контексте, и модель сама решает, подходит ли какое-то к задаче. Описание — всё, что она знает о скиле до загрузки.

  • В описании две части: что делает и когда применять.
  • Слова, которыми говорит пользователь: «анкета», «прод лежит», «changelog».
  • Третье лицо: описание вставляется в системный промпт.

Задачка: скил не срабатывает

В проекте 60 скилов. Вы добавили deploy-staging с описанием «Деплой». На просьбу «выкати ветку на стенд» агент запускает kubectl наугад и скил не трогает. Что поможет вернее всего?

Поля приоритета нет ни в стандарте, ни в Claude Code (неизвестные поля молча игнорируются). Тело до выбора скила модель вообще не видит. Решение принимается по описанию, а «Деплой» не связан ни со «стендом», ни с «выкати». Ещё проверьте, что описание не выброшено из-за бюджета списка: спросите «What skills are available?» или посмотрите /context. Если скил нужен только по команде — disable-model-invocation: true и вызов /deploy-staging.

Что происходит в разговоре

В Claude Code у модели есть инструмент Skill. Вызов с именем скила подставляет содержимое SKILL.md в разговор отдельным сообщением, и оно остаётся там до конца сессии. Через API и в claude.ai отдельного инструмента нет: модель читает файл командой cat в контейнере.

Выберите способ вызова и листайте сообщения. Справа — сколько токенов добавил каждый шаг.

Аргументы и подстановки

До того как текст скила попадёт к модели, Claude Code его рендерит: подставляет аргументы и выполняет команды из !`…`. Модель видит уже результат — вывод git, а не просьбу его запустить.

  • $ARGUMENTS — вся строка, $0, $1… — по позиции (с нуля).
  • Нет плейсхолдера — Claude Code допишет ARGUMENTS: … в конец.
  • Команда упала — весь вызов скила прерывается; терпимость — || true.

Скрипты: код вместо генерации

Отсортировать список, проверить 40 полей формы, посчитать контрольную сумму — это дёшево и надёжно сделать кодом и дорого и ненадёжно — генерацией токенов. Скрипт в скиле пишут один раз и тестируют; модель его только запускает.

  • Пишите в инструкции явно: «запусти» или «прочитай как пример».
  • Скрипту нужен исполнитель: Bash в Claude Code, code execution tool в API.
  • Окружение разное: в API контейнер без сети и без установки пакетов, в claude.ai сеть зависит от настроек, в Claude Code — ваша машина целиком.

Жизнь скила в контексте

  • Загруженный SKILL.md — одно сообщение в разговоре. Claude Code не перечитывает файл: правки вступят в силу при следующем вызове.
  • Повторный вызов с тем же содержимым добавляет короткую пометку «уже загружен», а не вторую копию.
  • При сжатии контекста (compaction) Claude Code снова прикладывает последние вызванные скилы: первые 5000 токенов каждого, всего не больше 25 000 токенов, начиная с самых свежих.
  • Правило, которое должно выполняться всегда, — в хук, а не в текст скила.

Скил на 12 000 токенов, в самом конце — «никогда не правь файлы в migrations/». Через час работы контекст сжали, и агент поправил миграцию. Почему?

После compaction скил возвращается в контекст, но обрезанным до первых 5000 токенов. Важное — в начало файла, детали — в отдельные файлы, а запрет на запись в migrations/ надёжнее сделать хуком PreToolUse: хук срабатывает на каждой правке, следует модель скилу или нет. Можно и просто вызвать скил ещё раз.

Скил, CLAUDE.md, MCP, сабагент или хук

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

Где живут скилы

Claude Code

  • ~/.claude/skills/<имя>/ личные, во всех проектах
  • .claude/skills/<имя>/ проектные, коммитятся в репозиторий
  • sub/.claude/skills/ вложенные: подгружаются, когда агент заходит в sub/
  • <плагин>/skills/ из плагина, вызов /плагин:имя
  • managed settings корпоративные

При совпадении имён: корпоративный > личный > проектный. Изменения в папках подхватываются без перезапуска.

API и claude.ai

  • API загрузка через /v1/skills, доступны всему workspace; в запросе — container.skills (до 20) и code execution tool
  • claude.ai zip в настройках, только для своего аккаунта; нужен code execution
  • Готовые pptx, xlsx, docx, pdf — в API и claude.ai, в Claude Code их нет

Поверхности не синхронизируются. Исключение из свежих версий Claude Code: при входе через аккаунт claude.ai его скилы скачиваются в ~/.claude/skills/synced/ — только в одну сторону.

Открытый стандарт

Формат придумали в Anthropic (октябрь 2025) и в декабре 2025 опубликовали как открытый стандарт на agentskills.io.

Поддерживают: OpenAI Codex, Cursor, Gemini CLI, GitHub Copilot и VS Code, JetBrains Junie, OpenCode, Goose, Amp, Roo Code, Kiro, OpenHands и другие.

Общая часть — папка, SKILL.md, name и description. Пути, способ вызова и дополнительные поля у каждого агента свои.

Скил — это код, который запустят

Чужой скил — то же самое, что чужой пакет из npm с post-install-скриптом, только инструкции к нему читает модель с вашими правами. Документация Anthropic: ставить только из доверенных источников, остальное — читать целиком перед установкой.

  • Проверяйте все файлы: скрипты, справочники, даже картинки.
  • Ссылки на внешние URL опасны вдвойне: содержимое по ним может измениться после вашей проверки.

Найдите в скиле всё подозрительное: нажимайте на строки.

Права: что разрешает скил

  • allowed-tools в Claude Code — это разрешение без вопроса, пока выполняется вызвавший скил ход. Других инструментов оно не ограничивает.
  • Убрать инструменты, пока скил активен, — disallowed-tools.
  • Запретить сам скил — правило разрешений Skill(имя); все скилы — запретить Skill.
  • Политика disableSkillShellExecution отключает команды !`…` в скилах.
  • В стандарте allowed-tools экспериментальное: другие агенты могут понимать его иначе или игнорировать.

В скиле allowed-tools: Read Grep. По его инструкции модель хочет выполнить rm -rf build/. Что сделает Claude Code в обычном режиме?

allowed-tools — список «можно без вопроса», а не белый список. Bash остаётся доступным и проходит обычную проверку разрешений: в интерактивном режиме — вопрос пользователю. Чтобы скил не мог запускать Bash вовсе, нужен disallowed-tools: Bash или запрещающее правило в настройках.

Как написать описание

  • Что делает + когда применять: «Используй, когда…».
  • Конкретика: форматы файлов, инструменты, слова пользователя.
  • Третье лицо: «Заполняет формы», а не «Я помогу заполнить».
  • Главное — в начале: длинный список могут обрезать.
  • Имя: строчные буквы, цифры, дефис; лучше processing-pdfs, чем helper.

Правьте описание или выберите пример — проверка идёт по правилам стандарта и рекомендациям Anthropic.

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

Делайте

  • Пишите только то, чего модель не знает: ваши таблицы, правила, команды. «Что такое PDF» она знает.
  • Узкий мост — точная команда; открытое поле — общие принципы. Степень свободы по хрупкости задачи.
  • Ссылки на файлы — на один уровень от SKILL.md; у длинных справочников — оглавление.
  • Сначала прогоните агента на 3 реальных задачах без скила, запишите провалы, потом пишите минимум, который их чинит.
  • Смотрите, как агент ходит по файлам: что читает, что пропускает. Правьте по наблюдениям.

Не делайте

  • Пять библиотек на выбор. Одна по умолчанию и запасной вариант
  • Цепочки ссылок SKILL.md → a.md → b.md. Агент может прочитать вложенный файл частично (head)
  • «До августа делай так, после — иначе». Раздел «устаревшее»
  • Скрипт, который падает и «пусть модель разбирается». Обработка ошибок и понятные сообщения
  • Пути с \ и магические константы без объяснения.

Первый скил за 5 минут

Пример из документации Claude Code: скил, который сам смотрит git diff и описывает изменения. Имени в фронтматтере нет — возьмётся имя папки.


---
description: Summarizes uncommitted changes and flags
  anything risky. Use when the user asks what changed,
  wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet
points, then list any risks you notice. If the diff
is empty, say there are no uncommitted changes.


# 1. папка и файл (слева)
mkdir -p ~/.claude/skills/summarize-changes
$EDITOR ~/.claude/skills/summarize-changes/SKILL.md

# 2. проверить в Claude Code
/skills                    # есть ли в списке
What did I change?         # должен сработать сам
/summarize-changes         # явный вызов

# 3. если не срабатывает
claude --debug             # ошибка разбора YAML
claude plugin validate ~/.claude/skills
/context                   # размер списка скилов
/skill-doctor              # цена и неиспользуемые

# стандарт: валидатор для любого агента
skills-ref validate ./summarize-changes

Главное

  • Агент — цикл вокруг модели, контекст — его единственная память, и каждый токен в нём оплачивается на каждом шаге.
  • Скил — папка с SKILL.md. В контексте всегда только имя и описание; тело — когда скил выбран; файлы и скрипты — по мере надобности.
  • Выбирает сама модель, читая описания. Описание со словами «что» и «когда» — главное поле скила.
  • В Claude Code скил вызывается инструментом Skill или /имя, рендерится с аргументами и выводом команд и остаётся в разговоре.
  • Детерминированную работу — в скрипты; правила «всегда» — в хуки; доступ к системам — в MCP; объёмный поиск — в сабагент.
  • Скил — это код с вашими правами. Только из доверенных источников и после чтения.

Хороший скил похож на памятку для нового сотрудника: коротко, по делу и со ссылками на подробности.

К списку презентаций