Навыки

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

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

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

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

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

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

---
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/ содержит глубокие знания о выполнении. Эти файлы загружаются только когда:

Агент явно вызван (через /command или поле skills агента)
Конкретный ресурс нужен для текущего типа и сложности задачи

Загрузка по требованию управляется руководством по загрузке контекста (.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 (условный)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QA-агент​

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