02. Планирование и дизайн

### **Начните со сценариев использования:** Прежде чем писать код, сформулируйте 2-3 конкретных сценария, которые ваш skill должен закрывать. --- ##### Пример хорошо описанного сценария: **Сценарий:** Планирование спринта **Когда срабатывает:** пользователь пишет «помоги спланировать спринт» или «создай задачи на спринт» **Что происходит:** 1. Забирает текущий статус проекта из Linear (через MCP) 2. Анализирует скорость и загрузку команды 3. Предлагает приоритизацию задач 4. Создаёт задачи в Linear с нужными метками и оценками **Итог:** Полностью спланированный спринт, задачи уже в трекере Ответьте себе на четыре вопроса: 1. Какую задачу хочет решить пользователь? 2. Из каких шагов складывается процесс? 3. Какие инструменты понадобятся: встроенные или через MCP? 4. Какую предметную экспертизу стоит зашить в skill? --- ### **Три типичные категории skills:** #### **1. Генерация документов и ресурсов** **Для чего:** стабильный, качественный результат: документы, презентации, дизайны, код, приложения. **Живой пример:** skill [`frontend-design`](https://github.com/anthropics/skills/tree/main/skills/frontend-design) «Создаёт выразительные, готовые к продакшену фронтенд-интерфейсы. Подходит для веб-компонентов, лендингов, артефактов и приложений.» **Характерные приёмы:** - Зашитые стайл-гайды и стандарты бренда - Шаблоны для единообразия результатов - Чеклисты качества перед финальной выдачей - Внешние инструменты не нужны, хватает встроенных возможностей Claude --- #### **2. Автоматизация рабочих процессов** **Для чего:** многоэтапные процессы, где важна единая методология, в том числе координация между несколькими MCP-серверами. **Живой пример:** skill [`skill-creator`](https://github.com/anthropics/skills/tree/main/skills/skill-creator) _«Интерактивный помощник для создания новых skills. Ведёт пользователя через формулировку сценариев, заполнение frontmatter, написание инструкций и проверку.»_ **Характерные приёмы:** - Пошаговый процесс с контрольными точками - Готовые шаблоны для типовых ситуаций - Встроенные подсказки по улучшению - Цикл «сделал, проверил, доработал» --- #### **3. Усиление MCP-интеграции:** **Для чего:** добавить слой экспертизы поверх инструментов, которые даёт MCP-сервер. **Живой пример:** skill [`sentry-code-review`](https://github.com/getsentry/sentry-for-claude/tree/main/skills) (от Sentry) _«Автоматически находит и исправляет баги в Pull Request'ах на GitHub, опираясь на данные мониторинга Sentry через MCP.»_ **Характерные приёмы:** - Цепочка из нескольких MCP-вызовов в нужном порядке - Предметная экспертиза, вшитая в логику - Контекст, который иначе пришлось бы объяснять каждый раз - Обработка типичных ошибок MCP --- ### **Как понять, что skill работает:** Это ориентиры, а не жёсткие пороги. Часть оценки неизбежно будет субъективной — и это нормально. #### Цифры: - **Skill подключается в 90% подходящих запросов** Как проверить: прогоните 10-20 тестовых запросов. Посчитайте, в скольких случаях skill загрузился сам, без ручного вызова. - **Рабочий процесс укладывается в X вызовов инструментов** Как проверить: дайте одну и ту же задачу с включённым skill и без. Сравните число вызовов и расход токенов. - **Ни одного сбойного API-вызова за весь процесс** Как проверить: смотрите логи MCP-сервера во время тестовых прогонов. #### **Ощущения:** - Пользователю не приходится подсказывать Claude, что делать дальше - Процесс доходит до конца без ручных правок - Результаты воспроизводимы от сессии к сессии --- ### **Технические требования**: #### Структура файлов ```bash your-skill-name/ ├── SKILL.md # Обязательный ├── scripts/ # Опционально - скрипты │ ├── process_data.py │ └── validate.sh ├── references/ # Опционально - справка │ ├── api-guide.md │ └── examples/ └── assets/ # Опционально - шаблоны и тп. └── report-template.md ``` #### Железные правила: **Файл SKILL.md:** - Имя ровно `SKILL.md`, регистр важен. - Никакие вариации не пройдут: ни `SKILL.MD`, ни `skill.md` . **Имя папки:** ✅ Правильно: `notion-project-setup` , kebab-case, всё строчными, через дефис. ❌ Неправильно: `Notion Project Setup` `notion_project_setup` `NotionProjectSetup` **README.md внутри skill не нужен.** Вся документация лежит в `SKILL.md` или `references/`. README понадобится позже, на уровне репозитория, для людей, а не для Claude. --- ### **YAML frontmatter: самое важное в skill:** Именно по YAML-шапке Claude решает, подключать ваш skill или нет. Здесь нельзя ошибиться. #### Минимально рабочий вариант ```yaml --- name: your-skill-name description: Что делает. Подключать, когда пользователь просит [конкретные фразы]. --- ``` Этого достаточно для старта. #### Обязательные поля: **name**: - Только kebab-case (строчные через дефис) - Без пробелов и заглавных - Должно совпадать с именем папки **description**: - Обязательно содержит две вещи: **что skill делает** и **когда его подключать** - Не больше 1024 символов - Никаких XML-тегов (`<` или `>`) - Перечислите конкретные фразы, которые может сказать пользователь - Укажите типы файлов, если это важно #### Опциональные поля - **license:** лицензия для открытых skills (MIT, Apache-2.0) - **compatibility:** требования к окружению (1-500 символов) - **metadata:** произвольные поля: автор, версия, mcp-server и т.д. #### Ограничения безопасности Во frontmatter запрещены: - XML-угловые скобки (`< >`) - Слова «claude» или «anthropic» в имени skill (зарезервированы) Шапка попадает прямо в системный промпт Claude, поэтому вредоносный контент мог бы подменить инструкции. --- ### Как писать описание Формула: **[Что делает] + [Когда подключать] + [Ключевые возможности]** ✅ Хорошо — конкретно и с триггерами: - Разбирает дизайн-файлы Figma и готовит документацию для передачи разработчикам. Подключать, когда пользователь загружает .fig, просит «спеки по дизайну», «документацию компонентов» или «хендофф дизайна». - Управляет проектами в Linear: планирование спринтов, создание задач, трекинг статусов. Подключать, когда пользователь упоминает «спринт», «задачи Linear», «планирование проекта» или просит «создать тикеты». - Полный онбординг клиентов PayFlow: создание аккаунта, настройка оплаты, управление подпиской. Подключать, когда пользователь просит «заонбордить клиента», «настроить подписку» или «создать аккаунт PayFlow». ❌ Плохо: - Помогает с проектами. - Создаёт системы документации. - Реализует модель Project с иерархическими связями. --- ### Как писать инструкции: После YAML-шапки идёт тело skill, обычный Markdown. Вот рекомендуемый каркас: ````yaml --- name: your-skill description: [...] --- # Название Skill ## Инструкции ### Шаг 1: [Первый шаг] Что конкретно нужно сделать. Пример: ```bash python scripts/fetch_data.py --project-id PROJECT_ID ``` Если всё прошло хорошо: [описание результата] ## Примеры ### Пример 1: [типичная ситуация] Пользователь: "Создай новую маркетинговую кампанию" Действия: 1. Забрать существующие кампании через MCP 2. Создать новую с указанными параметрами Результат: кампания создана, ссылка для подтверждения отправлена ## Если что-то пошло не так Ошибка: [текст ошибки] Почему: [причина] Что делать: [решение] ```` #### Как писать инструкции, которые работают: ✅ Хорошо: конкретно, с примерами ``` Запустите `python scripts/validate.py --input {filename}` для проверки формата. Если не прошло, типичные причины: - Не хватает обязательных полей (допишите в CSV) - Даты в неправильном формате (нужен YYYY-MM-DD) ``` ❌ Плохо: размыто, бесполезно ``` Проверьте данные перед тем как продолжить. ``` Не забывайте про **обработку ошибок** и **ссылки на справочные файлы**. Главное правило: `SKILL.md` содержит суть, а детали выносите в `references/`.