Что понадобится
- Установленный Claude Code. Проверяется командой
claude --version- всё ниже я прогнал на версии 2.1.259. - Терминал - тот, что уже есть в системе.
- Любой текстовый редактор. Первый рабочий скилл - это одна папка и один файл.
Если само слово пока не оформилось - короткое объяснение в словаре. Про сам инструмент - что такое Claude Code.
Главное, что надо понять до первой команды
Скилл - это папка, а в ней файл SKILL.md. Больше ничего обязательного нет.
Сам файл состоит из двух частей: шапка между строчками из трёх дефисов и обычный текст под ней.
---
name: otchyot-po-dnyu
description: Собирает отчёт за день из моих заметок. Звать, когда прошу подвести итоги дня.
---
## Что делать
1. Прочитать заметки за сегодня.
2. Собрать три пункта: сделано, застряло, на завтра.
3. Показать списком, без вступления.А теперь то, из-за чего люди чаще всего мажут. Агент не читает твой скилл целиком. В контекст каждой сессии попадает только строчка description - список в духе «что у меня вообще есть под рукой». Тело файла подгружается в тот момент, когда агент решил, что скилл подходит под задачу, или когда ты позвал его руками.
Это видно цифрами. Команда claude plugin details принимает имя установленного плагина - вот её ответ для плагина, внутри которого лежит один скилл:
claude plugin details frontend-design
Component inventory
Skills (1) frontend-design
Projected token cost
Always-on: ~78 tok added to every session
Per-component (rounded)
component always-on on-invoke
frontend-design ~80 ~2.7kМеньше сотни токенов висят всегда, две с лишним тысячи приезжают только при срабатывании. У своего скилла, который лежит просто папкой, эта команда цифр не покажет - она работает по имени плагина, - но устроено там ровно так же. Отсюда весь практический вывод: описание важнее инструкции. Плохо описанный скилл не сработает никогда, каким бы толковым ни было тело.
Шаг 1. Найти папку скиллов {#shag-1}
Мест три, и разница между ними только в том, кто скилл увидит:
| Куда положил | Путь | Кто видит |
|---|---|---|
| себе | ~/.claude/skills/имя/SKILL.md |
все твои проекты |
| в проект | .claude/skills/имя/SKILL.md |
только этот проект |
| в плагин | плагин/skills/имя/SKILL.md |
там, где плагин включён |
Начинай с первого, он общий:
mkdir -p ~/.claude/skills/otchyot-po-dnyuИмя папки пиши латиницей через дефис. Это не косметика: имя папки становится командой. Папка otchyot-po-dnyu даст команду /otchyot-po-dnyu. Поле name в шапке на это не влияет - я специально прописал в файле одно имя, а папку назвал другим, и агент показал имя папки.
Ещё две вещи про расположение, которые экономят вечер:
- Проектные скиллы подхватываются не только из папки, где ты запустил агента, но и из всех папок выше - до корня репозитория. Запустился в подпапке - скиллы из корня всё равно приедут.
- При совпадении имён личный скилл перекрывает проектный. Скиллы из плагинов не конфликтуют ни с чем: они живут с приставкой,
плагин:скилл.
Шаг 2. Написать SKILL.md {#shag-2}
Открой в папке файл SKILL.md и положи туда шапку с описанием и текст инструкции.
Обязательных полей в шапке нет вообще. Рекомендуется одно - description. Всё остальное по желанию:
| Поле | Зачем |
|---|---|
description |
когда звать скилл. Единственное, что агент видит всегда |
when_to_use |
добавка к описанию: фразы-триггеры, примеры просьб |
allowed-tools |
какие инструменты доступны агенту, пока работает скилл |
disable-model-invocation |
true - агент не зовёт скилл сам, только ты слешем |
user-invocable |
false - наоборот, скрыть из меню, звать может только агент |
Про описание есть жёсткая рамка: description вместе с when_to_use обрезаются на 1536 символах в общем списке скиллов. То есть простыня в описании не просто бесполезна - её хвост физически не доедет.
Как писать описание, чтобы работало: не «что внутри», а «в какой ситуации меня звать», причём теми словами, которыми ты сам ставишь задачу. Сравни.
Плохо: description: Инструкция по сборке отчёта.
Хорошо: description: Собирает отчёт за день из заметок. Звать, когда прошу подвести итоги дня, спрашиваю «что я сегодня сделал» или прошу отчёт за вчера.
Тело - обычный текст. Пиши шагами, как объяснял бы человеку, который делает это первый раз. Рядом в папке можно держать что угодно: примеры, шаблоны, скрипты - агент дочитает их, когда понадобится.
Шаг 3. Проверить формат командой {#shag-3}
Не на глаз. У Claude Code для этого есть проверялка - ей скармливают папку, внутри которой лежит skills:
claude plugin validate ~/.claudeТак выглядит здоровый ответ:
Validating components in: /Users/имя/.claude
✔ Validation passedА так - когда в файле забыли описание:
⚠ Found 1 warning:
❯ description: No description in frontmatter. A description helps
users and Claude understand when to use this skill.
✔ Validation passed with warningsПоследняя строка важна: это предупреждение, а не ошибка, проверка всё равно проходит. Хочешь, чтобы предупреждения считались ошибками (например, в проверке перед коммитом) - добавь --strict.
Шаг 4. Убедиться, что агент его видит {#shag-4}
Проверка формата - это ещё не «агент подключил». Смотри с двух сторон.
Изнутри сессии набери:
/skillsТвоё имя должно быть в списке.
Снаружи, не открывая сессию:
claude -p "Есть ли у тебя скилл otchyot-po-dnyu? Ответь одним словом: ДА или НЕТ."Я так и проверял проектный скилл: положил папку в .claude/skills/, запустил эту команду в корне проекта и получил ДА. Способ хорош тем, что честный: отвечает не файловая система, а сам агент.
Шаг 5. Позвать и посмотреть, как срабатывает {#shag-5}
Два режима, проверять надо оба.
Руками - слеш и имя папки:
/otchyot-po-dnyuАгент должен сделать ровно то, что написано в теле. У меня в проверочном скилле было написано «ответь словом РАБОТАЕТ» - агент ответил РАБОТАЕТ.
Сам - сформулируй задачу словами из описания и ничего про скилл не говори. Подключился молча - описание попало в цель. Не подключился - переписывай описание, а не инструкцию.
Правки в SKILL.md подхватываются на лету, перезапускать сессию не надо. Исключение одно: если самой папки skills не было в момент старта сессии и ты создал её только что - сессию перезапусти, иначе агент за ней не следит.
Куда смотреть, если что-то не так
| Что видишь | Что это значит |
|---|---|
No frontmatter block found |
перед первой чертой из трёх дефисов есть пустая строка или пробел - шапка не читается вообще |
No description in frontmatter |
нет строки description, агент не поймёт, когда звать |
скилла нет в списке /skills |
папка не там, где ищет агент, либо папку skills ты создал уже после старта сессии |
| скилл в списке есть, но не срабатывает сам | описание не про повод позвать; допиши в него свои формулировки задачи |
| позвал слешем - «команда не найдена» | смотри на имя папки, а не на поле name: команда собирается из папки |
Отдельно про первую строку - на ней спотыкаются чаще всего. Шапка читается, только если три дефиса стоят самой первой строкой файла. Один перевод строки выше - и весь файл считается телом, а описания у скилла как бы нет. Проверялка это ловит, глаз - нет.
Пять ошибок, на которых теряют вечер
- Писать описание про содержание, а не про повод. «Инструкция по отчётам» агенту ничего не говорит. «Звать, когда прошу подвести итоги дня» - говорит.
- Пустая строка перед шапкой. Файл выглядит правильным, а описания у скилла нет. Лечится
claude plugin validate. - Называть папку по-русски или с пробелом. Имя папки становится командой - держи латиницу и дефисы.
- Ждать, что агент прочитает тело заранее. Он не прочитает. Всё, что должно влиять на решение звать или не звать, живёт в описании.
- Складывать в один скилл три задачи. Описание становится размытым, и агент не зовёт его нигде. Один скилл - одна работа.
Что дальше
- Что такое скилл - если нужно объяснить кому-то в двух абзацах.
- Скиллы в Codex - там то же самое устроено иначе: своей папки скиллов нет, они приезжают внутри плагинов.
- Что такое Claude Code и что такое агент - если пропустил базу.
- Каталог скиллов - готовые, с русским описанием и командой установки.
Дальше это обычно растёт само: один скилл на отчёты, второй на письма, третий на разбор выгрузки. Через месяц половина рабочих задач начинается с того, что агент молча подключает нужный. Всё, что я собрал для своих проектов, лежит в ClaudeBase - файлы кладутся в проект по инструкции, и агент читает их в работе.