# Skill Writing

> Помогает создавать и структурировать скиллы для Claude Code. Используй когда нужно написать, создать, организовать или отрефакторить скилл. Skill writing, skill creation, create skill, write skill, new skill, author skill.

- Skill: `bbar0n234/skill-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bbar0n234/skill-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bbar0n234/skill-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Bbar0n234 (https://skillmd.com/u/bbar0n234)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bbar0n234/skill-writing

---


# Skill Writing

## Что такое Skills

Skills — специализированные папки с инструкциями, которые Claude автоматически обнаруживает и применяет, когда они релевантны задаче. Это экспертиза в конкретных областях, оформленная как переиспользуемые инструкции.

### Механизм работы

Claude использует **progressive disclosure**:
1. Сначала загружаются только метаданные (~100 токенов)
2. По ним Claude определяет релевантность
3. Полные инструкции загружаются при необходимости

**Ключевое отличие от slash commands:** Skills вызываются автоматически — Claude сам решает на основе description. Slash commands требуют явного вызова `/команда`.

### Приоритеты при конфликте имён

```
managed (enterprise) > personal > project > plugin
```

## Структура скилла

Каждый скилл требует файл `SKILL.md` (регистр важен) с YAML-метаданными и Markdown-инструкциями.

### Обязательные поля

```yaml
---
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) |

### Базовый шаблон

```markdown
---
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 содержит естественные триггеры
- Чёткое разделение ответственности между скиллами

## Формат работы

1. **Пользователь описывает** — полная картина, мысли, требования к скиллу
2. **Изучить контекст** — существующие скиллы, возможные пересечения
3. **Предложить аутлайн** — название, расположение, структура содержания
4. **Получить обратную связь** — доработать по замечаниям
5. **После апрува** — написать финальный скилл

**Важно:** Не писать скилл сразу. Сначала аутлайн, потом апрув.

## Чеклист

- [ ] Проверены существующие скиллы (`~/.claude/skills/`, `.claude/skills/`)
- [ ] Нет пересечений / решено как интегрировать
- [ ] Определено расположение (personal vs project)
- [ ] Название: lowercase, дефисы, ≤64 символа
- [ ] Description содержит ключевые слова для триггера
- [ ] Получен апрув на аутлайн перед написанием

## Troubleshooting

**Скилл не срабатывает:** Проблема в description. Должен быть специфичным и включать слова, которые пользователь естественно использует.

**Скилл не загружается:**
- Проверить путь (регистр: `SKILL.md`, не `skill.md`)
- Проверить YAML-синтаксис (начинается с `---` на строке 1)
- Использовать `claude --debug` для диагностики

## Ссылки

- [Skills Explained (Anthropic Blog)](https://www.claude.com/blog/skills-explained)
- [What are Skills (Support)](https://support.claude.com/en/articles/12512176-what-are-skills)
- [Using Skills in Claude (Support)](https://support.claude.com/en/articles/12512180-using-skills-in-claude)