Bbar0n234 Skill Writing
Что такое Skills
Skills — специализированные папки с инструкциями, которые Claude автоматически обнаруживает и применяет, когда они релевантны задаче. Это экспертиза в конкретных областях, оформленная как переиспользуемые инструкции.
Механизм работы
Claude использует progressive disclosure:
- Сначала загружаются только метаданные (~100 токенов)
- По ним Claude определяет релевантность
- Полные инструкции загружаются при необходимости
Ключевое отличие от slash commands: Skills вызываются автоматически — Claude сам решает на основе description. Slash commands требуют явного вызова /команда.
Приоритеты при конфликте имён
managed (enterprise) > personal > project > plugin
Структура скилла
Каждый скилл требует файл SKILL.md (регистр важен) с YAML-метаданными и Markdown-инструкциями.
Обязательные поля
---
name: your-skill-name # lowercase, цифры, дефисы. Макс 64 символа
description: > # Макс 1024 символа
Что делает скилл и когда использовать.
Включи ключевые слова для триггера.
---
Критично: Description определяет когда Claude применит скилл. Должен содержать ключевые слова, которые пользователь естественно использует.
Опциональные поля
| Поле | Назначение |
|---|---|
allowed-tools |
Инструменты без запроса разрешения при активном скилле |
model |
Конкретная модель для использования |
context: fork |
Запуск в отдельном sub-agent контексте |
agent |
Тип агента при context: fork |
hooks |
Хуки в жизненном цикле скилла |
user-invocable |
Видимость в меню slash commands (default: true) |
Базовый шаблон
---
name: example-skill
description: >
Краткое описание назначения.
Используй когда [конкретные триггеры].
---
# Название скилла
## Инструкции
[Чёткие пошаговые указания для Claude]
## Примеры
[Конкретные примеры применения]
Расположения
| Тип | Путь | Доступность |
|---|---|---|
| Personal | ~/.claude/skills/ |
Тебе, во всех проектах |
| Project | .claude/skills/ |
Всем в репозитории |
Когда что выбирать
- Personal — универсальные практики, личные предпочтения, инструменты для всех проектов
- Project — специфика конкретного репозитория, командные соглашения
Многофайловые скиллы
Для сложных скиллов можно выносить детальную документацию в отдельные файлы:
skill-name/
├── SKILL.md # Основные инструкции
├── REFERENCE.md # Детальная документация (при необходимости)
└── scripts/ # Утилиты (выполняются без загрузки в контекст)
Использовать когда есть реальная потребность, не заранее.
Принципы работы
1. Изучить существующие скиллы
Перед созданием проверить:
~/.claude/skills/— личные.claude/skills/— проектные
2. Не дублировать
При пересечении:
- Мержить скиллы
- Или выстраивать иерархию (один скилл ссылается на другой)
- Или адаптировать существующий
3. Семантическая чистота
- Название отражает суть
- Description содержит естественные триггеры
- Чёткое разделение ответственности между скиллами
Формат работы
- Пользователь описывает — полная картина, мысли, требования к скиллу
- Изучить контекст — существующие скиллы, возможные пересечения
- Предложить аутлайн — название, расположение, структура содержания
- Получить обратную связь — доработать по замечаниям
- После апрува — написать финальный скилл
Важно: Не писать скилл сразу. Сначала аутлайн, потом апрув.
Чеклист
- Проверены существующие скиллы (
~/.claude/skills/,.claude/skills/) - Нет пересечений / решено как интегрировать
- Определено расположение (personal vs project)
- Название: lowercase, дефисы, ≤64 символа
- Description содержит ключевые слова для триггера
- Получен апрув на аутлайн перед написанием
Troubleshooting
Скилл не срабатывает: Проблема в description. Должен быть специфичным и включать слова, которые пользователь естественно использует.
Скилл не загружается:
- Проверить путь (регистр:
SKILL.md, неskill.md) - Проверить YAML-синтаксис (начинается с
---на строке 1) - Использовать
claude --debugдля диагностики