Claude Skills и SKILL.md для разработчиков: VS Code, JetBrains, Cursor

Большинство команд неправильно используют Claude Skills одним из двух способов. Либо они превращают SKILL.md в свалку информации, либо так и не переходят от огромных скопированных промптов к чему-то более структурированному.

Оба подхода небрежны. Если вы хотите, чтобы Skills работали в реальном dev-процессе, их нужно рассматривать как код и операционную логику, а не как поэзию промптов.

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

Если вы также используете Hermes Agent, та же структура на диске соответствует спецификации в стиле agentskills, которую документирует Hermes — условная активация, сканирование хаба, а также различия между секретами и конфигурацией подробно описаны в Hermes Agent Skill Authoring — SKILL.md Structure and Best Practices.

Собственные рекомендации Anthropic довольно четко показывают предполагаемое разделение труда. CLAUDE.md предназначен для постоянного, всегда активного контекста проекта. Skills — для переиспользуемых знаний, плейбуков и вызываемых рабочих процессов, которые должны загружаться по требованию. Это делает Skills естественным местом для кодирования цикла разработки, управляемого спецификацией — спецификация, планирование, реализация, валидация — когда вам нужно больше структуры, чем в «вайб-кодинге», но меньше церемоний, чем в полном каркасе Spec Kit. Смотрите GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows, чтобы узнать, как скиллы Claude Code сравниваются с портативными и интегрированными в IDE альтернативами. Если вы предпочитаете установить этот цикл в готовом и принудительном виде, а не создавать его самостоятельно, Superpowers упаковывает именно такой набор скиллов — мозговой штурм, планирование, обзор сабагентами, TDD — в виде устанавливаемого плагина.

Claude Code даже интегрировал старые пользовательские команды в тот же механизм, поэтому устаревшие файлы .claude/commands/*.md по-прежнему работают, но Skills теперь представляют собой лучшую долгосрочную форму — и самый переиспользуемый строительный блок в любом AI-powered development workflow.

Когда использовать Claude Skills: CLAUDE.md vs Skills vs Hooks

Создание Claude Skill имеет смысл, если вы постоянно вставляете в чат один и тот же чек-лист, один и тот же плейбук развёртывания, один и тот же критерий ревью кода или одни и те же подводные камни внутреннего API. Anthropic явно рекомендует создавать скилл, если вы постоянно повторяете одну и ту же процедуру, или если раздел в CLAUDE.md вырос до уровня процесса, а не факта. Это практический ответ на вопрос из FAQ: «Что такое Claude Skill и когда его следует использовать». Используйте Skill для повторяемых процедур, а не для общего вкуса или широких правил репозитория.

Реальная выгода — контроль над стоимостью контекста и поведением. Хороший Skill загружается только тогда, когда это уместно, тогда как раздутый CLAUDE.md загружается в каждой сессии. Anthropic рекомендует держать CLAUDE.md коротким и переносить доменные знания или процедуры в Skills именно потому, что загрузка по требованию позволяет агенту оставаться сфокусированным на текущей задаче.

Моё субъективное правило просто. Если инструкция должна применяться в каждой сессии, она должна быть в CLAUDE.md. Если инструкция — это переиспользуемый метод, чек-лист или рабочий процесс, который важен только иногда, он должен быть в Skill. Если действие должно происходить автоматически при каждом подходящем событии, скорее всего, ему место в хуке, а не в Skill. Обзор функций Anthropic описывает эти инструменты почти точно в этой модели послойности.

Практический индикатор для каждого: если вы ловите себя на том, что вставляете одни и те же инструкции в каждый чат, это Skill. Если раздел CLAUDE.md вырос в пошаговый процесс, выделите его в Skill. Если вы хотите, чтобы что-то срабатывало молча каждый раз при сохранении файла, напишите хук. Есть и четвёртый слой, о котором стоит знать: когда задача генерирует много шумных промежуточных данных, которые вы не хотите видеть в основной сессии — исследование кодовой базы, большой запуск тестов — это задача для subagent, а не для Skill.

Поддержка Claude Skills в IDE: VS Code, JetBrains, Cursor и Codex

Claude Code работает в CLI, Desktop, VS Code, JetBrains, в вебе и в мобильных потоках удалённого управления. Anthropic описывает CLI как наиболее полную локальную поверхность, тогда как интеграции в IDE жертвуют некоторыми возможностями, доступными только в CLI, ради нативного для редактора ревью, контекста файлов и более удобной эргономики рабочего процесса. Конфигурация, память проекта и MCP-серверы разделяются между локальными поверхностями, поэтому ваша настройка .claude следует за вами, а не заперта в одном редакторе.

Для VS Code Anthropic говорит, что расширение — рекомендуемый интерфейс внутри редактора. Оно предоставляет ревью планов, инлайн-диффы, поддержку упоминания файлов и интегрированный доступ к CLI. Тот же процесс установки также открывает прямой путь для Cursor. Для JetBrains текущий список поддерживаемых IDE включает IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm и GoLand, с встроенными в плагин просмотром диффов, обменом выделением текста, горячими клавишами для ссылок на файлы и обменом диагностикой.

Поддержка JetBrains лучше, чем многие разработчики думают. Если вы запускаете claude из встроенного терминала IDE, функции интеграции активируются автоматически. Если вы начинаете из внешнего терминала, Anthropic документирует команду /ide для переподключения Claude Code к сессии JetBrains и явно рекомендует запускать из того же корня проекта, чтобы Claude видел те же файлы, что и ваша IDE. Если вы используете режимы авто-редактирования в JetBrains, Anthropic также предупреждает, что файлы конфигурации IDE могут стать частью редактируемой поверхности, поэтому ручное одобрение действий — более безопасный вариант в такой среде.

Теперь более крупная точка. Claude Skills — это не только дело Claude Code. Agent Skills — это открытый стандарт. Официальное быстрое начало Agent Skills говорит, что один и тот же скилл может работать в VS Code с GitHub Copilot, Claude Code и OpenAI Codex, а собственные документы OpenAI по Codex утверждают, что Skills доступны в Codex CLI, расширении IDE и приложении. Руководство по реализации Agent Skills добавляет важный нюанс портативности: .agents/skills утвердился как кросс-клиентское соглашение, хотя некоторые клиенты также сканируют .claude/skills ради прагматичной совместимости.

Так вот практическое правило совместимости, которое я рекомендую. Если вы строите только для Claude Code, создавайте скиллы в .claude/skills. Если вы действительно хотите кросс-клиентскую портативность, ориентируйтесь на открытый формат Agent Skills и используйте .agents/skills как канонический путь. Не делайте вид, что эти две цели идентичны. Они связаны, но не идентичны.

Краткая справка по совместимости:

Структура, расположение папок и места хранения файла SKILL.md

Правильный Skill — это папка, а не случайный markdown-файл, лежащий в корне репозитория. Базовая спецификация требует каталог с файлом SKILL.md и допускает необязательные каталоги scripts/, references/ и assets/. SKILL.md должен содержать YAML frontmatter, за которым следуют markdown-инструкции. В спецификации name и description обязательны, name ограничен 64 символами (строчные буквы, цифры и дефисы), compatibility предназначен только для реальных требований к среде, а allowed-tools явно экспериментален в разных реализациях.

Claude Code немного более лоялен к портативной спецификации, поскольку может выводить имя из каталога и использовать первый абзац как запасной вариант, если отсутствует description. Если вам важна портативность или предсказуемость, на это полагаться не стоит. Claude.ai требует, чтобы имя каталога совпадало с полем name, и его путь загрузки пользовательских скиллов ограничивает описания 200 символами, хотя более широкая спецификация позволяет гораздо больше. Портативный выбор — установить явное name, держать каталог идентичным и написать точное описание, которое укладывается в строгие лимиты. Это отвечает на тему FAQ «Что должно содержать файл SKILL.md» без уклончивых ответов.

Начните со структуры, скучной вот до чего:

repo/
  .claude/
    skills/
      review-pr/
        SKILL.md
        scripts/
          review.sh
        references/
          checklist.md
        assets/
          comment-template.md

Если портативность между клиентами, поддерживающими Skills, важнее, чем удобство Claude Code, сохраняйте ту же внутреннюю структуру, но замените .claude/skills/ на .agents/skills/. Структура папок — это одна и та же идея в любом случае.

Для Claude Code места хранения straightforward. Скиллы проекта находятся в .claude/skills/<skill-name>/SKILL.md. Личные скиллы находятся в ~/.claude/skills/<skill-name>/SKILL.md. Скиллы, распространяемые через плагины, находятся в <plugin>/skills/<skill-name>/SKILL.md. Anthropic документирует приоритет между встроенными областями видимости: enterprise выше personal, personal выше project, тогда как скиллы плагинов избегают конфликтов, используя именованный формат, например plugin-name:skill-name. На Windows ~/.claude резолвится в %USERPROFILE%\.claude, а CLAUDE_CONFIG_DIR может переместить весь базовый каталог.

Выбор между проектной и личной областью видимости straightforward. Используйте .claude/skills/ внутри репозитория, когда Skill тесно связан с этой кодовой базой — например, плейбук развёртывания, который знает ваши конкретные имена кластеров, или критерий ревью, настроенный на соглашения вашей команды. Используйте ~/.claude/skills/ для Скиллов, которые путешествуют с вами между проектами: личные чек-листы, универсальные генераторы changelog, предпочтительные рабочие процессы отладки. Всё, что вы бы положили в репозиторий dotfiles, принадлежит к личной области.

Несколько острых углов стоит запомнить. SKILL.md должен называться именно так, с учётом регистра. PDF-руководство Anthropic рекомендует kebab-case для имён папок и явно говорит не размещать README.md внутри папки скилла, потому что действующая документация должна жить в SKILL.md или references/. То же руководство подчёркивает, что имя SKILL.md чувствительно к регистру. Это скучные ограничения, но именно скучные ограничения делают инструменты надёжными.

Claude Code также делает правильную вещь для монорепозиториев. Он автоматически обнаруживает вложенные каталоги .claude/skills/, когда вы работаете внутри подкаталогов, что идеально для скиллов на уровне пакетов или сервисов. Он также отслеживает существующие каталоги скиллов на предмет живых изменений в текущей сессии. Единственная ловушка с перезапуском — создание верхнеуровневого каталога скиллов, которого не существовало на момент начала сессии. Anthropic документирует это как случай, когда вам действительно нужно перезапустить, чтобы новый каталог мог отслеживаться.

Лучшие практики Claude Skills: описания, скрипты и область видимости

Самый быстрый способ создать бесполезный Skill — попросить LLM выдумать его из общих обучающих знаний. Руководство по лучшим практикам Anthropic предупреждает именно об этом. Ценные части — это доменные исправления, граничные случаи, выбор инструментов и соглашения, которые модель не придумает надёжно сама. Правильный рабочий процесс — решить задачу один раз с агентом, исправить её, пока она не заработает, а затем извлечь метод в Skill.

Ограничивайте область Skill как хорошую функцию, а не как вики. Anthropic говорит, что Skills должны инкапсулировать согласованную единицу работы. Слишком узко — и вы заставляете стекать несколько скиллов для одной задачи. Слишком широко — и агент не может активировать их точно. Руководство по лучшим практикам прямо говорит, что чрезмерно всеобъемлющие скиллы могут навредить больше, чем помочь, потому что модель гонится за нерелевантными инструкциями и теряет сигнал.

Качество описания — это не косметический вопрос. Это слой маршрутизации. И Anthropic, и документы Agent Skills говорят, что поле description — это основной механизм, который модель использует, чтобы решить, загружать ли Skill вообще. Хорошие описания говорят, что делает Skill, когда его использовать и какие триггерные фразы или типы файлов пользователь действительно назовёт. Плохие описания размыты, чрезмерно технически сложны или настолько широки, что подходят к чему угодно. Это реальный ответ на вопрос из FAQ «Почему Claude Skill не срабатывает». Обычно виновата плохая маршрутизация, а не модель.

Контраст очевиден рядом:

Плохие описания — слишком размыты для надёжной маршрутизации:

• Helps with code review — подходит ко всему, ничего не различает
• Useful for development tasks — шире поискового запроса
• Assists with writing — не маршрутизатор, просто метка категории

Хорошие описания — специфический триггерный язык:

• Review pull requests for security issues, migration risk, and missing tests. Use when reviewing a PR, git diff, or release critical change.
• Generate a changelog from git log output. Use when preparing a release, writing release notes, or summarising commits since last tag.
• Scaffold a new Go HTTP handler with request validation and error middleware. Use when adding a new endpoint or route to a Go service.

Шаблон каждый раз один и тот же: заявите, что делает Skill, назовите точные фразы пользователя, которые должны его активировать, и при необходимости назовите типы файлов или инструменты, которые релевантны. Если ваше описание подошло бы к общему запросу в Google, оно недостаточно специфично.

Если рабочий процесс имеет побочные эффекты, сделайте его ручным. Claude Code предоставляет это напрямую. disable-model-invocation: true делает Skill доступным только для вызова пользователем, что Anthropic рекомендует для действий, таких как развёртывание, коммиты или исходящие сообщения. user-invocable: false делает обратное и скрывает Skill из слаг-меню, позволяя Claude использовать его как фоновые знания. Это отвечает на тему FAQ «Когда скилл должен быть ручным, а не автоматическим» одним предложением: ручное для риска, автоматическое для безопасных повторяемых руководств.

Держите SKILL.md достаточно маленьким, чтобы оставаться понятным. Anthropic рекомендует держать его меньше 500 строк и около 5 000 токенов, а затем переносить детальный материал в references/ или аналогичные файлы с явными инструкциями по загрузке. «Прочитай references/api-errors.md, если API возвращает не 200» — хороший паттерн. «Смотри references/» — лень. Claude Code также вставляет отрендеренный Skill в разговор как сообщение и не перечитывает файл повторно в последующих ходах. После компактизации контекста только недавний контент Skill передаётся вперёд в пределах бюджетов токенов. Поэтому огромные Skills — это не просто некрасиво. Они хрупки в длинных сессиях.

Хороший SKILL.md может оставаться очень простым:

---
name: review-pr
description: Review pull requests for security issues, migration risk, and missing tests. Use when reviewing a PR, git diff, or release critical change.
compatibility: Designed for Claude Code. Requires git and gh.
disable-model-invocation: true
allowed-tools: Bash(git diff *) Bash(gh pr diff *) Read Grep Glob
---
# Review PR

Read references/checklist.md before running any commands.

1. Collect the diff and changed files.
2. Flag correctness, security, and test coverage issues.
3. Return findings grouped by severity with file references.
4. Suggest the smallest safe fix first.

Используйте скрипты, когда детерминизм важнее красноречия. Руководство по скриптам Skills здесь отлично. Оно говорит, что скрипты для агентов должны избегать интерактивных подсказок, документировать использование через --help, выводить полезные сообщения об ошибках, предпочитать структурированный вывод, такой как JSON или CSV, в stdout, отправлять диагностику в stderr и поддерживать безопасное для повторных попыток использование. Оно также рекомендует фиксировать версии одноразовых инструментов и явно описывать требования к времени выполнения в SKILL.md или поле compatibility, а не предполагать, что в среде есть нужные пакеты.

Минимальный, но правильный скрипт для агента выглядит так:

#!/usr/bin/env bash
# scripts/collect-diff.sh — called by review-pr skill
# Usage: collect-diff.sh <base-ref> [<head-ref>]
set -euo pipefail

BASE="${1:?Usage: collect-diff.sh <base-ref> [<head-ref>]}"
HEAD="${2:-HEAD}"

# Structured output to stdout so the agent can parse it
git diff "${BASE}...${HEAD}" --stat --name-only \
  | jq -Rs '{
      "changed_files": split("\n") | map(select(length > 0))
    }' \
  || { printf '{"error":"git diff failed"}\n' >&2; exit 1; }

Три вещи делают это безопасным для агента. set -euo pipefail обеспечивает громкий выход скрипта при любой ошибке, а не тихое продолжение. JSON в stdout даёт агенту формат, который он может разобрать без догадок. Диагностика уходит в stderr, чтобы поток stdout агента оставался чистым. Ничего из этого не хитро. Всё это необходимо.

Одна тонкая ловушка — allowed-tools. В спецификации он экспериментален, и поддержка варьируется. В Claude Code он предварительно одобряет конкретные инструменты, пока Skill активен, но не ограничивает вселенную вызываемых инструментов, и правила запрета по-прежнему принадлежат разрешениям Claude Code. В Claude Agent SDK Anthropic явно говорит, что frontmatter allowed-tools в SKILL.md не применяется, поэтому приложения на SDK должны применять доступ к инструментам в основной конфигурации allowed_tools или allowedTools. Если вы проигнорируете это различие, ваш Skill будет вести себя по-разному в CLI и в автоматизации на базе SDK.

Ещё один продвинутый паттерн стоит украсть. Когда рабочий процесс затопит ваш основной поток логами, поиском файлов или длинным исследовательским выводом, Claude Code позволяет запускать Skill в форкнутом сабагенте, используя context: fork и агента, такого как Explore. Anthropic показывает это для исследовательских рабочих процессов, где тяжёлая работа происходит в изолированном контексте, а основной разговор получает резюме. Для глубокого исследования кодовой базы это гораздо лучший дизайн, чем огромный инлайн-Skill, загрязняющий основную сессию.

Форкнутый Skill выглядит так во frontmatter:

---
name: explore-codebase
description: Deep exploration of an unfamiliar codebase. Use when onboarding to a new repo, auditing architecture, or mapping module dependencies.
context: fork
agent: Explore
compatibility: Requires Claude Code CLI.
---
# Explore Codebase

1. Walk the directory tree and summarise the top-level modules.
2. Identify the main entry points and their responsibilities.
3. Map the dependency graph between packages.
4. Return a structured summary to the main session — not the raw file list.

Ключевая строка — context: fork. Без неё вывод исследования попадает инлайн в ваш разговор. С ней сабагент работает в собственном окне контекста и возвращает резюме. Разница важна в больших репозиториях, где одно только исследование может потреблять тысячи токенов.

Тестирование Claude Skills: триггеры, корректность и сравнение с базовой линией

Skill не считается протестированным, потому что один демонстрационный сценарий «happy-path» сработал один раз. Руководство Anthropic делит тестирование на три слоя: ручное тестирование в Claude.ai, скриптовое тестирование в Claude Code и программное тестирование через Skills API. Рекомендуемые области оценки — срабатывание (triggering), функциональная корректность и производительность по сравнению с базовой линией без Skill. Это также лучший ответ на вопрос из FAQ «Как проверить, надёжен ли скилл». Вы тестируете выбор маршрута, качество вывода и эффективность, а не просто то, звучала ли модель уверенно.

Официальное руководство по оценке даёт чистую структуру для тестовых случаев. Каждый случай должен включать реалистичный промпт пользователя, человекочитаемое описание ожидаемого вывода и необязательные входные файлы. Документы хранят их в evals/evals.json внутри каталога Skill, что разумное соглашение, даже если вы делаете свой собственный харнес.

Используйте файл фикстуры и бескомпромиссную структуру оценки, как здесь:

{
  "skill_name": "review-pr",
  "evals": [
    {
      "id": 1,
      "prompt": "Review this PR for security issues and missing tests",
      "expected_output": "Findings grouped by severity with file references and at least one test recommendation.",
      "files": ["evals/files/pr-diff.patch"]
    },
    {
      "id": 2,
      "prompt": "Summarise last week's commits",
      "expected_output": "The skill should not activate.",
      "files": []
    }
  ]
}

Моё собственное правило тестирования жёстче, чем используют большинство команд, но оно согласуется с официальным руководством. Каждый серьёзный Skill должен иметь запросы, которые должны срабатывать (should-trigger), запросы, которые не должны срабатывать (should-not-trigger), хотя бы один тест граничного случая и сравнение с базовой линией без Skill. Примеры Anthropic сравнивают вызовы инструментов, неудачные вызовы API, циклы уточнения и использование токенов с Skill и без него, потому что «работает» — это не то же самое, что «улучшает рабочий процесс».

Если вы тестируете через Claude Agent SDK, помните о подводных камнях. Скиллы там — это артефакты файловой системы, а не программные регистрации. Anthropic говорит, что вы должны включить инструмент "Skill" и загрузить соответствующие настройки файловой системы через settingSources или setting_sources. Если вы опустите user или project, или укажете cwd в неправильное место, SDK не обнаружит Skill. Anthropic даже рекомендует спрашивать «Какие Skills доступны?» как прямую проверку обнаружения.

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

Устранение неполадок в Claude Skills: частые сбои и исправления

Когда Skill ведёт себя неправильно, сначала подозревайте упаковку, а не интеллект. Самые частые сбои — всё ещё скучные.

• Если Skill вообще не найден, убедитесь, что файл называется именно SKILL.md, с правильным регистром, внутри правильного каталога. Руководство по устранению неполадок Anthropic явно указывает на регистр имени файла, а его документы по Claude Code и SDK направляют вас прямо к .claude/skills/*/SKILL.md и ~/.claude/skills/*/SKILL.md как к первым проверкам.
• Если frontmatter недействителен, сначала проверьте разделители YAML и кавычки. Примеры Anthropic показывают классические ошибки: отсутствующие ---, незакрытые кавычки или недействительные имена с пробелами и заглавными буквами. Имена скиллов должны быть строчными и дефисированными.
• Если Skill существует, но не срабатывает, описание обычно слишком размыто. Собственное руководство по устранению неполадок Claude Code говорит включать ключевые слова, которые пользователи естественно скажут, проверить, появляется ли Skill, когда вы спрашиваете «Какие скиллы доступны?», и попробовать переформулировать ближе к описанию. PDF-руководство Anthropic добавляет отличный диагностический трюк: спросите Claude, когда бы он использовал Skill, и послушайте, как он перефразирует описание вам.
• Если Skill срабатывает слишком часто, сузьте область. Anthropic рекомендует сделать описание более специфичным, добавить отрицательные триггеры и использовать disable-model-invocation: true для рабочих процессов, которые вы хотите только по явной команде. Чрезмерное срабатывание — это обычно просто недостаточно определённый язык маршрутизации.
• Если Skill кажется теряющим влияние в длинных сессиях, помните, что описания могут быть сокращены в каталоге Claude Code, когда присутствует много скиллов, а вызванные Скиллы затем переносятся в пределах бюджетов токенов после компактизации. Anthropic рекомендует выносить ключевые слова в начало описания, обрезать лишний текст и, конкретно для Claude Code, настраивать SLASH_COMMAND_TOOL_CHAR_BUDGET, если списки описаний сжимаются слишком агрессивно.
• Если встроенный скрипт зависает или ведёт себя непредсказуемо, проверьте, ожидает ли он интерактивный ввод. Руководство по скриптам говорит, что агенты работают в неинтерактивных оболочках, поэтому TTY-подсказки, диалоги паролей и меню подтверждения — это баги дизайна. Принимайте ввод через флаги, переменные окружения или stdin и делайте ошибки явными.
• Если SDK не видит ваш Skill, убедитесь, что allowed_tools включает "Skill", что settingSources или setting_sources содержит user и/или project, и что cwd указывает на каталог, который действительно содержит .claude/skills/. Без этой настройки система Skill не включена, каким бы правильным ни выглядел ваш markdown.
• Если Skill на базе MCP загружается, но вызовы инструментов не удаются, чек-лист по устранению неполадок Anthropic разумный: проверьте, подключён ли MCP-сервер, подтвердите аутентификацию и области доступа, протестируйте MCP-инструмент напрямую без Skill, затем проверьте точные имена инструментов, потому что они чувствительны к регистру.

Скучная правда в том, что хорошие Claude Skills выглядят как хороший операционный инжиниринг. Чёткие имена. Маленькие файлы. Явные триггеры. Детерминированные скрипты там, где нужно. Реальные тесты. Если ваш Skill читается как чёткий ранбук, у агента есть шанс на успех. Если он читается как мозговой штурм, вы просто спрятали хаос в папке.