# Что такое skills

← [Раздел](README.md) · [Главная](../README.md)

## Цель

Разобрать **анatomy skill**: структура каталога, frontmatter, тело инструкции, optional scripts.

## Предварительно

- [05 — Skills](README.md)

## Время

**50–70 минут**

---

## Структура каталога skill

```
skill-name/
├── SKILL.md              # обязательно
├── reference.md          # опционально — детали
├── examples.md           # опционально — примеры
└── scripts/              # опционально — утилиты
    └── validate.sh
```

Минимум для работы — только **`SKILL.md`**.

---

## Frontmatter SKILL.md

```yaml
---
name: tdd-workflow
description: Use when writing new features, fixing bugs, or refactoring. Enforces TDD with 80%+ coverage.
origin: ECC
---
```

| Поле | Назначение |
|------|------------|
| `name` | Идентификатор (kebab-case) |
| `description` | **Главный триггер** — когда агент должен применить skill |
| `disable-model-invocation` | (опционально) только явный вызов пользователем |
| `origin` | Метаданные (ECC, custom) |

Качество `description` = частота правильного auto-activation.

---

## Тело skill: рекомендуемые секции

1. **Заголовок** — название workflow.
2. **When to Activate** — триггеры (дублируют/расширяют description).
3. **Core Principles** — не negotiable правила процесса.
4. **Steps** — нумерованный алгоритм.
5. **Checklist** — перед завершением.
6. **Anti-patterns** — чего не делать в этом workflow.

Пример из ECC `tdd-workflow`: Tests BEFORE Code, 80% coverage, unit + integration + E2E.

---

## Длинные skills

ECC skills могут быть **большими** (400+ строк) — это нормально для skill, потому что он **не always-on**, в отличие от rules. Всё равно:

- выносите справочник в `reference.md`;
- scripts — в `scripts/`, не в простыню bash внутри SKILL.md.

---

## Skills с hooks и scripts

Некоторые ECC skills сложнее текста:

- `continuous-learning-v2` — hooks `observe.sh`, agents observer;
- `skill-stocktake` — shell scripts scan;
- `configure-ecc` — install pipeline.

Для начала достаточно **текстового** skill; scripts добавляйте, когда workflow повторяется mechanically.

---

## Activation flow

```mermaid
flowchart TD
  U[Запрос пользователя]
  U --> M{description match?}
  M -->|да| L[Load SKILL.md]
  M -->|нет| R[Только rules + промпт]
  L --> E[Execute steps]
  E --> C[Checklist]
```

Явное `@skill-name` или фраза «follow tdd-workflow» обходит неоднозначность match.

---

## Built-in vs ECC vs custom

| Источник | Пример |
|----------|--------|
| Cursor built-in | `create-skill`, `create-rule` в skills-cursor |
| ECC | `fastapi-patterns`, `react-patterns` |
| Ваш | `.cursor/skills/team-deploy/SKILL.md` |

Built-in не редактируйте — создавайте **свои** рядом.

---

## Skill и контекст

Skill загружается **порциями** при активации — всё равно не вставляйте в SKILL.md целые книги. Ссылка «см. reference.md» + `@` при необходимости.

ECC `iterative-retrieval` учит агента доставать контекст итеративно — meta-skill для больших задач.

---

## Практика: разбор чужого skill

1. Найдите в ECC `.cursor/skills/error-handling/SKILL.md`.
2. Выпишите: name, description, 3 core principles, checklist.
3. Отметьте, что можно было бы вынести в rule (если always true).

---

## Самопроверка

1. Какой файл обязателен в каталоге skill?
2. Какое поле frontmatter главное для auto-activation?
3. Почему skill может быть длиннее rule?
4. Чем built-in skills-cursor отличаются от project skills?

## Дальше

→ [Когда использовать skill](kogda-ispolzovat-skill.md)