Как написать skill для Claude Code, чтобы он реально работал

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

Anthropic выпустила отдельное руководство по написанию скиллов с конкретными правилами, а не общими советами. Ниже то, что в нём реально можно применить к уже установленным у Вас скиллам.

Минимальный скилл: куда класть и что внутри

Скилл это папка с файлом SKILL.md внутри. Для Claude Code путь такой: .claude/skills/<название-скилла>/SKILL.md в проекте или ~/.claude/skills/<название-скилла>/SKILL.md для личных скиллов на все проекты. Минимальный рабочий файл выглядит так:

---
name: extracting-pdf-text
description: Извлекает текст и таблицы из PDF-файлов. Используй при работе с PDF, формами или извлечением текста из документа.
---

# Извлечение текста из PDF

Используй pdfplumber:

import pdfplumber

with pdfplumber.open("file.pdf") as pdf:

text = pdf.pages[0].extract_text()

Дальше можно добавлять отдельные файлы (reference.md, examples.md), на которые SKILL.md ссылается, но для старта хватает этого.

Главный принцип: контекст общий, не бесплатный

При старте сессии загружаются только name и description всех скиллов. Сам SKILL.md читается, только когда скилл стал релевантен задаче. Но после того как он загрузился, каждый его токен конкурирует за место с историей разговора и остальным контекстом.

Отсюда правило: добавлять в скилл только то, что Claude не знает сам. Перед каждым абзацем в SKILL.md полезно спросить себя, оправдывает ли он свою цену в токенах, или это объяснение того, что модель и так понимает.

Лимиты, которые легко нарушить не заметив

У полей name и description в YAML-шапке SKILL.md жёсткие ограничения:

• - name: максимум 64 символа, только латиница в нижнем регистре, цифры и дефисы. Руководство Anthropic отдельно просит не использовать в имени слова "anthropic" и "claude": это требование для скиллов, которые загружаются через API или claude.ai. Для локальных скиллов именно в Claude Code жёсткого запрета нет, зарезервированы только конкретные имена папок synced и anthropic-skills, но тем же нейтральным именам стоит следовать и здесь, чтобы не путать свои скиллы с системными.
• - description: максимум 1024 символа, поле не может быть пустым.
• - Тело самого SKILL.md рекомендуется держать до 500 строк, остальное выносить в отдельные файлы.
• - Файлы, на которые ссылается SKILL.md, должны лежать на один уровень вложенности от него. Если один файл ссылается на другой, а тот на третий, Claude может прочитать такую цепочку частично, командой вроде head -100, и упустить часть информации.

Описание решает, выберут ли скилл вообще

У Claude может быть одновременно загружено больше ста скиллов, и description это единственное, по чему он выбирает нужный. Раз пишется от третьего лица: не "я помогу с Excel" и не "Вы можете использовать это для Excel", а "анализирует Excel-таблицы, строит сводные таблицы и графики". Непоследовательное лицо в описании само по себе мешает Claude правильно выбрать скилл.

Хорошее описание называет и что делает скилл, и когда его применять, с конкретными словами-триггерами. "Помогает с документами" или "обрабатывает данные" это не описание, это заглушка: Claude не понимает, в какой момент скилл нужен.

Частые ошибки, которые встречаются в уже работающих скиллах

Слишком много вариантов в инструкции. Фраза вида "можно использовать библиотеку A, или B, или C, или..." заставляет Claude угадывать. Лучше назвать один инструмент по умолчанию и отдельно обозначить, когда брать запасной вариант.

Время в тексте. Формулировки вида "до августа 2025 года используйте старый способ, после новый" устаревают сами по себе. Руководство рекомендует держать устаревшие варианты в отдельном свёрнутом блоке "старые паттерны", а не в основном потоке инструкции.

Непоследовательная терминология. Если в одном месте скилла написано "API endpoint", а в другом про то же самое "URL" или "маршрут", Claude тратит часть внимания на то, чтобы понять, что это один и тот же объект.

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

Чек-лист перед тем, как делиться скиллом

Из руководства можно вытащить короткий список, который реально проверяется за несколько минут:

• - описание называет и что делает скилл, и когда его применять;
• - тело SKILL.md меньше 500 строк;
• - нет завязки на конкретные даты;
• - термины одни и те же от начала до конца;
• - ссылки на файлы идут напрямую из SKILL.md, не цепочкой;
• - примеры конкретные, не абстрактные описания.

Я прогнала этот список по своим 37 скиллам в заводе контента. Девять из них, все на Three.js, оказались за пределами рекомендованных 500 строк, от 520 до 660 строк в теле SKILL.md. Остальные тридцать по длине в норме. Ни один из моих скиллов не превысил лимит описания в 1024 символа, но у одного описание заняло 997 символов, это уже впритык, и я взяла его в план на сокращение.

Если скилл написан давно и никто его не пересматривал, пройтись по этому списку один раз стоит того: часть проблем из этого руководства невидима на глаз, пока не читаешь описание конкретно под эти критерии.

Итог

Скилл, который выглядит правильным, может молча терять часть своей пользы из-за превышенного лимита описания, слишком глубокой вложенности файлов или описания от первого лица вместо третьего. Руководство Anthropic даёт не общие принципы, а проверяемые цифры: 64 символа на имя, 1024 на описание, 500 строк на тело, один уровень вложенности для ссылок.

Про рабочие связки скиллов и агентов для контента и автоматизации пишу в канале «Растём с ИИ». Разбор смежной темы: 5 MCP-серверов для Claude Code.

Если нужно разобрать свою систему скиллов и агентов лично, можно начать с бесплатной консультации.