Создание skill из накопленных знаний (на примере Bot API Макса)

Skill — это способ упаковать доменные знания (например, о работе с Bot API мессенджера Макс) в переиспользуемый модуль, который Claude Code подгружает по требованию, а не в каждую сессию. Это экономит токены и позволяет переносить опыт между проектами: один раз дистиллировали знания из проекта первого бота — используете во всех последующих.

Официальная документация: Extend Claude with skills

Skill — это папка с файлом SKILL.md внутри: YAML-frontmatter вверху (обязательные поля name и description) и markdown-инструкции ниже. Опционально рядом лежат вспомогательные файлы.

Загрузка происходит по принципу прогрессивного раскрытия (progressive disclosure) в три уровня:

Экономика проста: вы держите библиотеку skill'ов, платя лишь малую фиксированную цену за их описания, а полное содержимое загружается ровно тогда, когда оно нужно. Это ключевое отличие от CLAUDE.md, который загружается целиком в каждую сессию.

~/.claude/skills/max-bot-api/
├── SKILL.md                      # обязательный файл: frontmatter + инструкции
└── references/                   # опционально: справочники, читаются по требованию
    ├── api-endpoints.md          # эндпоинты и форматы Bot API
    └── pitfalls.md               # известные грабли и их решения

Откройте Claude Code в проекте существующего бота и попросите выгрузить накопленные знания сразу в структуру skill'а:

Проанализируй проект и собери все знания о работе с Bot API мессенджера
Макс в структуру skill'а. Создай в /tmp/max-bot-api/:
1. SKILL.md — сжатая выжимка: архитектура бота, ключевые концепции API,
   типовые паттерны (обработка обновлений, клавиатуры, состояния диалога)
2. references/api-endpoints.md — справочник по эндпоинтам и форматам
3. references/pitfalls.md — грабли, которые мы встретили, и их решения
Пиши только проверенные факты из этого проекта, без воды.

Этот шаг выполняется один раз; дальше skill переносится в любой новый проект без затрат.

При совпадении имён приоритет у проектного skill'а — так можно локально переопределить личный.

Перенос дистиллированного skill'а:

mkdir -p ~/.claude/skills
cp -r /tmp/max-bot-api ~/.claude/skills/

Пример для знаний о Максе:

---
name: max-bot-api
description: Знания о Bot API российского мессенджера Макс — эндпоинты,
  авторизация, webhook, клавиатуры, состояния диалогов, известные грабли.
  Использовать всегда, когда работа касается бота в Максе, Bot API Макса,
  отправки сообщений, обработки обновлений или интеграции с мессенджером
  Макс, даже если пользователь не упомянул слово «Макс» явно, но проект —
  чат-бот для этого мессенджера.
user-invocable: false
---

# Bot API мессенджера Макс

## Ключевые концепции
- Авторизация: токен бота передаётся ...
- Получение обновлений: webhook / long polling, особенности ...

## Типовые паттерны
- Роутер команд: ...
- Inline-клавиатуры: ...

## Справочники
- Полный список эндпоинтов: см. references/api-endpoints.md
- Известные проблемы и решения: см. references/pitfalls.md

Три момента, критичных для качества:

1. Description — это триггер, а не документация. Claude при старте сессии сопоставляет запрос пользователя с описаниями всех skill'ов. Абстрактное описание («знания о боте») не сработает. Известная особенность: Claude склонен недоиспользовать skill'ы, поэтому описание стоит делать слегка «навязчивым» — перечислять синонимы, сценарии и формулировки, которые вы реально печатаете.
2. Тело SKILL.md — компактное, до 500 строк. Тяжёлые справочники — в references/: контент оттуда загружается только при реальной необходимости, а тот же контент в теле SKILL.md грузился бы при каждой активации.
3. Только проверенные факты. Skill — концентрат опыта, а не черновик. Устаревшие сведения в skill'е хуже их отсутствия.

1. Если директория ~/.claude/skills/ создана впервые — перезапустите сессию Claude Code (новая директория верхнего уровня начинает отслеживаться только после перезапуска). Последующие правки SKILL.md подхватываются прямо в работающей сессии.
2. Команда /skills показывает установленные skill'ы и позволяет менять их видимость.
3. Команда /doctor диагностирует, почему skill не появляется или не срабатывает.
4. Практический тест: в новом проекте задайте вопрос по теме («как отправить сообщение с клавиатурой в Максе») — в интерфейсе должна появиться загрузка skill'а.

Со временем skill превращается в общую базу знаний обо всех ботах на платформе Макс, доступную в каждом новом проекте за минимальную цену в токенах.