# Описание Yao Meta Skill

`YAO = Yielding AI Outcomes` означает ориентацию на реальные результаты от ИИ. Цель здесь не в том, чтобы написать больше prompt-текста, а в том, чтобы получать переиспользуемые AI-активы и прикладные операционные результаты.

`yao-meta-skill` — это легкая, но строгая система для создания, оценки, упаковки и управления переиспользуемыми agent skills.

Он преобразует сырые workflows, transcripts, prompts, notes и runbooks в переиспользуемые skill-пакеты с:

- понятной поверхностью срабатывания
- компактным `SKILL.md`
- необязательными references, scripts и evals
- более человечным коротким intent dialogue перед глубокой разработкой, с intent confidence gate: если реальная работа, результат, exclusions или стандарты все еще неясны, система продолжает уточнять
- silent-by-default GitHub benchmark scan и reference synthesis до глубокого authoring: система изучает сильные публичные репозитории и world-class pattern tracks, а пользователю явно показывает только реальные конфликты или неопределенность
- явным запросом пользовательских референсов, если они есть, чтобы перенимать паттерны, структуру и стандарты качества, а не копировать формулировки или приватный материал
- автоматически создаваемым минималистичным HTML-обзором на белом фоне для каждого нового skill
- prompt quality profile, который превращает need model, RTF mapping, complexity и prompt-facing quality checks в видимые для reviewer доказательства, не раздувая `SKILL.md`
- тремя наиболее ценными направлениями следующей итерации после первого создания
- компактным HTML review viewer для быстрой первой ручной оценки
- легким feedback log, чтобы не запускать полный promotion flow на каждом цикле
- отчетом with-skill vs baseline для быстрого сравнения инкрементальной пользы
- conversation-style archetype-aware quickstart, который ведет пользователя как discovery flow и помогает выбрать scaffold, production, library или governed форму
- нейтральными исходными метаданными и клиентскими адаптерами
- встроенными проверками governance, promotion и portability в стандартном потоке

## Архитектура

В hero-версии вся система сводится к одной линии: превратить разрозненный вход в управляемый и переиспользуемый skill package.

```mermaid
flowchart LR
    A["Входы<br/>workflow / prompt / transcript / docs / notes"] --> B["Маршрут<br/>SKILL.md"]
    B --> C["Проектирование<br/>method + gates"]
    C --> D["Исполнение<br/>create / validate / eval / promote"]
    D --> E["Выходы<br/>skill package + reports + adapters"]
```

Как читать это за 10 секунд:

- **Входы**: стартуем с workflow, prompt, документов и заметок.
- **Маршрут**: компактный `SKILL.md` сначала задает границу и trigger.
- **Проектирование**: выбираются нужные archetype, quality gates и разбиение ресурсов.
- **Исполнение**: единый CLI создает, проверяет, оптимизирует и продвигает skill.
- **Выходы**: результатом становится skill package плюс доказательства оценки, governance и portability.

## Взвешенный quality benchmark

Это инженерная оценка проекта. Каждое измерение оценивается по шкале `0-10`, затем пересчитывается в `100` баллов с учетом веса. GitHub stars не включаются, потому что они отражают популярность экосистемы, а не инженерное качество meta-skill.

Формула взвешенного балла: `sum(score / 10 * weight)`.

| Meta Skill | Методология 15 | Context discipline 10 | Toolchain 15 | Eval/tests 20 | Governance 15 | Portability 10 | Onboarding/review 5 | Local reliability 10 | Weighted score |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| Yao Meta Skill | 9.5 | 8.0 | 9.5 | 9.5 | 9.5 | 9.0 | 6.5 | 9.5 | 91.5 |
| Anthropic Skill Creator | 9.0 | 6.5 | 8.5 | 7.5 | 4.0 | 5.0 | 7.5 | 5.0 | 67.5 |
| OpenAI Skill Creator | 8.5 | 9.5 | 5.0 | 2.0 | 3.0 | 4.0 | 8.5 | 4.0 | 50.5 |

| Место | Meta Skill | Балл | Основное позиционирование |
| ---: | --- | ---: | --- |
| 1 | Yao Meta Skill | 91.5 | Полная система engineering, evaluation, governance и portability для переиспользуемых skills. |
| 2 | Anthropic Skill Creator | 67.5 | Сильная методология и итерационный цикл, но слабее local execution reliability и governance coverage. |
| 3 | OpenAI Skill Creator | 50.5 | Лучше как краткое руководство по написанию skills, чем как полноценная engineering system. |

## Подходящие сценарии

- Выбирайте **Yao Meta Skill**, если нужен командный переиспользуемый актив с явными границами, evaluation gates, governance, portability и долгосрочной поддержкой.
- Выбирайте **Anthropic Skill Creator**, если вам важнее conversation-first creation loop и итерация с сильным human guidance.
- Выбирайте **OpenAI Skill Creator**, если вам нужен краткий reference по написанию lean skills и context discipline.
- Практичный гибридный вариант: сначала получить первый черновик через conversation-driven creator, а затем использовать `yao-meta-skill`, чтобы усилить пакет и сделать его team-ready.

## Быстрый старт

1. Опишите workflow, набор prompts или повторяющуюся задачу, которую хотите превратить в skill.
2. Сначала проведите короткий, но более человечный intent dialogue, чтобы уточнить реальную job-to-be-done, outputs, exclusions, constraints и те стандарты качества, которые для вас важны.
3. Сначала позвольте `quickstart` прояснить намерение, затем тихо выполнить benchmark scan и reference synthesis. Явные уточнения поднимаются только тогда, когда intent все еще неясен или между маршрутами проектирования есть реальный конфликт.
4. Используйте archetype-aware `quickstart` или полный authoring flow, чтобы сгенерировать или улучшить пакет в режиме scaffold, production, library или governed.
5. Каждый новый skill также получает `reports/intent-dialogue.md`, `reports/intent-confidence.md`, `reports/reference-synthesis.md`, `reports/artifact-design-profile.md`, `reports/prompt-quality-profile.md`, `reports/skill-overview.html`, `reports/review-viewer.html` и `reports/iteration-directions.md`. После этого feedback log и baseline compare позволяют запускать короткий цикл улучшений без полного promotion flow.

## Текущие результаты

- `make test` сейчас проходит
- на текущем regression-наборе trigger eval дает `0` false positives и `0` false negatives
- все три набора train / dev / holdout проходят
- реальные китайские формулировки теперь включены в trigger eval, например `做一个 skill`, `沉淀成可复用能力`, `优化已有 skill`, `补 trigger 评测`
- packaging contracts для `openai`, `claude` и `generic` проходят проверку

## Текущие сильные стороны

В последней взвешенной оценке Yao набирает `91.5/100`. Его сильные стороны сосредоточены в том, что нужно для долговечных командных skill-активов:

- **Глубина методологии `9.5`**: формальная skill engineering doctrine, archetypes, gate selection, non-skill decisions, governance и resource boundaries.
- **Полнота toolchain `9.5`**: initialization, validation, benchmark scan, description optimization, reporting, promotion checks, packaging, CI и portability checks связаны в один operational flow.
- **Строгость Eval / tests `9.5`**: train/dev/holdout, blind holdout, adversarial holdout, judge-backed blind eval, route confusion, drift history и promotion gates покрыты.
- **Governance / lifecycle `9.5`**: важные skills могут иметь owner, lifecycle, review cadence, maturity score, trust boundary, promotion decision и regression history.
- **Local execution reliability `9.5`**: репозиторий проверяется локально через `make test`, `make ci-test` и unified CLI.
- **Portability / distribution `9.0`**: neutral metadata, adapters, degradation rules, packaging contracts и portability score сохраняют переносимую семантику между средами.
- **Context discipline `8.0`**: entrypoint остается в рамках budget, но эта метрика отслеживается как живое ограничение, потому что система несет больше reports, examples, benchmark assets и evidence.
- **Onboarding / review experience `6.5`**: quickstart, HTML overview, side-by-side review viewer и feedback log улучшили первый опыт, но это все еще главный UX-направление для улучшения.

Общий вектор здесь осознанный: легкий вход, сложная для имитации evaluation, видимая governance и снижение трения первого создания и ручного review.

## Почему Yao

- **Легкий**: entrypoint остается компактным, context budgets заданы явно, а дополнительная структура добавляется только тогда, когда она действительно окупается.
- **Строгий**: качество trigger проверяется через family regressions, blind holdout, adversarial holdout, route confusion, judge-backed blind eval и promotion gates.
- **Управляемый**: важные skills рассматриваются как поддерживаемые активы с lifecycle, maturity expectation, owner и review cadence.
- **Портируемый**: source metadata остается нейтральной, а adapters, degradation rules и packaging contracts сохраняют переносимую семантику между средами.

## Что делает проект

Этот проект помогает создавать, перерабатывать, оценивать и упаковывать skills как долговечные capability-пакеты, а не как одноразовые prompts.

Его логика проста:

1. определить реальную повторяющуюся задачу за пользовательским запросом
2. задать чистую границу skill, чтобы один пакет решал одну связанную задачу
3. оптимизировать trigger description до того, как раздувать основное тело
4. держать основной файл маленьким, а детали переносить в references или scripts
5. добавлять quality gates только тогда, когда они действительно окупаются
6. экспортировать compatibility artifacts только для реально нужных клиентов

## Зачем нужен этот проект

У большинства команд важные операционные знания разбросаны по чатам, личным prompts, устным привычкам и недокументированным workflows. Этот проект превращает такое скрытое знание в:

- обнаруживаемые skill-пакеты
- повторяемые execution flows
- инструкции с меньшей нагрузкой на контекст
- переиспользуемые командные активы
- готовые к совместимости дистрибутивы

## Структура репозитория

```text
yao-meta-skill/
├── SKILL.md
├── README.md
├── LICENSE
├── .gitignore
├── agents/
│   └── interface.yaml
├── references/
├── scripts/
└── templates/
```

## Ключевые компоненты

### `SKILL.md`

Главная точка входа skill. Здесь задаются surface trigger, operating modes, compact workflow и output contract.

### `agents/interface.yaml`

Нейтральный единый источник метаданных. Он хранит display и compatibility metadata, не привязывая дерево исходников к vendor-specific path.

### `references/`

Длинные материалы, которые не должны раздувать основной skill-файл. Здесь находятся design rules, evaluation guidance, compatibility strategy и quality rubrics.

### `scripts/`

Утилиты, которые делают meta-skill по-настоящему рабочей:

- `trigger_eval.py`: проверяет, не слишком ли широкая или слабая trigger description
- `context_sizer.py`: оценивает вес контекста и предупреждает, если initial load становится слишком большим
- `cross_packager.py`: собирает client-specific export artifacts из нейтрального исходного пакета

### `templates/`

Стартовые шаблоны для простых и более сложных skill-пакетов.

## Как использовать

### 1. Использовать skill напрямую

Вызывайте `yao-meta-skill`, когда хотите:

- создать новую skill
- улучшить существующую skill
- добавить evals в skill
- превратить workflow в переиспользуемый пакет
- подготовить skill для более широкого использования в команде

### 2. Сгенерировать новый skill-пакет

Типичный поток:

1. описать workflow или capability
2. определить trigger phrases и expected outputs
3. выбрать режим scaffold, production или library
4. сгенерировать пакет
5. при необходимости запустить size и trigger checks
6. экспортировать targeted compatibility artifacts

### 3. Экспортировать compatibility artifacts

Примеры:

```bash
python3 scripts/cross_packager.py ./yao-meta-skill --platform openai --platform claude --zip
python3 scripts/context_sizer.py ./yao-meta-skill
python3 scripts/trigger_eval.py --description "Create and improve agent skills..." --cases ./cases.json
```

## Преимущества

- **Сначала метод, а не просто prompt**: skill creation рассматривается как формальный engineering workflow
- **Ориентация на trigger optimization**: description проходит через route confusion, blind holdout, adversarial families и promotion policy
- **Легкий entrypoint**: `SKILL.md` остается компактным, а references, scripts и evals добавляются только когда действительно нужны
- **Цельная toolchain**: init, validate, optimize, report, package и test проходят через единый CLI и CI path
- **Управляется как актив**: важные skills могут иметь owner, lifecycle, maturity expectation и review cadence
- **Портируемость по умолчанию**: исходники нейтральны, а совместимость обрабатывается через adapters и degradation rules
- **Высокая плотность доказательств**: route scorecards, regression history, context budgets, portability scores и promotion decisions публикуются как артефакты

## Для кого подходит

Проект лучше всего подходит для:

- agent builders
- команд внутреннего tooling
- prompt engineers, переходящих к skill engineering
- организаций, создающих библиотеки переиспользуемых skills

## Лицензия

MIT. См. [LICENSE](../LICENSE).