Что такое skill: указатель в упаковке

Зачем это нужно

Документ с указателем (см. 5.2) работает, но живёт внутри одного репозитория. Чтобы та же процедура появилась в соседнем проекте или у коллеги, файл и строку-указатель придётся переносить руками, и каждая копия начнёт жить своей жизнью.

Skill решает именно это. Это тот же документ с указателем, только упакованный в стандартную папку, которую можно передать, положить в другой проект или раздать команде.

Как это устроено

Папка и SKILL.md

Skill — папка с обязательным файлом SKILL.md. Файл состоит из YAML frontmatter между маркерами --- и Markdown-тела с инструкциями:

---
name: database-migrations
description: Database schema changes - generate the migration, update the seed, reseed. Use when editing the schema or adding or altering a table column.
---

# Database migrations

1. Edit `app/db/schema.ts`.
2. Run `npm run db:generate`.
3. Update `scripts/seed.ts` to match the new shape.
4. Run `npm run db:seed`, then `npm run typecheck`.

Формат — открытый стандарт Agent Skills (agentskills.io). Claude Code следует ему и добавляет свои поля. Skill, который обходится полями стандарта, работает и в других агентах, которые его поддерживают.

Progressive disclosure: что и когда загружается

Стандарт описывает три стадии:

1. Discovery. При старте агент загружает только name и description каждого skill — ровно столько, чтобы понять, когда он может пригодиться.
2. Activation. Когда задача совпадает с описанием, агент читает в контекст весь SKILL.md.
3. Execution. Агент выполняет инструкции и при необходимости открывает файлы из папки skill.

Значит, description — это и есть context pointer skill-а: он лежит в контексте всегда, а тело — нет. В Claude Code текст description вместе с полем when_to_use обрезается в списке skills до 1536 символов, поэтому главный сценарий использования ставят первым.

Вспомогательные файлы

В папке skill могут лежать и другие файлы: справочник, примеры, скрипты. SKILL.md ссылается на них с условием, когда их открывать, и агент читает их, только если нужно. Это тот же приём на уровень ниже: документация Claude Code советует держать SKILL.md короче 500 строк и выносить подробности в отдельные файлы.

Кто вызывает skill

По умолчанию skill может вызвать и агент, и вы, набрав /name. Поведение меняется одним полем frontmatter:

Это компромисс двух нагрузок. Skill, который вызывает агент, стоит одну строку описания в каждом запросе, зато агент найдёт его сам. Skill с disable-model-invocation: true не стоит контекста вообще, но помнить о нём и вызывать его вовремя придётся вам. Документация советует второй вариант для действий с побочными эффектами вроде /deploy: вы не хотите, чтобы агент решил выкатить код, потому что он «выглядит готовым».

Практика

Наберите в Claude Code /skills. Команда показывает доступные skills с описаниями. Нажмите t, чтобы отсортировать список по числу токенов: так видно, сколько контекста занимает каждый skill. Найдите skill, который вы ни разу не вызывали, и решите, нужен ли агенту его description в каждом запросе.

Подводные камни

• Сломанный frontmatter. Если YAML не разбирается, skill всё равно загружается, но без полей: /name работает, а агент не может сопоставить задачу с description. Запустите Claude Code с --debug, чтобы увидеть ошибку разбора.
• Слишком много skills. Список описаний занимает около 1% контекстного окна. Когда skills не помещаются, Claude Code выбрасывает описания тех, что вызываются реже всего, и агент перестаёт их находить.

Вывод: skill — это указатель в упаковке; в контексте всегда лежит только его описание, поэтому описание — главное, что нужно написать хорошо.

Проверь себя

Источники

• Anthropic, Extend Claude with skills
• Anthropic, Commands
• Agent Skills, What are Agent Skills?
• По мотивам AI Coding Crash Course, AI Hero