/init-skill — Генератор новых Skills

Перед началом

Прочитай .claude/qa_agent.md и .claude/agents/sdet.md.

Когда использовать

• •Создание нового инструмента для повторяющейся QA-задачи
• •Стандартизация процесса в команде
• •Автоматизация рутинных проверок

Принцип Progressive Disclosure

YAML-заголовок (всегда в промпте) → Тело SKILL.md (при активации) → scripts/references (по запросу).

Полная диаграмма: references/skill-template.md → секция "Progressive Disclosure".

Стиль написания

Используй императивный/инфинитивный стиль в инструкциях skill:

Verbosity Protocol

Structured Output Priority: Весь analysis идёт в артефакт (MD/HTML), не в чат.

Chat output (ограничения):

• •Brief Summary: max 5 строк (что нашли, сколько, итог)
• •Findings table: max 15 строк (топ по severity)
• •Полный отчёт: 📊 Полный отчёт: {path} + открыть файл

Iterative steps: Не выводить прогресс по каждому файлу. Checkpoint только при:

• •Phase transition (Фаза N → Фаза N+1)
• •Blocker обнаружен
• •Завершение (SKILL COMPLETE)

Tools first:

• •Grep → table → report, без "Now I will grep..."
• •Read → analyze → report, без "The file shows..."

Post-Check: Inline перед SKILL COMPLETE (5-7 строк checklist), не отдельный файл.

ИНТЕРАКТИВНЫЙ WORKFLOW

Фаза 1: Определение назначения

Шаг 1.1: Спроси назначение

Что должен делать новый skill?

Примеры для QA:
- Генерировать тест-кейсы для [область]
- Анализировать [что] на [что искать]
- Создавать автотесты для [тип API/UI]
- Проверять [артефакт] на соответствие [стандарт]

Шаг 1.2: Определи категорию

Категории: Analysis (отчёт), Generation (код/документ), Validation (pass/fail), Transformation (конвертация).

Полная таблица с примерами: references/skill-template.md → секция "Категории skills".

Шаг 1.3: Собери конкретные примеры использования

Попроси пользователя привести 2-3 конкретных примера:

Прежде чем проектировать skill, мне нужны конкретные примеры:

1. **Trigger-фразы** — что скажет пользователь, чтобы вызвать skill?
   Пример: "проверь скриншот на L10N баги", "сгенерируй тесты для /api/v1/users"

2. **Use cases** — опиши 2-3 реальных сценария использования:
   - Какие входные данные?
   - Какой ожидаемый результат?
   - Какой контекст (проект, стадия, команда)?

3. **Анти-примеры** — когда skill НЕ должен использоваться?

Зачем: Конкретные примеры определяют scope скилла точнее, чем абстрактное описание. Trigger-фразы помогут написать точный YAML description.

✅ CHECKPOINT 1: Подтверждение назначения

Понял задачу так:
- Назначение: [что делает]
- Категория: [Analysis/Generation/Validation/Transformation]
- Название: /[skill-name]

Примеры использования:
1. [use case 1]
2. [use case 2]

Trigger-фразы: "[фраза 1]", "[фраза 2]"

Всё верно? (да / нет, уточню)

⚠️ НЕ ПРОДОЛЖАЙ без подтверждения пользователя!

Фаза 2: Проектирование структуры

Шаг 2.1: Предложи структуру на основе категории

Предложения зависят от категории skill (Analysis/Generation/Validation/Transformation).

Полный список вопросов для каждой категории — в references/interaction-guide.md → секция "Структурные предложения по категориям"

Шаг 2.2: Определи файловую структуру

.claude/skills/{skill-name}/
├── SKILL.md              # Обязательно (case-sensitive!)
├── scripts/              # Executable — автоматизация и утилиты
│   └── [name].py/.sh
├── references/           # Loaded into context — справочники, чек-листы
│   └── [name].md/.json
└── assets/               # Used in output, NOT loaded — шаблоны, иконки
    └── [name].md/.png

Critical rules:

• •Папка: только kebab-case (my-skill ✅, My_Skill ❌)
• •Файл: точно SKILL.md (case-sensitive, не skill.md)
• •НЕ создавай README.md внутри skill папки — вся документация в SKILL.md или references/

✅ CHECKPOINT 2: Подтверждение структуры

Структура skill:
- Основной файл: SKILL.md
- Scripts: [да/нет] — [назначение]
- References: [да/нет] — [назначение]
- Assets: [да/нет] — [назначение]

Дополнительные фичи:
- [список выбранных опций]

Продолжаем? (да / изменить)

⚠️ НЕ ПРОДОЛЖАЙ без подтверждения пользователя!

Фаза 3: Создание YAML-заголовка

Прочитай references/yaml-reference.md для полного справочника по полям, ограничениям и примерам.

Шаг 3.1: Сгенерируй name и description

Ключевые правила:

• •name: kebab-case, совпадает с именем папки, без "claude"/"anthropic"
• •description: формула [Что делает]. [Когда использовать], < 1024 символов, без XML тегов

Используй trigger-фразы из Checkpoint 1 для формулировки "Когда использовать".

✅ CHECKPOINT 3: Подтверждение YAML frontmatter

YAML Frontmatter (будет виден в системном промпте):

---
name: [skill-name]
description: [твой вариант]
---

Устраивает? (да / предложи свой вариант)

⚠️ НЕ ПРОДОЛЖАЙ без подтверждения пользователя!

Фаза 4: Подготовка ресурсов (scripts, references, assets)

Создай выбранные в Checkpoint 2 ресурсы:

• •scripts/ — исполняемые утилиты (Python/Bash)
• •references/ — справочники, загружаемые в контекст
• •assets/ — шаблоны для вывода (НЕ загружаются в контекст)

✅ CHECKPOINT 4: Подтверди список созданных файлов перед переходом к SKILL.md

Фаза 5: Написание тела SKILL.md

Шаг 5.1: Сгенерируй полный SKILL.md

Прочитай и используй шаблон из references/skill-template.md → секция "Шаблон".

Стиль: императивный (см. "Стиль написания" выше).

При написании инструкций ссылайся на реальные ресурсы, подготовленные в Фазе 4:

• •Прочитай references/checklist.md — а не абстрактное "используй чек-лист"
• •Запусти scripts/validate.sh — а не "провалидируй"

✅ CHECKPOINT 5: Ревью SKILL.md

Покажи полный SKILL.md и предложи опции редактирования (см. references/interaction-guide.md → "Опции редактирования").

⚠️ ОБЯЗАТЕЛЬНО покажи файл и дождись выбора!

Фаза 6: Итеративная доработка

Цикл доработки описан в references/interaction-guide.md → "Цикл доработки"

Фаза 7: Сохранение и валидация

✅ CHECKPOINT 6: Финальное подтверждение

Готово к сохранению:

.claude/skills/[skill-name]/
├── SKILL.md ✅
├── scripts/[name].* ✅ (если есть)
├── references/[name].* ✅ (если есть)
└── assets/[name].* ✅ (если есть)

Сохранить? (да / вернуться к редактированию)

⚠️ НЕ СОХРАНЯЙ без подтверждения пользователя!

Шаг 7.1: Сохрани файлы

Создай директорию и все файлы.

Совет: Используй scripts/init_skill.sh для генерации шаблонной структуры:

bash .claude/skills/init-skill/scripts/init_skill.sh [skill-name]

Шаг 7.2: Валидация и завершение

• •Пройди references/validation-checklist.md
• •Если SKILL.md > 500 строк — предложи разбиение
• •Покажи результат: путь к skill, команду вызова
• •Предложи цикл улучшений после первого использования (см. references/interaction-guide.md)

Связанные файлы

• •Init-скрипт: .claude/skills/init-skill/scripts/init_skill.sh
• •Шаблон: references/skill-template.md
• •Полный гайд: docs/ai-files-handbook.md
• •Примеры: .claude/skills/*/SKILL.md