Что такое навык агента (Agent Skill) — и почему он почти ничего не стоит

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

Это и есть навык агента (Agent Skill). И да, технически это просто папка с текстовым файлом.

Навык — это папка, а не код

Минимальный навык выглядит так:

release-checklist/
└── SKILL.md

Всё. Один файл SKILL.md — и навык готов. Внутри он делится на две части: служебная «шапка» в самом верху и обычный текст инструкции под ней.

---
name: release-checklist
description: Проверить релиз перед выкаткой. Использовать, когда просят
  собрать релиз, выпустить версию или подготовить сборку.
---

Перед выкаткой пройди по шагам:

1. Прогони тесты, убедись, что они зелёные.
2. Подними номер версии в манифесте.
3. Проверь, что в changelog попали все правки.

Шапка (её называют frontmatter) — это YAML между двумя тройными дефисами. Обязательных полей всего два: name (до 64 символов, только строчные буквы, цифры и дефисы) и description (до 1024 символов). Всё остальное — твой текст на Markdown, написанный обычными словами.

Если рядом нужны файлы — шаблон письма, скрипт, справочник, — их кладут в подпапки scripts/, references/, assets/. Агент откроет их, когда дойдёт до дела.

Почему это дёшево: агент читает по частям

Вот главная хитрость. Агент не держит весь навык в контексте. Загрузка идёт тремя ступенями:

• Ступень 1. При старте он видит только name и description — буквально строчку на навык. Это как оглавление книги.
• Ступень 2. Задача совпала с описанием — он читает тело SKILL.md целиком.
• Ступень 3. Инструкция ссылается на файл из references/ — он открывает и его.

Такой приём называют прогрессивным раскрытием. Практический вывод: двадцать навыков в проекте почти не съедают контекст, пока лежат без дела. Ты можешь держать их сколько угодно — платишь только за тот, что сработал.

Описание важнее самой инструкции

Начинающие пишут отличную инструкцию и халтурное описание — и навык не срабатывает никогда.

Потому что description — единственное, что агент видит заранее. Это не заголовок для людей, это условие срабатывания. В нём должно быть что делает и когда применять.

• Плохо: description: Работа с релизами
• Хорошо: description: Проверить релиз перед выкаткой. Использовать, когда просят собрать релиз, выпустить версию или подготовить сборку.

Второй вариант содержит слова, которыми ты реально просишь: «собери релиз», «выпусти версию». Агент сопоставляет твою фразу с описанием — и вспоминает про навык. Логика та же, что в хорошем промпте: конкретика бьёт общие слова.

Зачем это тебе, а не большой компании

Ты, скорее всего, уже объяснял агенту одно и то же по третьему разу: «у нас компоненты вот в этой папке», «коммиты пиши по-английски», «перед пушем прогони линтер». Каждую новую сессию — заново.

Навык превращает это объяснение в файл. Один раз написал — работает всегда, во всех сессиях, у всех в команде, потому что лежит прямо в репозитории рядом с кодом.

И ещё: формат открытый. Спецификация Agent Skills опубликована как стандарт (agentskills.io), его поддерживает не только Claude Code — например, Microsoft Agent Framework работает с теми же SKILL.md. Написанный тобой навык переезжает в другой инструмент без переписывания.

Готов сделать свой? Собери его по шагам в статье как написать навык агента — там полный проход от пустой папки до первого срабатывания.

Чем навык отличается от системного промпта?

Системный промпт грузится всегда и целиком — он задаёт общее поведение агента. Навык лежит на полке и подтягивается только под конкретную задачу. Грубо: системный промпт — это характер, навык — методичка.

Навык может запускать код?

Сам по себе — нет, это просто текст. Но в папке рядом могут лежать скрипты, и инструкция может велеть агенту их запустить. Тогда код выполняет агент своими инструментами — с теми же правами и ограничениями, что и обычно.

Сколько навыков — это много?

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