---
name: doc-to-skill
description: "Конвертер документации в SKILL.md. Триггеры: 'сделай скилл из', 'оформи как скилл', 'превратить в скилл', 'конвертировать в SKILL.md', 'make a skill from', 'convert to skill', 'создай документацию для Claude Code'. НЕ для создания хуков — используй create-hook."
---

# Doc-to-Skill: конвертер документации в скиллы Claude Code

## Обзор

Превращает **сырую информацию** о технологии (статьи, документацию, README, результаты ресёрча) в **структурированный SKILL.md** — формат, который Claude Code использует как руководство к действию. Убирает маркетинг и прозу, оставляет команды, паттерны, диагностику.

---

## Рабочий процесс

### Шаг 1: Сбор исходного материала

| Тип входа | Действие |
|-----------|----------|
| URL на документацию | `WebFetch` — загрузить и извлечь текст |
| Файл (PDF, MD, TXT, HTML) | `Read` — прочитать содержимое |
| Устное описание | Уточнить вопросами, затем `WebSearch` |
| Несколько источников | Объединить, устранить дубликаты |

Если информации недостаточно — **обязательно** провести исследование через `WebSearch` и `WebFetch`.

### Шаг 2: Извлечение категорий знаний

```
ИДЕНТИФИКАЦИЯ           УСТАНОВКА И НАСТРОЙКА
├─ Что это              ├─ Зависимости
├─ Для чего             ├─ Команды установки
└─ Когда триггерить     └─ Конфигурационные файлы

CORE API / КОМАНДЫ      ПАТТЕРНЫ ИСПОЛЬЗОВАНИЯ
├─ Основные команды     ├─ Типичные сценарии
├─ Ключевые параметры   ├─ Шаблоны (копируй-вставляй)
└─ Форматы ввода/вывода └─ Интеграция с другими

АРХИТЕКТУРА             ДИАГНОСТИКА
├─ Как работает внутри  ├─ Частые ошибки + решения
├─ Ключевые абстракции  ├─ Антипаттерны
└─ Ограничения          └─ Отладочные команды
```

### Шаг 3: Сборка SKILL.md по шаблону

Для полного шаблона читай `references/template.md`.

---

## Правила трансформации

### Что УБИРАТЬ
- История и предыстория
- Маркетинговые фразы
- Философские рассуждения
- Сравнения с конкурентами (без практической пользы)
- Избыточные повторения
- Длинные абзацы прозы → сжимай в таблицы и списки

### Что ДОБАВЛЯТЬ
- **Копируемые команды** — готовые к Ctrl+C → Ctrl+V
- **Таблицы параметров** — вместо прозы
- **ASCII-диаграммы** — для архитектуры и потоков
- **Шаблоны с [ПЛЕЙСХОЛДЕРАМИ]** — готовые к адаптации
- **Таблицы диагностики** — проблема → причина → решение
- **Антипаттерны** — что НЕ делать (Claude склонен повторять ошибки)

### Стилистика
1. **Императив** — «Используй X» вместо «Можно использовать X»
2. **Конкретика** — `pip install onnxruntime` вместо «установите библиотеку»
3. **Объясняй "почему"** — «делай так, потому что иначе Y»
4. **Без модальных "можешь"** — инструкция, не опция
5. **Русский язык** для описаний, английский для команд и кода
6. **Длина** — SKILL.md не более 500 строк, иначе выноси в `references/`

---

## Контроль качества

| Критерий | Проверка |
|----------|----------|
| Триггерность | Description содержит >= 5 триггерных фраз? |
| Копируемость | Каждая команда готова к копированию? |
| Полнота | Есть: установка, команды, >= 1 шаблон, диагностика? |
| Actionability | Claude выполнит инструкцию без доп. поиска? |
| Длина | <= 500 строк? Лишнее вынесено в references/? |
| Антипаттерны | >= 3 распространённых ошибки? |
| Без воды | Нет истории, маркетинга, философии? |

---

## Правило специализированного fallback-скилла

**Если файл-источник содержит actionable-контент (параметры, команды, JSON-схемы, таблицы, примеры кода), но НЕ попадает ни в один существующий доменный скилл — создать отдельный специализированный скилл, а НЕ отсеивать.**

### Алгоритм принятия решения

```
Файл содержит actionable-контент?
├─ НЕТ (обзор, маркетинг, каталог) → ОТСЕВ — не создавать скилл
└─ ДА (параметры, команды, схемы, код)
   ├─ Попадает в существующий домен? → ДОБАВИТЬ в этот скилл
   └─ НЕ попадает ни в один домен?
      ├─ Можно объединить с 1-3 похожими файлами? → НОВЫЙ специализированный скилл
      └─ Единственный файл, >= 50 строк actionable? → НОВЫЙ микро-скилл
```

### Критерии actionable-контента (любой из)

| Критерий | Пример |
|----------|--------|
| Таблица параметров/настроек | VS Code extension settings |
| Команды с флагами | `claude --chrome`, `/statusline` |
| JSON/YAML схема | statusline input JSON structure |
| Примеры кода (копируемые) | bash/python/node скрипты |
| Keyboard shortcuts | `Cmd+Esc`, `Option+K` |
| API endpoints / protocols | Native Messaging API |
| Troubleshooting таблица | проблема → решение |

### Антипаттерн: ложный отсев

**НЕПРАВИЛЬНО:** "Файл слишком узкий → отсев"
**ПРАВИЛЬНО:** "Файл узкий, но содержит 12 параметров и 5 скриптов → специализированный скилл"

Узость домена ≠ отсутствие ценности. Если пользователь задаст вопрос по этой теме, скилл должен существовать.

---

## Правила роутера и метрик

### Обязательная регистрация в роутере

**КАЖДЫЙ новый скилл ДОЛЖЕН быть добавлен в `.claude/skills/skill-router-config.json`.**

```json
// Добавить bundle в skill-router-config.json
"my-new-skill": {
  "keywords": ["уникальный триггер 1", "уникальный триггер 2"],
  "skills": ["my-new-skill"],
  "optional": []
}
```

Родственные скиллы (одна технология) группируй в один bundle с `skills` + `optional`.

### Уникальность триггеров

Перед выбором триггерных ключевых слов — проверь уникальность:

```bash
grep -r "keyword" .claude/skills/*/SKILL.md
```

| Правило | Пример |
|---------|--------|
| Один keyword → один primary скилл | "checkpointer" → только `langgraph-memory-persistence` |
| Если пересечение неизбежно → НЕ-redirect | "НЕ для X — используй skill-Y" |
| Квалифицируй общие слова | "MCP langchain" вместо "MCP", "streaming langchain" вместо "streaming" |

### Краткость описания

- Description ≤ 300 символов (1-2 строки триггеров + НЕ-redirects)
- Формула: `[Что делает, 1 строка]. Триггеры: [...]. НЕ для X — используй Y.`
- Убирай: "Используй этот скилл когда...", "Также используй когда..."

### НЕ-redirect обязателен

Для **каждого** пересекающегося домена добавляй:
```
НЕ для [overlapping domain] — используй [correct-skill].
```

---

## Структура выходных файлов

```
.claude/skills/<skill-name>/
├── SKILL.md              ← Основной (≤ 500 строк)
└── references/           ← [если применимо]
    ├── advanced-usage.md
    ├── templates.md
    └── api-reference.md
```

Для полного шаблона SKILL.md читай `references/template.md`.