Навыки

---
title: Навыки
description: Полное руководство по двухуровневой архитектуре навыков oh-my-agent — дизайн SKILL.md, загрузка ресурсов по требованию, все общие ресурсы, условные протоколы, типы ресурсов для каждого навыка, вендорные протоколы выполнения, расчёт экономии токенов и механика маршрутизации навыков.
---

# Навыки

Навыки — это структурированные пакеты знаний, которые дают каждому агенту его доменную экспертизу. Это не просто промпты — они содержат протоколы выполнения, справочники по технологическому стеку, шаблоны кода, справочники по ошибкам, чек-листы качества и примеры для обучения, организованные в двухуровневой архитектуре, разработанной для эффективности использования токенов.

---

## Двухуровневый дизайн

### Уровень 1: SKILL.md (~800 байт, всегда загружен)

Каждый навык имеет файл `SKILL.md` в корне. Он всегда загружается в контекстное окно при обращении к навыку. Содержит:

- **YAML-фронтматтер** с `name` и `description` (используется для маршрутизации и отображения)
- **Когда использовать / Когда НЕ использовать** — явные условия активации
- **Основные правила** — 5-15 наиболее критичных ограничений для домена
- **Обзор архитектуры** — как должен быть структурирован код
- **Список библиотек** — утверждённые зависимости и их назначение
- **Ссылки** — указатели на ресурсы Уровня 2 (никогда не загружаются автоматически)

Пример фронтматтера:

```yaml
---
name: oma-frontend
description: Frontend specialist for React, Next.js, TypeScript with FSD-lite architecture, shadcn/ui, and design system alignment. Use for UI, component, page, layout, CSS, Tailwind, and shadcn work.
---
```

Поле description критично — оно содержит ключевые слова маршрутизации, которые система использует для сопоставления задач с агентами.

### Уровень 2: resources/ (загружается по требованию)

Директория `resources/` содержит глубокие знания о выполнении. Эти файлы загружаются только когда:
1. Агент явно вызван (через `/command` или поле skills агента)
2. Конкретный ресурс нужен для текущего типа и сложности задачи

Загрузка по требованию управляется руководством по загрузке контекста (`.agents/skills/_shared/core/context-loading.md`), которое сопоставляет типы задач с необходимыми ресурсами для каждого агента.

---

## Пример файловой структуры

```
.agents/skills/oma-frontend/
├── SKILL.md                          <- Уровень 1: всегда загружен (~800 байт)
└── resources/
    ├── execution-protocol.md         <- Уровень 2: пошаговый рабочий процесс
    ├── tech-stack.md                 <- Уровень 2: детальные спецификации технологий
    ├── tailwind-rules.md             <- Уровень 2: соглашения Tailwind
    ├── component-template.tsx        <- Уровень 2: шаблон React-компонента
    ├── snippets.md                   <- Уровень 2: готовые паттерны кода
    ├── error-playbook.md             <- Уровень 2: процедуры восстановления
    ├── checklist.md                  <- Уровень 2: чек-лист верификации качества
    └── examples/                     <- Уровень 2: примеры для обучения
        └── examples.md

.agents/skills/oma-backend/
├── SKILL.md
├── resources/
│   ├── execution-protocol.md
│   ├── examples.md
│   ├── orm-reference.md              <- Доменный (ORM-запросы, N+1, транзакции)
│   ├── checklist.md
│   └── error-playbook.md
└── stack/                             <- Генерируется через /stack-set
    ├── stack.yaml
    ├── tech-stack.md
    ├── snippets.md
    └── api-template.*

.agents/skills/oma-design/
├── SKILL.md
├── resources/
│   ├── execution-protocol.md
│   ├── anti-patterns.md
│   ├── checklist.md
│   ├── design-md-spec.md
│   ├── design-tokens.md
│   ├── prompt-enhancement.md
│   ├── stitch-integration.md
│   └── error-playbook.md
├── reference/                         <- Глубокие справочные материалы
│   ├── typography.md
│   ├── color-and-contrast.md
│   ├── spatial-design.md
│   ├── motion-design.md
│   ├── responsive-design.md
│   ├── component-patterns.md
│   ├── accessibility.md
│   └── shader-and-3d.md
└── examples/
    ├── design-context-example.md
    └── landing-page-prompt.md
```

---

## Типы ресурсов для каждого навыка

| Тип ресурса | Паттерн имени | Назначение | Когда загружается |
|------------|--------------|-----------|------------------|
| **Протокол выполнения** | `execution-protocol.md` | Пошаговый рабочий процесс: Анализ -> План -> Реализация -> Верификация | Всегда (вместе с SKILL.md) |
| **Технологический стек** | `tech-stack.md` | Детальные спецификации технологий, версии, конфигурация | Сложные задачи |
| **Справочник по ошибкам** | `error-playbook.md` | Процедуры восстановления с эскалацией «3 попытки» | Только при ошибках |
| **Чек-лист** | `checklist.md` | Доменный чек-лист верификации качества | На этапе верификации |
| **Сниппеты** | `snippets.md` | Готовые паттерны кода для копирования | Средние/Сложные задачи |
| **Примеры** | `examples.md` или `examples/` | Примеры вход/выход для обучения LLM | Средние/Сложные задачи |
| **Варианты** | Директория `stack/` | Языко/фреймворко-специфичные справочники | При наличии stack |
| **Шаблоны** | `component-template.tsx`, `screen-template.dart` | Шаблоны файлов | При создании компонентов |
| **Доменные справочники** | `orm-reference.md`, `anti-patterns.md` и т.д. | Глубокие доменные знания | По типу задачи |

---

## Общие ресурсы (_shared/)

Все агенты разделяют общие основы из `.agents/skills/_shared/`. Они организованы в три категории:

### Основные ресурсы (`.agents/skills/_shared/core/`)

| Ресурс | Назначение | Когда загружается |
|--------|-----------|------------------|
| **`skill-routing.md`** | Сопоставляет ключевые слова задач с правильным агентом. Содержит таблицу маппинга навык-агент, паттерны маршрутизации сложных запросов, правила межагентных зависимостей, правила эскалации и руководство по лимитам ходов. | Ссылается оркестратором и навыками координации |
| **`context-loading.md`** | Определяет, какие ресурсы загружать для какого типа задачи и сложности. Содержит таблицы маппинга тип задачи-ресурс для каждого агента и триггеры загрузки условных протоколов. | В начале рабочего процесса (Шаг 0 / Фаза 0) |
| **`prompt-structure.md`** | Определяет четыре элемента каждого промпта задачи: Цель, Контекст, Ограничения, Готово когда. Включает шаблоны для PM, агентов реализации и QA. Перечисляет анти-паттерны. | Ссылается PM-агентом и всеми рабочими процессами |
| **`clarification-protocol.md`** | Определяет уровни неопределённости (LOW/MEDIUM/HIGH) с действиями для каждого. Содержит триггеры неопределённости, шаблоны эскалации и поведение в режиме субагента. | При неоднозначных требованиях |
| **`context-budget.md`** | Управление бюджетом токенов. Определяет стратегию чтения файлов (использовать `find_symbol`, а не `read_file`), бюджеты загрузки ресурсов по уровню модели (Flash: ~3100 / Pro: ~5000 токенов). | В начале рабочего процесса |
| **`difficulty-guide.md`** | Критерии классификации задач как Простая/Средняя/Сложная. Определяет ожидаемое количество ходов и ветвление протокола. | В начале задачи (Шаг 0) |
| **`reasoning-templates.md`** | Структурированные шаблоны рассуждений для типовых паттернов принятия решений. | Во время сложных решений |
| **`quality-principles.md`** | 4 универсальных принципа качества, применяемых всеми агентами. | В начале рабочих процессов, ориентированных на качество |
| **`vendor-detection.md`** | Протокол определения текущей среды выполнения (Claude Code, Codex CLI, Gemini CLI, Antigravity, CLI Fallback). | В начале рабочего процесса |
| **`session-metrics.md`** | Оценка Clarification Debt (CD) и отслеживание метрик сессий. Определяет типы событий, пороги и точки интеграции. | Во время сессий оркестрации |
| **`common-checklist.md`** | Универсальный чек-лист качества для финальной верификации сложных задач. | Этап верификации сложных задач |
| **`lessons-learned.md`** | Репозиторий знаний из прошлых сессий, автогенерируемый из нарушений CD и отброшенных экспериментов. | После ошибок и в конце сессии |
| **`api-contracts/`** | Директория с шаблоном API-контракта и сгенерированными контрактами. | При планировании кросс-доменной работы |

### Рантайм-ресурсы (`.agents/skills/_shared/runtime/`)

| Ресурс | Назначение |
|--------|-----------|
| **`memory-protocol.md`** | Формат файлов памяти и операции для CLI-субагентов. Определяет протоколы При старте, Во время выполнения и При завершении. |
| **`execution-protocols/claude.md`** | Паттерны выполнения для Claude Code. |
| **`execution-protocols/gemini.md`** | Паттерны выполнения для Gemini CLI. |
| **`execution-protocols/codex.md`** | Паттерны выполнения для Codex CLI. |
| **`execution-protocols/qwen.md`** | Паттерны выполнения для Qwen CLI. |

Вендор-специфичные протоколы внедряются автоматически через `oma agent:spawn`.

### Условные ресурсы (`.agents/skills/_shared/conditional/`)

| Ресурс | Условие срабатывания | Примерный объём |
|--------|---------------------|----------------|
| **`quality-score.md`** | Начинается фаза VERIFY или SHIP | ~250 токенов |
| **`experiment-ledger.md`** | Записан первый эксперимент после базовой линии IMPL | ~250 токенов |
| **`exploration-loop.md`** | Один и тот же шлюз дважды проваливается | ~250 токенов |

Суммарное влияние на бюджет: ~750 токенов при загрузке всех 3. Типичные сессии загружают 1-2.

---

## Маршрутизация навыков через skill-routing.md

### Простая маршрутизация (один домен)

Промпт «Build a login form with Tailwind CSS» совпадает с ключевыми словами `UI`, `component`, `form`, `Tailwind` и маршрутизируется на **oma-frontend**.

### Маршрутизация сложных запросов

| Паттерн запроса | Порядок выполнения |
|----------------|-------------------|
| «Create a fullstack app» | oma-pm -> (oma-backend + oma-frontend) параллельно -> oma-qa |
| «Create a mobile app» | oma-pm -> (oma-backend + oma-mobile) параллельно -> oma-qa |
| «Fix bug and review» | oma-debug -> oma-qa |
| «Design and build a landing page» | oma-design -> oma-frontend |
| «I have an idea for a feature» | oma-brainstorm -> oma-pm -> агенты -> oma-qa |
| «Do everything automatically» | oma-orchestrator (внутри: oma-pm -> агенты -> oma-qa) |

### Правила межагентных зависимостей

**Могут работать параллельно (без зависимостей):**
- oma-backend + oma-frontend (когда API-контракт предопределён)
- oma-backend + oma-mobile (когда API-контракт предопределён)
- oma-frontend + oma-mobile (независимы)

**Должны работать последовательно:**
- oma-brainstorm -> oma-pm (дизайн перед планированием)
- oma-pm -> все остальные агенты (планирование в первую очередь)
- агент реализации -> oma-qa (ревью после реализации)
- oma-backend -> oma-frontend/oma-mobile (без предопределённого API-контракта)

**QA всегда последний**, кроме ревью конкретных файлов.

---

## Расчёт экономии токенов

Сессия оркестрации с 5 агентами (pm, backend, frontend, mobile, qa):

**Без прогрессивного раскрытия:**
- Каждый агент загружает все ресурсы: ~4000 токенов на агента
- Итого: 5 x 4000 = 20 000 токенов до начала работы

**С прогрессивным раскрытием:**
- Только Уровень 1 для всех агентов: 5 x 800 = 4000 токенов
- Уровень 2 для активных агентов (1-2 одновременно): +1500 токенов
- Итого: ~5500 токенов

**Экономия: примерно 72-75%**

На моделях flash-уровня (128K) это разница между 108K и 125K доступных токенов.

---

## Загрузка ресурсов по сложности задачи

### Простая (3-5 ходов)

Изменение одного файла, чёткие требования, повторение существующих паттернов.

Загружается: только `execution-protocol.md`. Пропустить анализ, сразу к реализации.

### Средняя (8-15 ходов)

2-3 изменения файлов, некоторые дизайн-решения.

Загружается: `execution-protocol.md` + `examples.md`. Стандартный протокол с кратким анализом.

### Сложная (15-25 ходов)

4+ изменений файлов, архитектурные решения, зависимости от других агентов.

Загружается: `execution-protocol.md` + `examples.md` + `tech-stack.md` + `snippets.md`. Расширенный протокол с контрольными точками.

---

## Карты загрузки контекста (по агентам)

### Бэкенд-агент

| Тип задачи | Необходимые ресурсы |
|-----------|-------------------|
| Создание CRUD API | stack/snippets.md (route, schema, model, test) |
| Аутентификация | stack/snippets.md (JWT, password) + stack/tech-stack.md |
| Миграция БД | stack/snippets.md (migration) |
| Оптимизация производительности | examples.md (пример N+1) |
| Модификация существующего кода | examples.md + Serena MCP |

### Фронтенд-агент

| Тип задачи | Необходимые ресурсы |
|-----------|-------------------|
| Создание компонента | snippets.md + component-template.tsx |
| Реализация формы | snippets.md (form + Zod) |
| Интеграция с API | snippets.md (TanStack Query) |
| Стилизация | tailwind-rules.md |
| Макет страницы | snippets.md (grid) + examples.md |

### Дизайн-агент

| Тип задачи | Необходимые ресурсы |
|-----------|-------------------|
| Создание дизайн-системы | reference/typography.md + reference/color-and-contrast.md + reference/spatial-design.md + design-md-spec.md |
| Дизайн лендинга | reference/component-patterns.md + reference/motion-design.md + prompt-enhancement.md + examples/landing-page-prompt.md |
| Аудит дизайна | checklist.md + anti-patterns.md |
| Экспорт дизайн-токенов | design-tokens.md |
| 3D / шейдерные эффекты | reference/shader-and-3d.md + reference/motion-design.md |
| Обзор доступности | reference/accessibility.md + checklist.md |

### QA-агент

| Тип задачи | Необходимые ресурсы |
|-----------|-------------------|
| Обзор безопасности | checklist.md (раздел Security) |
| Обзор производительности | checklist.md (раздел Performance) |
| Обзор доступности | checklist.md (раздел Accessibility) |
| Полный аудит | checklist.md (полный) + self-check.md |
| Оценка качества | quality-score.md (условный) |

---

## Компоновка промпта оркестратором

Когда оркестратор составляет промпты для субагентов, он включает только релевантные ресурсы:

1. Раздел основных правил из SKILL.md агента
2. `execution-protocol.md`
3. Ресурсы, соответствующие типу задачи (из карт выше)
4. `error-playbook.md` (всегда включён)
5. Serena Memory Protocol (режим CLI)

Такая целевая компоновка максимизирует доступный контекст субагента для реальной работы.