Agent Skills: продвинутая настройка и отладка. Часть 2

Самое сложное в Agent Skills не создать скилл. Сложно понять, почему он работает не так, как задумано. Вторая часть курса Anthropic целиком про это: конфигурация, многофайловая архитектура, распространение в команде и диагностика. Первая часть объясняла «что это и как начать». Здесь начинается инженерная работа.

Курс: Introduction to Agent Skills Платформа: Anthropic Academy (anthropic.skilljar.com) Ссылка: anthropic.skilljar.com/introduction-to-agent-skills Длительность: ~2.5 часа (10 видеоуроков + тест) Язык: English Бесплатно, с сертификатом Авторский конспект по материалам курса. Не является официальным переводом или публикацией Anthropic.

Это часть серии «Учусь вместо вас». Также в серии: Claude 101, AI Fluency for Educators, Advanced Prompt Engineering и Claude Code in Action.

Серия из 2 частей. Это часть 2. ← Часть 1: основы и первый скилл

Что нужно знать заранее. Статья предполагает, что вы уже работаете с Claude Code и создали хотя бы один скилл. Если нет, начните с первой части или с обзора Claude Code.

Зачем скиллу несколько файлов?

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

Курс вводит понятие Progressive Disclosure (постепенное раскрытие информации). Суть: Claude читает только то, что нужно прямо сейчас. Основные инструкции лежат в SKILL.md (рекомендация до 500 строк), а детали разнесены по подпапкам.

Структура продвинутого скилла выглядит так:

my-skill/
├── SKILL.md          ← основной файл (до 500 строк)
├── scripts/          ← скрипты, которые Claude выполняет
├── references/       ← дополнительная документация
└── assets/           ← шаблоны, данные, примеры

Файлы в scripts/ можно выполнять и передавать модели только их вывод, если исходный код не нужен для рассуждения. Это помогает не загружать в контекст лишний текст, но любой исполняемый скрипт нужно проверять как обычный код.

На практике я перенесла шаблоны в assets/, а скрипты проверки форматирования в scripts/. Основной SKILL.md стал короче, и его проще редактировать без риска задеть вспомогательные материалы.

Как делиться скиллами с командой?

Skills можно передавать через git-репозиторий: папка .claude/skills/ приходит вместе с проектом. Личные skills остаются в ~/.claude/skills/ и не попадают в репозиторий. Это различие помогает отделить общие правила проекта от персональных предпочтений.

Курс объясняет два уровня хранения через аналогию, которая мне показалась точной.

Личные скиллы (~/.claude/skills/) как ваши привычки. Как вы ставите будильник, варите кофе, какой у вас порядок на рабочем столе. Они работают для вас, но навязывать их коллегам бессмысленно.

Проектные skills (.claude/skills/ в репозитории) похожи на общий стандарт проекта: правила оформления, порядок проверки и чеклист перед публикацией. Они приходят вместе с репозиторием.

Способ	Как работает	Для кого
Репозиторий	.claude/skills/ коммитится в git, приходит с clone/pull	Команда проекта
Плагины	Публикация в marketplace	Сообщество
Enterprise	Managed settings, высший приоритет	Организация

Нюанс с субагентами, который стоит запомнить

Skill можно запустить в отдельном контексте через context: fork, а для кастомного субагента заранее указать нужные skills в его конфигурации. В обоих случаях стоит помнить: изолированный контекст не получает всю историю основного разговора автоматически.

Если subagent не следует ожидаемой процедуре, нужно проверить не только сам SKILL.md, но и способ запуска: доступен ли skill этому контексту и передана ли субагенту конкретная задача.

Что делать, когда скилл не работает?

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

Чеклист устранения неполадок

1. Skill не вызывается автоматически. Проверьте description: оно должно объяснять, что делает skill и когда его использовать. Добавьте конкретные сценарии, но не превращайте описание в длинный список ключевых слов.

2. Скилл не загружается. Проверяйте по порядку:

   • Существует ли папка?
   • Файл называется именно SKILL.md (не skill.md, не README.md)?
   • Корректен ли frontmatter (три дефиса, name, description)?
   • Видит ли Claude Code нужную папку skills? Изменения в существующих папках отслеживаются во время сессии, но новая верхнеуровневая папка может потребовать перезапуска.

3. Конфликт имён. Enterprise skill имеет приоритет над личным, а личный над проектным. Plugin skills используют пространство имён плагина и не конфликтуют с этими уровнями. Решение: давать skills описательные уникальные имена, например front-end-pr-review вместо review.

4. Ошибка при выполнении. Скрипт не запускается? Проверьте: chmod +x для исполняемых файлов, установлены ли зависимости, правильные ли пути (forward slashes, не backslashes).

Для диагностики сначала проверьте меню /skills, frontmatter и прямой вызов через /имя-skill. Автоматический выбор лучше тестировать отдельными реалистичными запросами, а не только одним удачным примером.

Как выглядит набор skills на практике?

Мой набор skills покрывает разные части редакционного и технического процесса. Одни используются регулярно, другие только в узких сценариях. Такая система требует периодического пересмотра: неактуальные инструкции быстро становятся источником ошибок.

Skill	Что делает	Когда нужен
content-workflow	Хранит требования к форматам и тону	При адаптации материала
learning-notes	Структурирует транскрипт курса	При подготовке конспекта
seo-aeo-review	Проверяет метаданные и структуру	Перед публикацией
fact-checking	Задаёт порядок проверки утверждений	Для материалов с изменяемыми фактами
writing-plans	Планирует структуру текста	Перед большим черновиком
debugging	Задаёт порядок диагностики	При ошибках в коде или скриптах
verification	Проверяет результат по критериям	Перед завершением задачи

Три типа skills, которые оказались особенно полезными:

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

Learning Notes задаёт одинаковый каркас для транскриптов: ключевые идеи, вопросы и термины. Это ускоряет первую обработку, но не заменяет сверку с исходными материалами курса.

SEO/AEO review фиксирует редакционный чеклист: метаданные, заголовки, FAQ и внутренние ссылки. Его задача не «дать SEO автоматически», а сделать проверку повторяемой.

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

Когда skills действительно улучшают процесс?

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

Польза появляется не от одного запуска, а от повторяемости: одинаковая задача проходит через одинаковые обязательные проверки. Это хорошо сочетается с фреймворком 4D, где роль AI и ответственность человека определяются заранее.

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

Ценность skill не в секретности промпта, а в точности описанного процесса. Проектные skills можно обсуждать, версионировать и улучшать вместе с остальной документацией.

Как Skills вписываются в экосистему Claude Code?

Skills занимают нишу специализированных знаний «по запросу» — между постоянными правилами CLAUDE.md и внешними инструментами MCP. Без понимания этой иерархии начинается каша.

Инструмент	Когда работает	Что даёт
CLAUDE.md	Всегда, автоматически	Общие правила проекта
Skills	По запросу, по смыслу	Специализированные знания
Subagents	Изолированно, при делегировании	Отдельный контекст
Hooks	На события (save, tool call)	Валидация, автоматические проверки
MCP	По необходимости	Инструменты (Notion, Sheets, браузер)

Ключевое различие: Skills добавляют знания и процедуры (как делать), а MCP даёт инструменты и данные (чем делать). Они могут работать независимо, но часто дополняют друг друга.

Типичная рабочая комбинация на примере моего блога:

1. CLAUDE.md задаёт правила: стиль кода, язык коммитов, дизайн-система
2. Skills специализируют работу: создание контента, проверка фактов, SEO-вычитка
3. Hooks автоматизируют проверки: линтинг перед коммитом
4. MCP подключает внешние сервисы: Notion, Google Sheets
5. Субагенты берут на себя изолированные задачи: параллельная обработка нескольких статей

Понимание этой экосистемы помогает не складывать все инструкции в CLAUDE.md и отделять постоянные правила от процедур, инструментов и изолированных задач.

---

Серия «Учусь вместо вас»:

• Claude 101
• AI Fluency for Educators
• Advanced Prompt Engineering
• Claude Code in Action, часть 1
• Claude Code in Action, часть 2
• Agent Skills, часть 1
• Agent Skills, часть 2 ← вы здесь

Часто задаваемые вопросы

Можно ли использовать один скилл в нескольких проектах?

Да. Личные скиллы в ~/.claude/skills/ доступны во всех проектах. Проектные скиллы в .claude/skills/ доступны только в конкретном репозитории. Если скилл универсальный (например, мой content-factory), держите его в личных. Если специфичный для проекта, то в проектных.

Сколько скиллов можно создать?

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

Что выбрать: Skills или CLAUDE.md?

Если инструкция нужна в каждом разговоре без исключения, это CLAUDE.md. Если инструкция нужна только для определённого типа задач, это скилл. CLAUDE.md съедает контекст всегда. Скилл загружается только когда нужен. Я переношу в CLAUDE.md только то, что действительно критично для каждой сессии.

Обязательно ли перезапускать Claude Code после изменения скилла?

Обычно нет: Claude Code отслеживает изменения в существующих папках skills во время сессии. Перезапуск может понадобиться, если верхнеуровневая папка skills была создана уже после запуска.

---

Если вы хотите определить, какие повторяющиеся процессы стоит оформить как skills, это можно обсудить на консультации.