Как научить Claude Code новым навыкам: пишем свой skill с нуля

Claude Code умеет многое из коробки, но рано или поздно вы столкнётесь с задачей, которую он решает плохо — или не решает вообще. Для таких случаев есть механизм skills — текстовые инструкции, которые подгружаются в контекст по ситуации. Покажу весь процесс создания skill на примере конвертации изображений в ICO-формат.

Для таких случаев в Claude Code есть механизм skills — текстовые инструкции, которые подгружаются в контекст по ситуации. Skill — это не плагин и не код. Это структурированная шпаргалка, которая превращает Claude Code из «умного, но незнающего» в «умного и знающего».

Покажу весь процесс на примере конкретной задачи — конвертации изображений в ICO-формат. Задача в общем-то простая, можно каждый раз обходиться без skill, но Claude Code раз за разом наступает на одни и те же грабли — и это отличный повод автоматизировать.

Зачем вообще нужен skill

Без skill конвертация картинки в .ico выглядит так: вы просите Claude Code сконвертировать SVG в ICO, он уверенно пишет команду с ImageMagick — которого у вас нет. Вы говорите, что ImageMagick не установлен. Он пробует cairosvg — тот падает с ошибкой про отсутствующую libcairo-2.dll. Потом пробует ещё что-то. Три-четыре итерации, и вот вы уже потратили кучу контекста на то, что должно было занять пять секунд.

Со skill Claude Code сразу знает: ImageMagick недоступен, cairosvg не работает на Windows, зато есть sharp-cli через npx и Python с Pillow. И знает конкретный workflow — сначала нарезать PNG всех размеров, потом собрать в ICO. И даже знает про неочевидные особенности Pillow, которые иначе пришлось бы каждый раз открывать заново.

Что такое skill технически

Skill — это файл SKILL.md в папке ~/.claude/skills/<имя-скилла>/. Файл состоит из YAML-заголовка и Markdown-тела:

---
name: ico-converter
version: 1.0.0
description: Convert image files (SVG, PNG, JPG, WebP, GIF, BMP) 
  to .ico format. Use when the user asks to "convert to ico", 
  "create favicon", "make icon", "generate .ico"...
---

Поле description — самое важное. Именно по нему Claude Code решает, когда подгружать skill. Если описание расплывчатое — skill не активируется, когда нужен. Если слишком узкое — не активируется на синонимы вашего запроса. Хорошая практика — перечислить типичные формулировки, которыми вы можете попросить об этой задаче.

После заголовка идёт тело — обычный Markdown с инструкциями. Здесь вы описываете всё, что Claude Code должен знать для выполнения задачи.

Что писать в теле skill

Тело skill — это, по сути, инструкция для Claude Code. Вот структура, к которой я пришёл:

1. Доступные инструменты. Что установлено, что работает, какие версии. И не менее важно — что НЕ установлено и что НЕ работает. Без этого Claude Code будет пробовать самый популярный инструмент (ImageMagick для работы с картинками), натыкаться на ошибку и тратить ваш контекст.

Tool	Version	Role
sharp-cli (via npx)	5.2.0	Rasterize SVG to PNG
Python Pillow	12.0.0	Combine PNGs into .ico

Tools NOT available (do not attempt)

ImageMagick — not installed
cairosvg — fails at runtime (missing libcairo-2.dll)

Секция «NOT available» экономит больше всего времени. Без неё каждая новая сессия начинается с одних и тех же граблей.

2. Конкретные команды. Не описания в духе «используйте sharp для ресайза», а готовые команды с флагами:

npx sharp-cli -i "source.svg" -o "icon_32.png" \
  resize 32 32 --fit contain --background "rgba(0,0,0,0)"

Чем конкретнее — тем меньше шансов, что Claude Code нагаллюцинирует несуществующий флаг или перепутает синтаксис.

3. Подводные камни. Это самая ценная часть. Каждый gotcha, на который вы наступили — это минус одна потраченная итерация в будущем:

Pillow ICO Gotcha

The 256px image MUST be the base (first argument to .save()). Passing a small image as the base with sizes= kwarg results in Pillow silently producing a single-size ICO.

Pillow не выбрасывает ошибку — он молча генерирует .ico файл с одним размером вместо шести. Без skill Claude Code наступит на те же грабли.

4. Чеклист. В конце skill полезно добавить проверочный список — что Claude Code должен сделать перед тем, как сказать «готово»:

Checklist Before Finishing

Verify .ico file size (typically 10-30 KB for 6 sizes)
Verify all sizes present by reopening with Pillow
Remove temporary PNG files
Report file path and size

Как я создал этот skill

Конвертация картинок в ICO — задача, которая всплывает в разных проектах. Нужен фавикон для сайта, иконка для десктопного приложения, что-то ещё. Каждый раз я просил Claude Code, и каждый раз начиналась одна и та же история: попытка через ImageMagick, ошибка, попытка через cairosvg, ошибка, перебор вариантов. Иногда в итоге получалось, иногда нет — зависело от того, сколько контекста было потрачено и не запутался ли он по дороге.

После очередного такого раза я решил сделать skill. Причём делать руками ничего не пришлось — прямо в той же сессии, где мы только что провозились с конвертацией, я попросил Claude Code: «Учти все ошибки, которые мы тут допустили, и создай skill, чтобы в следующий раз это работало сразу». Он собрал рабочий workflow, записал, что не нужно пробовать, добавил конкретные команды — и сохранил как SKILL.md.

Skill я поместил на уровень системы (~/.claude/skills/), а не в конкретный проект. Теперь в любом проекте, где мне нужно сконвертировать картинку в ICO, Claude Code подхватывает этот skill и делает всё с первого раза.

Когда стоит создавать skill

Skill имеет смысл для повторяющихся задач, где шаги неочевидны и включают несколько этапов. Главное преимущество skill — знание загружается в контекст только когда нужно, а не висит там постоянно.

Можно, конечно, скачать готовые skills из публичных каталогов. Но универсальный skill не знает, какие инструменты стоят на вашей конкретной машине. Он предложит ImageMagick, потому что это самый популярный вариант — а у вас ImageMagick не установлен, зато есть sharp-cli и Python. Свой skill заточен под вашу среду и работает сразу.

Итого

Skill — это способ превратить ваш опыт в переиспользуемое знание для Claude Code. Не код, не плагин — просто хорошо структурированная инструкция. Пишется за 2 минуты, экономит время при каждом использовании.

Начните с задачи, которую вы уже решали руками несколько раз. Запишите, какие инструменты работают, какие нет, и какие грабли вы нашли. Положите в ~/.claude/skills/. Всё, ваш первый skill готов.