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

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

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

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

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

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

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

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

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

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

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

Вот критичный момент, который не сразу очевиден, и он, собственно, меняет всё. Файлы в scripts/ Claude выполняет, а не читает. Разница колоссальная для расхода токенов. Когда Claude читает файл на 200 строк, он тратит токены на каждую строку. Когда выполняет скрипт, тратит токены только на вывод. Представьте: прочитать всю кулинарную книгу vs. нажать одну кнопку на блендере.

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

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

Скиллы передаются через git-репозиторий: поместите папку .claude/skills/ в проект, и каждый, кто сделает git clone, получит все скиллы автоматически. Личные скиллы при этом остаются в ~/.claude/skills/ и не попадают в репозиторий. Если вы работаете в команде (а у меня агентство, то есть команда есть), это ключевое различие.

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

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

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

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

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

Субагенты (subagent в терминологии Claude Code, изолированные экземпляры, которым делегируют задачи) не наследуют скиллы автоматически. Они стартуют с чистым контекстом, как новый сотрудник, которому ничего не объяснили. Чтобы субагент использовал определённые скиллы, их нужно явно прописать в поле skills файла .claude/agents/agent.md. Дополнительный момент: в субагентах скиллы загружаются сразу (eagerly), а не по требованию. Встроенные агенты вроде Explore и Plan вообще не имеют доступа к скиллам.

Я столкнулась с этим, когда субагент для создания контента не мог найти скилл content-factory. Полчаса искала баг в скилле, а проблема была в конфигурации агента. Курс бы сэкономил мне эти полчаса.

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

Скиллы ломаются. Не в теории, а в реальной работе. Курс даёт конкретный алгоритм диагностики, который я теперь использую каждый раз.

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

1. Скилл не триггерится. Причина почти всегда одна: плохое описание (description). Claude сопоставляет ваш запрос с description по смыслу, и если формулировка расплывчатая, совпадения не происходит. Решение: переписать description, добавить trigger phrases на русском и английском. Максимум 1024 символа, каждое слово на вес золота.

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

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

3. Конфликт с другим скиллом. Если у двух скиллов одинаковое имя, побеждает тот, у кого выше приоритет: Enterprise > Personal > Project > Plugins. Понимаете, вы можете неделю отлаживать свой скилл, а проблема в том, что enterprise-версия его перекрывает. Решение: давать скиллам описательные уникальные имена (не review, а front-end-pr-review).

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

Главный инструмент диагностики: Skills Validator. Команда verify agent skills покажет, какие скиллы загружены, какие конфликтуют, какие имеют ошибки в синтаксисе. Грубо говоря, это npm doctor, но для скиллов.

После прохождения курса я прогнала валидатор по всем своим скиллам и нашла два с битым frontmatter. Они просто молча не работали. Без валидатора я бы ещё долго не заметила.

Как выглядит экосистема из 14 скиллов на практике?

Экосистема из 14 скиллов — это система, которая экономит мне часы каждый день. За неделю после прохождения первых курсов Anthropic Academy я, Валерия Ом, собрала 14 активных скиллов. Не все сложные, не все многофайловые, но вместе они покрывают весь рабочий цикл от создания контента до публикации.

Скилл	Что делает	Частота использования
content-factory	Создаёт карточки для соцсетей, посты, статьи	Каждый день, 3+ раза
learning-notes	Конвертирует SRT/транскрипты в конспекты (Notion + Sheets)	2-3 раза в неделю
seo-aeo-review	Финальная вычитка статей для поисковиков и AI	При каждой публикации
fact-checking	Проверяет факты, законы, статистику в статьях	При каждой публикации
brainstorming	Структурированная генерация идей	3-4 раза в неделю
writing-plans	Планирует структуру текстов	2-3 раза в неделю
executing-plans	Выполняет пошаговые планы	2-3 раза в неделю
subagents	Делегирует задачи субагентам	Ежедневно
debugging	Отладка кода и скриптов	По необходимости
TDD	Разработка через тесты	По необходимости
verification	Проверка результатов работы	По необходимости
code-review	Ревью кода перед коммитом	По необходимости
worktrees	Параллельная работа в нескольких ветках	Редко
ui-ux-pro-max	Дизайн интерфейсов	При редизайне

Три скилла, которые дали максимальный эффект:

content-factory экономит мне примерно 3 часа в день. Раньше я вручную адаптировала каждый текст под формат каждой площадки. Теперь пишу одну статью, а скилл генерирует варианты для Instagram, Telegram, VK, TikTok. С правильной длиной, хештегами и визуальными элементами для каждой платформы.

learning-notes автоматически обработал конспекты шести курсов. Без этого скилла я бы потратила на каждый конспект по 2-3 часа ручной работы. Шесть курсов, по три часа. Это 18 часов, которые пошли на другие задачи.

seo-aeo-review проверяет 40+ параметров в каждой статье: от длины description до наличия FAQ-блока, от внутренних ссылок до авторской атрибуции. Запускаю его перед каждой публикацией на valeryom.com, и каждый раз он находит что-то пропущенное.

Ни один из 14 скиллов не был создан с первого раза в финальном виде. Каждый прошёл через 3-5 итераций: первая версия, тестирование, переписать description, добавить trigger phrases, вынести шаблоны в отдельные файлы. Именно этот цикл и описывает курс.

Почему скиллы становятся конкурентным преимуществом?

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

Когда я настраиваю контент-факторию один раз и потом использую её для всех клиентов, я не просто экономлю время. Я создаю систему, способную работать без моего постоянного участия. Это то самое переключение из режима автоматизации в режим дополнения, о котором говорит фреймворк 4D. Разница между «я делаю маркетинг» и «у меня есть маркетинговая система».

Правило двух повторений: если вы объясняете Claude одно и то же больше двух раз, вы тратите время зря. Создайте скилл. Если скилл не срабатывает, правьте описание. Если описание правильное, а скилл всё равно не триггерится, запускайте валидатор.

И ещё кое-что, что курс не произносит вслух, но что следует из всей логики: экосистему скиллов невозможно скопировать. Можно украсть промпт, повторить workflow. Но систему из 14 скиллов, заточенных под конкретный бизнес, с конкретными шаблонами, проверками и интеграциями, просто так не воспроизведёшь.

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

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

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

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

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

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), держите его в личных. Если специфичный для проекта, то в проектных.

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

Технического ограничения нет, но есть практическое. Claude загружает имена и описания всех скиллов при старте. Если у вас 50 скиллов с расплывчатыми описаниями, сопоставление будет работать хуже. Лучше 14 чётко описанных, чем 40 размытых.

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

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

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

Да. Скиллы сканируются при запуске. Если вы изменили SKILL.md, но не перезапустили Claude Code, он будет работать со старой версией. Частая ошибка, я сама на ней попадалась не раз.

---

Хотите внедрить AI-инструменты в свой маркетинг? Запишитесь на консультацию. Разберём ваш случай и составим план автоматизации.

Делюсь инструментами и кейсами в Telegram. Без воды, только практика.