Skills: как надеть на агента готовое умение

Есть просьба, которую вы повторяете: посмотри изменения, проверь эти файлы, оформи вот так, а сюда не лезь. Каждый раз вы объясняете процедуру заново и немного иначе.

Результат гуляет вместе с формулировкой. Сегодня вышло отлично, завтра вы забыли половину условий, и агент честно сделал то, что услышал.

Лечится это не памятью агента, а папкой с инструкцией. Skill - это записанная один раз процедура, которую Claude Code может подключить сам или по вашей команде. Разберём, где эта папка лежит, как убедиться, что skill встал, и что проверить до первого запуска.

Что такое skill

Прежде чем разбирать файлы и поля, поймаем интуицию.

Представьте столяра. Он один раз записал привычный порядок работы, подготовил памятки, шаблоны и программу для станка. Теперь коротко: "убери всё, заточи сверло, дальше стул для кота - запусти ЧПУ-шаблон". Запустил - и погнали.

Записанная процедура держит всю работу вместе:

• Наводит порядок по вашим правилам. Убирает верстак, раскладывает инструмент - каждый раз одинаково, ровно как вы привыкли.
• Следует записанным границам. Пила ещё крутится - не лезет. Безопасную часть работы делает сразу, без лишних вопросов.
• Заглядывает в памятки, когда нужно. Надо наточить сверло - открыл правило по заточке. Не держит его в голове заранее, достаёт по месту.
• Держит шаблоны под разные работы. Перешли со стола на стулья - берёт готовую схему подготовки.
• Запускает сложное одной командой. Программа повторяемых распилов уже лежит рядом. Достаточно сказать: "найди шаблон Стул для кота и пусти на ЧПУ" - станок соблюдёт зазоры и порядок операций.

Skill устроен так же. Это не ещё один инструмент в руках агента, а упакованная процедура. Основная инструкция хранит порядок и границы, справочники дают детали по месту, шаблоны держат заготовки, а скрипты запускают повторяемую механику. Один раз описали - дальше просто вызывается.

Сам формат skill ничего не изолирует. Инструкция может ограничить работу оформлением, но технической стены между CSS и логикой нет. Хороший skill явно называет область работы; после запуска вы смотрите изменённые файлы и проверяете поведение страницы. "Работает" и "выглядит" - разные слои, а гарантию даёт проверка, не формат.

Где живёт skill

Никакой магии в облаке здесь нет. Skill - это папка на диске, в вашем же проекте:

.claude/skills/web-design/SKILL.md

Путь разбирается по сегментам: служебная папка .claude, внутри неё skills, внутри - папка самого skill (имя придумываете вы), а в ней файл SKILL.md. Обычный текстовый файл, открывается чем угодно.

Для skill в проекте и домашней папке имя каталога становится именем команды со слэшем. Так что придумывайте его сразу с прицелом на то, как оно будет выглядеть в чате.

Теперь поправка к самой частой картинке в голове: skill это не один файл, а папка. Рядом с SKILL.md может лежать что угодно.

.claude/
└── skills/
    └── web-design/
        ├── SKILL.md      # главный файл: описание и инструкция
        ├── palettes.md   # справочник, агент откроет его, если понадобится
        └── scripts/
            └── check.py  # скрипт, который можно запустить

Для автоматического выбора агенту доступны имя и короткое описание skill, а не всё тело. SKILL.md загружается при запуске, соседние справочники - по необходимости. Поэтому длинная памятка не заполняет контекст заранее.

Для обычной локальной работы важны три источника skills:

Значок ~ означает домашнюю папку пользователя. В командах его оставляют как есть; если открываете папку вручную, переходите в свой домашний каталог.

Разница между первыми двумя местами простая, и разобраться с ней стоит сразу.

Положили папку в проект - skill работает только в этом проекте. Открыли соседний, а там его нет.

Skill в домашней папке доступен во всех проектах. Это удобно для общей процедуры, но она может включиться там, где вы её не ждали. Универсальное кладут домой, проектное оставляют в проекте.

Если Claude Code запущен с отдельным учебным профилем ~/.claude-javarush/, личные skills лежат в его папке skills/. Проектный путь .claude/skills/ от профиля не меняется.

Description решает, когда skill сработает

Типичная история: папку положили, файл на месте, а агент ведёт себя ровно как раньше. Ничего не сломано - просто он не понял, что этот skill сюда подходит.

Посмотрите, что у агента есть на руках в момент выбора. Тело самого skill он ещё не читал: загружен только список имён и описаний. Значит, решение принимается по описанию, и больше не по чему.

Соберём минимальный skill для проекта от начала до конца. Имя у него web-design - так называется папка, и отсюда же берётся команда /web-design. В самом файле имя не пишут, папка его уже задала:

.claude/skills/web-design/SKILL.md

А внутри вот что, и больше ничего не нужно:

---
description: Приводит веб-интерфейс в порядок - современный CSS, плавные переходы,
  согласованная палитра. Применять, когда просят сделать красиво или стильно.
---

# Веб-дизайн

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

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

Хорошее описание отвечает на два вопроса: что skill делает и когда его брать. Причём теми словами, которыми вы реально пишете запросы.

# молчит: непонятно, когда применять
description: Помогает с оформлением

# срабатывает: сказано и что делает, и когда
description: Приводит интерфейс в порядок - CSS, типографика, палитра.
  Применять, когда просят сделать красиво, стильно или поправить вёрстку.

Описание отвечает за то, когда skill поднимется сам. Но это не единственный вход: у skill есть имя, и по нему его можно позвать вручную. Набрали /web-design - и описание вообще ни при чём, файл читается и выполняется.

В готовых skills часто встречается поле name. У skills в проекте и домашней папке это подпись в списке, команду по-прежнему задаёт каталог. В плагине name может задать последнюю часть команды после имени плагина.

Путей запуска, стало быть, два, а всё, что после них, одинаково.

Левая ветка - автоматическая: запрос совпал с описанием, агент взял skill. Правая - ручная: набрали /web-design, и skill запустился независимо от описания.

Skills попадают в то же меню по /, что и встроенные команды. Файл .claude/commands/deploy.md и skill .claude/skills/deploy/SKILL.md создают одну команду /deploy; если лежат оба, выигрывает skill.

Поставить и проверить

Папку положили. Как понять, что агент её увидел, а не просто файл лежит на диске?

/skills

Команда открывает список skills и показывает их источник. Наберите пару букв - список отфильтруется. Нашли имя своей папки и состояние on - Claude Code видит skill и разрешает его запуск.

Имя, источник и состояние on подтверждают, что skill доступен

Обычно Claude Code подхватывает новый или изменённый SKILL.md на лету. Если имени в списке нет, перебирайте по порядку:

Skill есть в списке, но не включается сам? Перезагрузка тут ни при чём. Проверьте description и поле disable-model-invocation: true - оно оставляет только ручной запуск. Переформулируйте просьбу или вызовите skill по имени. Ручной вызов работает - значит, установка исправна.

Что проверить до того, как доверять

Тут придётся сбавить восторг. Skill это не тема оформления и не картинка, которую можно поставить и снять. Это инструкции, которые ваш агент выполнит в вашем проекте.

Проверять надо не только главный файл, а всю папку. Начните с четырёх вещей:

• описание - совпадает ли оно с тем, чего вы от skill ждёте, и не срабатывает ли слишком широко;
• тело и ссылки из него - что skill велит делать и какие соседние файлы просит открыть;
• папка scripts/, если она есть, - какие команды там запускаются, какие файлы и сетевые адреса они трогают;
• поле allowed-tools - какие инструменты skill заранее разрешает использовать без отдельного вопроса.

---
name: pre-commit-style
description: Приводит проект к общему стилю перед коммитом
allowed-tools: Read, Write, Edit, Glob
---

Здесь allowed-tools не описывает план работы и не ограничивает полный набор возможностей агента. Поле только предодобряет перечисленные инструменты на тот ход, в котором вызван skill. Имена расшифровываются просто:

• Read - читать файлы;
• Write - создавать новые файлы и перезаписывать существующие целиком;
• Edit - вносить правки внутрь существующего файла;
• Glob - искать файлы по маске, то есть ходить по проекту и смотреть, что в нём вообще есть.

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

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

И последнее, менее страшное, но куда более частое. Skill направляет агента, а не гарантирует результат. После запуска посмотрите изменённые файлы и проверьте результат: оформительский skill может сделать страницу красивее, но работоспособность кнопки за него никто не подтвердит.

Где брать готовые

Писать SKILL.md с нуля, чтобы попробовать, совсем не обязательно. Чаще всего готовые skills находят в открытых репозиториях или получают вместе с плагинами.

Самый короткий путь - попросить агента найти подходящий вариант, но не устанавливать его вслепую. Формулировка может быть такой:

Найди skill для оформления интерфейсов. Покажи источник, SKILL.md и скрипты,
объясни, какие файлы и инструменты он использует. До моего подтверждения
ничего не устанавливай.

Посмотрели источник и содержимое - тогда просите положить папку в .claude/skills/ проекта и проверяйте результат через /skills.

Для самостоятельного поиска подойдёт запрос Claude skills marketplace. Каталог помогает найти варианты, но не служит знаком безопасности: содержимое всё равно читают до установки.

SKILL.md следует открытому стандарту Agent Skills, поэтому базовая структура переносится между разными агентами. Но Claude Code добавляет собственные поля и способы запуска. Перенесли skill в другой инструмент - проверьте, какие возможности он там действительно поддерживает.

Свой skill можно собрать с агентом

Момент, когда пора заводить свой skill, узнаётся без всякой теории: одну и ту же процедуру вы объясняете третий раз. Не задачу, а именно порядок действий - посмотри то, проверь это, оформи вот так, сюда не лезь. Повторяется - значит, созрела.

И тут хорошая новость. Писать SKILL.md с пустого листа не обязательно. Агент может собрать черновик, а от вас требуется объяснить, что за процедура и чего вы от неё хотите. Выглядит это как обычный разговор:

Сделай skill для подготовки коммита. Он должен смотреть, что изменилось,
проверять, не попали ли в коммит лишние файлы, и писать сообщение
по нашему шаблону. Запускать буду руками, когда сам захочу.
Если требований не хватает, сначала задай вопросы.

Заметьте, ни одного поля вы не назвали и в устройство файла не полезли. Требования сказаны словами, перевести их в поля - работа агента.

Если данных не хватает, агент задаст вопросы. Без такой просьбы он может сразу сделать допущения, поэтому нужная строка уже есть в примере. Получив черновик, проверьте файлы, найдите skill через /skills и сделайте пробный запуск.

Если процедуру можно пройти руками, сделайте это вместе с агентом до упаковки. Один коммит по шагам покажет, где его пришлось поправить и чего не хватило в объяснении. Skill по живому прогону точнее, чем по воспоминаниям.

Когда SKILL.md разрастается

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

Складывать всё в одно место не надо, и причина уже называлась выше: тело грузится целиком, как только skill пошёл в дело. Четыре экрана справочника уедут в работу и в тот раз, когда из них понадобилась одна строка.

Поэтому детали выносят в соседние файлы, а в SKILL.md оставляют отсылку: если такая-то ситуация - открой такой-то файл. Папку с palettes.md и scripts/ вы уже видели, вот как она выглядит изнутри:

## Справочники

- Палитры и сочетания цветов - в [palettes.md](palettes.md)
- Готовые примеры разметки - в [examples.md](examples.md)
- Проверить контрастность: запусти scripts/check.py

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

Раскладывать удобно по назначению:

• SKILL.md - сама процедура: что делать, в каком порядке, чего не делать. До вызова агент видит её описание, а тело загружает при запуске;
• справочники - таблицы, правила, длинные примеры, всё, что нужно не в каждом запуске;
• scripts/ - то, что проще выполнить, чем описать словами. В чужом skill эти файлы проверяют до запуска;
• шаблоны - файлы, которые skill берёт за основу и правит под задачу.

Отсюда же обратный вывод, уже про чужие skills. Короткий SKILL.md не означает "простой skill". Загляните, что лежит в папке рядом с ним.

Что это меняет в работе

Если собрать всё в несколько строк:

• повторяемая просьба превращается в папку. Один раз описали порядок работы - дальше он воспроизводится одинаково, в любой сессии и в любой день;
• свой skill можно не писать с пустого листа. Объясняете процедуру словами, просите уточнить недостающее и проверяете собранный черновик;
• при автоматическом запуске skill выбирается по description, при ручном - по имени со слэшем. Если он молчит, сначала выясните, виден ли он в списке и разрешён ли автозапуск;
• /skills отвечает на вопрос "он вообще встал". Полминуты проверки экономят полчаса догадок;
• чужой skill читается до установки и запуска, вместе со связанными файлами и скриптами;
• skill меняет то, как агент делает работу, но не изолирует область правок и не отменяет проверку результата.