Как создать скилл для Клода и куда его установить

Свой скилл — это папка с текстовым файлом, и первый рабочий вариант собирается за полчаса. Разбираем структуру, установку и то, из-за чего скиллы чаще всего не подхватываются.

Короткий ответ

Нужны два шага: создать папку с файлом SKILL.md и положить её туда, где Клод её увидит. Никакого кода, никакой сборки — обычный текст в разметке Markdown.

Дальше агент сам решает, когда скилл применить: он читает описания всех доступных скиллов и подключает подходящий.

1. Собрать папку

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

otchet-po-prodazham/
  SKILL.md

Если нужны шаблоны, справочники или скрипты — кладите рядом:

otchet-po-prodazham/
  SKILL.md
  shablon-otcheta.md
  scripts/
    svesti-tablicy.py

2. Написать заголовок файла

В начале SKILL.md — блок с названием и описанием:

---
name: otchet-po-prodazham
description: Собирает недельный отчёт по продажам из выгрузки в наш формат. Использовать, когда просят подготовить отчёт, свести данные из таблицы продаж, посчитать итоги за неделю или сравнить менеджеров. Не для прогнозов и не для отчётов по марже.
---

Обязательных полей ровно два. name — только строчные латинские буквы, цифры и дефис, до 64 символов, и он обязан совпадать с именем папки. description — до 1024 символов.

Остальные поля необязательные, но два из них стоит знать:

Поле	Зачем
metadata	произвольные пары ключ-значение; сюда кладут version и автора
license	лицензия, если скилл выкладывается наружу
compatibility	требования к среде: «нужен git и доступ в интернет»
allowed-tools	заранее разрешённые инструменты; в чужом скилле читать в первую очередь

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

Плохое описание: «помогает с отчётами». Непонятно, с какими и когда.

Хорошее описание делает три вещи, и все три видны в примере выше:

1. Называет задачу — что скилл вообще делает.
2. Перечисляет формулировки, при которых он нужен, — теми словами, которыми вы реально ставите задачу. Чем больше синонимов, тем выше шанс срабатывания.
3. Очерчивает границу — где скилл не применяется. Это важно, когда скиллов несколько: без границы два похожих описания начинают перетягивать задачи друг у друга.

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

3. Написать тело скилла

Дальше — обычный текст. Работает такая структура:

## Что делаем

Собираем недельный отчёт по продажам из выгрузки CRM.

## Порядок

1. Проверить, что в выгрузке есть колонки: дата, менеджер, сумма, статус.
2. Отфильтровать отменённые сделки.
3. Сгруппировать по менеджерам, посчитать сумму и количество.
4. Оформить по шаблону shablon-otcheta.md.

## Правила

- Суммы округляем до рублей, разряды разделяем пробелом.
- Менеджеров сортируем по сумме, а не по алфавиту.
- Если данных за неделю нет — так и пишем, а не показываем нули.

## Чего не делать

- Не додумывать пропущенные значения.
- Не менять формулировки в шапке отчёта.

Раздел «чего не делать» недооценивают, а он экономит больше всего времени: агент склонен добавлять от себя, и явный запрет работает лучше просьбы.

4. Вынести детали в справочники

Шаг, который пропускают, а потом удивляются, почему агент стал медленнее и глупее.

Скиллы загружаются в три приёма, и у каждого своя цена:

Что грузится	Когда	Сколько стоит
name и description	всегда, для всех скиллов	около 100 токенов на скилл
тело SKILL.md	когда скилл сработал	рекомендуется до 5 000 токенов
файлы из references/	когда агент до них дошёл	сколько понадобится

Отсюда практическое правило из спецификации: SKILL.md держим короче 500 строк, а всё, что нужно не всегда, выносим в references/ и ссылаемся оттуда:

otchet-po-prodazham/
  SKILL.md
  references/
    formuly.md
    slovar-statusov.md

В теле скилла — обычная ссылка: «Расшифровка статусов — в references/slovar-statusov.md». Агент откроет файл, если дойдёт до статусов, и не потратит на него контекст, если не дойдёт.

Ссылки держат на один уровень: файл из references/, который ссылается на другой файл, который ссылается на третий, агент чаще всего не дочитывает.

ПолезноНаличие references/ — заодно хороший признак при выборе чужого скилла: значит, автор думал о контексте, а не писал в одну простыню.

5. Установить и проверить

Папку нужно положить туда, где агент её ищет, — и это разные места для приложения и для Claude Code. Все четыре способа с точными путями разобраны в инструкции по установке; самое короткое — положить папку в ~/.claude/skills/.

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

Дальше не полагайтесь на то, что файл лежит правильно, — проверьте на деле.

1. Спросите, какие скиллы доступны (в Claude Code — команда /skills).
2. Дайте задачу словами из описания — той самой строки, которая определяет срабатывание.
3. Посмотрите, применились ли ваши правила. Если агент сделал по-своему — скилл не подключился либо описание не совпало с формулировкой задачи.

6. Собрать проверочные сценарии

То, что отличает скилл, который работает у вас, от скилла, который работает вообще.

Заведите рядом со скиллом простой файл со сценариями: формулировка задачи и список того, что агент обязан сделать в ответ. В открытых наборах это обычно папка evals/ — в маркетинговой библиотеке coreyhaines31/marketingskills таких сценариев 340 на 50 скиллов.

Выглядит это как обычный список:

## Сценарий 2

Запрос: «посчитай, кто из менеджеров сколько закрыл за прошлую неделю»

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

Сценариев хватает трёх-пяти, и главное в них — разные формулировки одной задачи. Именно они ловят самую частую поломку: скилл срабатывает на ваши слова и молчит на слова коллеги.

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

Почему скилл не срабатывает

Пять причин по частоте:

1. Размытое описание. «Помогает с текстами» не срабатывает никогда, потому что не содержит условия. Опишите ситуацию, в которой скилл нужен.

2. Скилл лежит не там. Приложение и Claude Code читают скиллы из разных мест. Положили в одно — проверяете в другом.

3. Задача сформулирована другими словами. Описание говорит «недельный отчёт», вы просите «сводку за семь дней». Добавьте синонимы прямо в описание.

4. Скиллов слишком много и они пересекаются. Два скилла с похожими описаниями — агент выберет не тот. Разводите по условиям срабатывания.

5. Инструкция противоречива. В одном месте «пиши коротко», в другом развёрнутый пример на страницу. Агент следует примеру, а не декларации.

Как писать, чтобы работало

• Примеры сильнее правил. Один разобранный случай «было — стало» заменяет абзац объяснений.
• Конкретика вместо оценок. Не «пиши хорошо», а «абзац не длиннее четырёх строк, без вводных слов».
• Порядок шагов явно. Нумерованный список выполняется точнее, чем описание в прозе.
• Одна задача — один скилл. Универсальный скилл на всё срабатывает невпопад.
• Дописывайте по факту. Первая версия всегда неполная; правила добавляются, когда агент ошибся.

Когда скиллов становится больше трёх

Один скилл ведут как файл. Набор ведут как продукт, и появляются три вещи, которых у одного скилла нет.

Версия в заголовке. Поле version внутри metadata ничего не делает автоматически — ни одна программа его не читает. Оно нужно вам: без него через полгода не вспомнить, правленая у вас версия или та, что скачали.

---
name: otchet-po-prodazham
description: …
metadata:
  version: 1.3.0
---

Список версий одним файлом. Таблица «скилл — версия — дата» рядом с набором. В открытых наборах это VERSIONS.md, и смысл у неё один: увидеть, что изменилось с момента вашей установки, не читая диффы.

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

В Claude Code разросшийся набор проверяют командой /skill-doctor — она показывает, сколько контекста стоит каждый скилл и какие ни разу не сработали. Скилл, который не срабатывал ни разу, либо не нужен, либо у него плохое описание, и третьего обычно не дано.

Готовые скиллы как основа

Быстрее, чем писать с нуля: взять близкий готовый и переделать под себя. Где искать — в обзоре источников.

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

Если нужно не знание, а доступ

Скилл объясняет, как делать. Если агент не может дотянуться до нужных данных — это другая задача, и решается она через MCP: как создать свой MCP-сервер.

Аналог скиллов у OpenClaw — навыки, и там своя механика: создание собственных навыков.

Коротко о главном

• Папка, файл SKILL.md, два обязательных поля — name (совпадает с именем папки) и description. Этого достаточно для рабочего скилла.
• Описание решает всё. Оно должно называть задачу, перечислять формулировки, при которых скилл нужен, и очерчивать границу, где он не нужен. Лимит — 1024 символа, и его стоит использовать.
• Детали выносите в references/: тело SKILL.md грузится целиком при каждом срабатывании, справочники — только когда понадобились.
• Три-пять проверочных сценариев с разными формулировками одной задачи ловят главную поломку: скилл срабатывает на ваши слова и молчит на слова коллеги.
• Основное время уходит не на структуру, а на формулировку правил, и она уточняется по ходу.

Начните с задачи, которую объясняете чаще всего, — что такое скиллы и когда они нужны. Аналог у OpenClaw — создание собственных навыков, там механика другая.