yao-meta-skill/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://gitea-dev.autobee.pro/frostbyte_neo/yao-meta-skill) · [上游 README](https://gitea-dev.autobee.pro/frostbyte_neo/yao-meta-skill/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# Yao Meta Skill

[![CI](https://github.com/yaojingang/yao-meta-skill/actions/workflows/test.yml/badge.svg)](https://github.com/yaojingang/yao-meta-skill/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)
[![English](https://img.shields.io/badge/Docs-English-black)](README.md)
[![中文](https://img.shields.io/badge/Docs-%E4%B8%AD%E6%96%87-red)](docs/README.zh-CN.md)
[![日本語](https://img.shields.io/badge/Docs-%E6%97%A5%E6%9C%AC%E8%AA%9E-blue)](docs/README.ja-JP.md)
[![Français](https://img.shields.io/badge/Docs-Fran%C3%A7ais-green)](docs/README.fr-FR.md)
[![Русский](https://img.shields.io/badge/Docs-%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9-purple)](docs/README.ru-RU.md)

`YAO` 代表 `Yielding AI Outcomes`：目标不是生成更多提示文本，而是产出可复用的 AI 资产与真实的运营成果。

`yao-meta-skill` 负责创建、评估、打包和治理可复用的 agent skills（智能体技能）。1.0 系列专注于将重复工作流转化为可安装、可读、跨平台的 skill 包。2.0 系列将该工厂扩展为 Skill OS：一个受治理的系统，用于一次建模技能、为多个目标编译、测试其行为、审查发布证据，并跟踪下一轮迭代。

[快速开始](#quick-start) · [Skill OS 2.0](#skill-os-20-upgrade) · [1.0 对比 2.0](#from-10-to-20) · [运维体验](#operator-ux-commands) · [基准测试](#weighted-quality-benchmark) · [示例](examples/README.md) · [评测](evals/README.md) · [失败库](failures/README.md) · [方法信条](#method-doctrine)

## Skill OS 2.0 升级

Skill OS 2.0 保留了 `yao-meta-skill` 的原有承诺，但使包生命周期更加明确。它不再止步于 `SKILL.md`，而是在 skill 周围增加了语义契约、目标编译器、评估证据、发布门禁和运营报告。

- **Skill IR**：面向意图、触发器、输入、输出、边界、引用和预期产物的平台中立中间表示（intermediate representation）。
- **目标编译器与适配器**：为 OpenAI、Claude、通用 agent skills、Agent Skills 兼容包以及面向 VS Code 的工作流生成对应表面。
- **Output Eval Lab**：触发器检查、输出断言、执行证据、时序与 token 证据、基准可复现性、盲审包、答案密钥和裁决报告。
- **Review Studio 2.0**：单一 HTML 门禁页面，涵盖意图、触发器、输出评测、上下文成本、运行时检查、信任、Skill Atlas 信号、采用漂移、豁免、批注、发布证据、警告、阻塞项和修复操作。
- **证据与发布治理**：证据一致性检查、包验证、安装模拟、运行时权限探测、世界级证据 intake、世界级台账、运维 runbook 和公开声明守卫。
- **SkillOps 循环**：仅元数据的采用漂移、遥测钩子、自适应提案、每日与每周策展人报告，以及组合级漂移信号。

当前态势：仓库已准备好进行 beta 和外部测试，而更强的公开「世界级」声明仍受证据门禁约束。由提供商支撑的生产证据、人工盲审证据、原生权限执行和真实客户端遥测，均作为独立的证据任务进行跟踪，而非视为已完成工作。

请参阅配套产物：

- [1.0 与 2.0 可视化对比报告](.previews/yao-meta-skill-2-comparison/index.html)
- [中文桌面预览](.previews/yao-meta-skill-2-comparison/yao-meta-skill-1-vs-2.png)
- [英文桌面预览](.previews/yao-meta-skill-2-comparison/yao-meta-skill-1-vs-2-en.png)

## 从 1.0 到 2.0

| 维度 | 1.0 重点 | 2.0 升级 |
| --- | --- | --- |
| 产品角色 | 创建、重构、评估和打包可复用 skills。 | 治理 skill 的完整生命周期：创建、编译、评估、审查、发布、遥测和迭代。 |
| 架构 | `SKILL.md`、`agents/interface.yaml`、清单文件和报告产物。 | Skill IR、目标编译器、适配器、门禁契约、证据台账、发布锁和操作导向的审查页面。 |
| 跨平台交付 | OpenAI、Claude 和通用包目标。 | 增加更广泛的 Agent Skills 与面向 VS Code 的兼容性，并提供注册表可读的兼容性记录。 |
| 质量模型 | 触发器与结构检查，以及基于报告的审查。 | 输出评测、基准可复现性、执行证据、失败披露、盲审包和证据一致性检查。 |
| 报告体验 | 概览 HTML 和首轮审查页面。 | 双语 Skill Overview v2、Review Studio 2.0、审查者批注、操作卡片、图表和面向审计的报告契约。 |
| 发布边界 | 带基础验证的包输出。 | 包验证、安装模拟、运行时权限探测、发布锁、公开声明守卫和运维 runbook。 |
| 运营循环 | 人工反馈与本地迭代。 | 采用漂移、元数据遥测、SkillOps 报告、自适应提案和组合级漂移检测。 |

## 2.0 使用场景

- **从重复工作中创建新 skill**：从工作流笔记、提示集、对话记录、runbook 或文档模式入手，生成带有精简入口点、明确输入输出、引用、报告和最轻量合理门禁的包。
- **将个人 skill 升级为团队资产**：在他人依赖该 skill 之前，添加接口契约、清单、目标适配器、信任检查、输出评测、审查者豁免、发布说明和 Review Studio 证据。
- **为 beta 发布准备 skill**：运行包验证、安装模拟、兼容性检查、运行时权限探测和证据一致性检查，然后将 beta 就绪度与更强的公开声明区分开。
- **在发布后保持 skill 可用**：使用仅元数据遥测、采用漂移、反馈日志、SkillOps 报告和自适应提案，决定下一步应是文档、评测、skill 补丁还是治理更新。
- **与其他 meta-skill 方案对比**：在适用处保留 Anthropic/OpenAI 风格的对话式创建和精简指令编写，当包需要证据、可移植性、发布门禁和可重复维护时，再使用 `yao-meta-skill`。

## 运维体验命令

这些只读辅助命令将常见的维护者问题转化为可重复的诊断：

```bash
python3 scripts/yao.py install-status --expected-source .
python3 scripts/yao.py localized-doc-sync-check
python3 scripts/yao.py pr-review-report 4 --repo yaojingang/yao-meta-skill
```

- `install-status` 说明当前活跃的 skill 来自 `.codex/skills`、`.agents/skills` 还是已禁用的镜像，并标记重复的活跃安装。
- `localized-doc-sync-check` 验证中文 README 是否包含已添加到英文 README 的公开首页章节。
- `pr-review-report` 读取 GitHub PR 元数据、变更文件、状态检查和建议的本地命令，而不会合并或修改 PR。

## 能力表面

它将粗糙的工作流、对话记录、提示、笔记和 runbook 转化为可复用的 skill 包，具备：

- 清晰的触发器表面
- 精简的 `SKILL.md`
- 可选的引用、脚本和评测
- 前置的意图对话与意图置信度门禁，当真实任务、输出、排除项或标准仍模糊时，系统会持续澄清
- 默认静默的 GitHub 基准扫描与参考综合，研究顶级公开仓库和世界级模式轨道，仅向用户呈现真实冲突或不确定性
- 为每个新初始化的 skill 生成可视化 HTML 概览
- 结合意图、触发器、输出评测、上下文、运行时、信任、atlas、采用漂移、审查者豁免、审查者批注、发布证据和逐条警告修复操作的 Review Studio 2.0 HTML 门禁页面
- 将每项世界级要求映射到当前证据、需人工补齐的缺口和需外部补齐的缺口的 Skill OS 2.0 审计
- 将升级计划的核心模块与推荐 PR 映射到具体产物、命令和测试的 Skill OS 2.0 蓝图覆盖报告
- 将剩余的提供商、人工、原生权限和真实客户端遥测缺口转化为可执行证据任务的世界级证据计划
- 记录哪些外部与人工证据已被接受或仍待处理、且不将计划工作视为证明的世界级证据台账
- 在台账审查前，验证外部与人工证据包的来源、隐私、产物引用和防过度声明规则的世界级证据 intake 契约
- 检查本地文件、环境就绪度、人工/外部前置条件和来源阻塞项的脱敏世界级预检报告，供运维人员收集证据前使用
- 比较证据包、intake 验证、来源产物和台账状态、但不接受证据的世界级提交审查队列
- 为审查者提供关闭剩余证据缺口所需的确切命令、产物和收集清单的世界级运维 runbook
- 扫描公开声明表面，并在证据台账仍有待处理的外部或人工证据时阻止过早的 completed/true 声明的世界级声明守卫
- 检查方法论章节、必需产物、失败披露和复现命令的基准可复现性清单
- 比较各生成报告之间的一致性，使基准、概览、解读、采用、世界级台账、覆盖率和 Review Studio 事实不会悄然漂移的证据一致性门禁
- 带有断言评分、执行/时序/token 证据、盲审 A/B 审查包、独立答案密钥和审查者裁决报告的 Output Eval Lab 证据
- 检查打包目标适配器的显式权限元数据、原生强制执行标志、元数据回退说明和残余风险的运行时权限探测报告
- 在语法隐患进入 GitHub Actions 或打包分发前捕获受支持运行时语法风险点的 Python 兼容性门禁
- 用于首轮人工审查的并排 HTML review studio
- 为报告、教程、仪表板、截图和审查页面定义视觉方向、布局模式和质量门禁的产物设计 profile
- 将需求建模、RTF 映射、复杂度和质量检查抽象为审查者可见证据、而非膨胀 `SKILL.md` 的提示质量 profile
- 映射边界、反馈循环、漂移风险、反复出现的失败模式和最高杠杆质量举措的系统思维模型
- 首个包创建后的三个高价值下一轮迭代方向
- 无需完整晋升周期的轻量反馈日志
- 将真实使用信号转化为下一轮迭代候选的本地优先、仅元数据采用与漂移报告，可选 `yao.py` CLI 运行捕获、外部客户端事件发射钩子、钩子配方和 JSONL 导入，记录命令名称与结果但不记录参数或原始内容
- 汇总脱敏的重复用户偏好并生成需审批的自适应提案、且不扫描私有日志或写入源文件的显式来源自适应提案循环
- 对脱敏重复信号排序、映射到仅报告、AGENTS 更新、现有 skill 补丁或评测增补操作，并使每项持久化写入均需审批的 SkillOps 机会评分器与决策策略
- 聚合每日机会、Skill Atlas 组合信号、发布锁状态和世界级证据缺口为仅提案维护队列的每周 SkillOps 策展人报告
- 可接收长度前缀的仅元数据客户端事件并生成本地启动器与清单、但不存储原始内容的 Browser/Chrome Native Messaging 遥测宿主
- 读取聚合采用报告并呈现组合级漂移信号、但不打包原始遥测日志的 Skill Atlas 漂移层
- 有 skill 与基线审查对比的基线比较报告
- 引导新包走向脚手架、生产、库或受治理适配的对话式、原型感知快速开始
- 作为平台中立语义契约的 Skill IR，以及编译器报告和客户端特定适配器
- 包含包版本、所有者、许可证、校验和和兼容性矩阵的注册表审计元数据
- 内置于默认流程的治理、晋升和可移植性检查

## Architecture

核心视角：Skill OS 2.0 通过「建模、编译、评估、发布、运营」闭环，将杂乱的运营输入转化为受治理、可复用的技能包。

```mermaid
flowchart LR
    A["Inputs<br/>workflow / prompt / transcript / docs / notes"] --> B["Intent model<br/>job / outputs / exclusions / standards"]
    B --> C["Skill IR<br/>trigger / contracts / resources / evidence"]
    C --> D["Skill package<br/>SKILL.md / references / scripts / reports"]
    C --> E["Target compilers<br/>OpenAI / Claude / generic / Agent Skills / VS Code"]
    D --> F["Eval Lab<br/>trigger / output / benchmark / runtime"]
    E --> F
    F --> G["Review Studio<br/>gates / warnings / actions / waivers"]
    G --> H["Release boundary<br/>package verification / install simulation / claim guard"]
    H --> I["SkillOps loop<br/>feedback / adoption drift / next iteration"]
    I --> B
```

10 秒速览：

- **输入（Inputs）**：从粗糙的运营素材出发，而非一份精修过的规格说明。
- **意图模型（Intent model）**：在生成文件之前，将工作任务、输出、排除项、约束和标准明确化。
- **技能 IR（Skill IR）**：将语义契约与任何单一平台格式分离。
- **打包与编译（Package and compile）**：从同一源模型生成精简技能包和目标平台适配器。
- **评估与评审（Evaluate and review）**：将触发行为、输出质量、运行时检查和信任信号转化为可评审的证据。
- **发布与运营（Release and operate）**：仅在当前证据边界内发布，再将采用偏差和评审者反馈纳入下一轮迭代。

## 加权质量基准

该基准是项目级工程评审，各维度按 `0-10` 评分，并加权至 `100`。GitHub stars 被有意排除，因其衡量的是生态热度，而非元技能（meta-skill）工程品质。

该分数是本地工程证据，并非宣称已达世界级就绪度。公开优越性声明仍须依赖世界级台账中已被接受的外部与人类证据。

加权分公式：`sum(score / 10 * weight)`。

| 元技能 | 方法深度 15 | 上下文纪律 10 | 工具链 15 | 评估/测试严谨度 20 | 治理 15 | 可移植性 10 | 上手/评审 5 | 本地可靠性 10 | 加权分 |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| 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 |

| 排名 | 元技能 | 分数 | 核心定位 |
| ---: | --- | ---: | --- |
| 1 | Yao Meta Skill | 91.5 | 面向可复用技能的完整工程、评估、治理与可移植性体系。 |
| 2 | Anthropic Skill Creator | 67.5 | 方法论与迭代闭环较强，但本地执行可靠性与治理覆盖较弱。 |
| 3 | OpenAI Skill Creator | 50.5 | 更适合视为精简的技能编写方法指南，而非完整工程体系。 |

## 人类盲测 A/B 评审快照

2026-06-29，一名人类评审者在五个贴近实际的技能创建场景中，将 `yao-meta-skill` 与捆绑的 OpenAI `skill-creator` 进行对比：支持工单分流、收入对账、网络研讨会内容再利用、事故复盘，以及 PR 评审跟进。评审者确认在打开答案密钥之前已完成各项决策。

结果：在 `5/5` 个案例中选择了 `yao-meta-skill`。

证据：

- 评审入口：[reports/blind-human-review-2026-06-29/index.html](reports/blind-human-review-2026-06-29/index.html)
- 裁决摘要：[reports/blind-human-review-2026-06-29/adjudication.md](reports/blind-human-review-2026-06-29/adjudication.md)
- 已记录决策：[reports/blind-human-review-2026-06-29/review-decisions.recorded.json](reports/blind-human-review-2026-06-29/review-decisions.recorded.json)

边界说明：这是单评审者盲测偏好证据。它并非由提供商背书的独立模型执行证据，且各案例的理由字段仍为空。

## 最佳适用场景

- 当目标是具备明确边界、触发评估、治理、打包、可移植性与本地执行检查的可复用团队资产时，选择 **Yao Meta Skill**。
- 当目标是对话优先的创建闭环，且优先人工引导迭代而非仓库级治理时，选择 **Anthropic Skill Creator**。
- 当目标是编写精简技能指令并保持上下文精简的紧凑参考时，选择 **OpenAI Skill Creator**。
- 实用的混合模式仍然有效：先以对话方式起草，再使用 `yao-meta-skill` 加固技能包、补充证据并使其达到团队可用标准。

## 快速开始

请先在 Codex 中全局安装该技能：

```bash
npx -y skills add yaojingang/yao-meta-skill -a codex -g -y
```

若要为所有受支持的 agent 安装，请将 `-a codex` 替换为 `-a '*'`：

```bash
npx -y skills add yaojingang/yao-meta-skill -a '*' -g -y
```

安装完成后，重启客户端。然后可通过诸如 "create a skill from this workflow"、"improve this existing skill"、"evaluate this skill" 或 "add evals to this skill" 等任务触发 `yao-meta-skill`。

1. 描述你希望转化为技能的工作流、提示词集或重复性任务。
2. 先进行简短的人类意图对话，使真实工作任务、输出、排除项、约束和标准明确化。
3. 让 `quickstart` 先澄清意图，再运行静默基准扫描与参考综合；仅在意图仍不清晰或存在真实设计冲突时才提出明确问题。
4. 使用支持原型的 `quickstart` 或完整创作流程，以 scaffold、production、library 或 governed 模式生成或改进技能包。
5. 先查看生成的 `reports/skill-interpretation.html` 以获取双语解读报告。默认使用简体中文，右上角提供英文切换。然后打开 `reports/skill-overview.html` 查看审计评分卡，并打开 `reports/review-studio.html` 在一页内检查发布阻塞项、权限审批与证据路径，再考虑添加更多结构。

或使用统一创作 CLI：

```bash
python3 scripts/yao.py quickstart --output-dir .
python3 scripts/yao.py github-benchmark-scan my-skill --query "release workflow portability"
python3 scripts/yao.py reference-scan my-skill \
  --external-reference "World Class Method::method::Borrow a tight evaluation loop.::Do not copy heavy process." \
  --user-reference "A product or repo I admire::taste::Learn the clarity and operating standard.::Do not copy wording." \
  --local-constraint "Current Library Naming::structure::Keep naming aligned with the local skill library.::Do not inherit private references."
python3 scripts/yao.py skill-interpretation my-skill
python3 scripts/yao.py review-viewer my-skill
python3 scripts/yao.py review-studio my-skill
python3 scripts/yao.py artifact-design-profile my-skill
python3 scripts/yao.py prompt-quality-profile my-skill
python3 scripts/yao.py system-model my-skill
python3 scripts/yao.py feedback my-skill --note "Tighten exclusions before adding scripts." --rating 4 --category boundary
python3 scripts/yao.py adapt-scan my-skill --source ./curated-user-signals.jsonl
python3 scripts/yao.py adapt-propose my-skill
python3 scripts/yao.py daily-skillops my-skill --source ./curated-user-signals.jsonl
python3 scripts/yao.py weekly-curator my-skill
python3 scripts/yao.py adoption-drift my-skill --record-event skill_activation --activation-type explicit --outcome accepted
YAO_CLI_TELEMETRY=1 python3 scripts/yao.py validate my-skill
python3 scripts/yao.py telemetry-emit my-skill --event skill_activation --activation-type explicit --outcome accepted --command browser-extension
python3 scripts/yao.py telemetry-hooks my-skill
python3 scripts/telemetry_native_host.py my-skill --write-launcher /tmp/yao-telemetry-host.sh --write-manifest /tmp/yao-telemetry-host.json --allowed-origin chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/
python3 scripts/yao.py telemetry-import my-skill --input-jsonl /tmp/external-client-events.jsonl --command browser-extension
python3 scripts/yao.py review-waivers my-skill --add-waiver --gate-key trust-report --reviewer "Yao Team" --reason "Known warning accepted for this release with bounded follow-up." --expires-at 2026-09-30
python3 scripts/yao.py review-waivers my-skill --add-waiver --gate-key permission-gates --reviewer "Yao Team" --reason "Permission warning accepted only for this non-governed release window." --expires-at 2026-09-30
python3 scripts/yao.py review-annotations my-skill --add-annotation --gate-key output-lab --target-path reports/output_quality_scorecard.md --line 1 --body "Clarify recorded fixture vs model-executed evidence before release."
python3 scripts/yao.py baseline-compare
python3 scripts/yao.py check-update
python3 scripts/yao.py skill-ir . --output-json skill-ir/examples/yao-meta-skill.json
python3 scripts/yao.py compile-skill . --target openai --target claude --target generic --target vscode
python3 scripts/yao.py package . --platform generic --output-dir dist
python3 scripts/yao.py output-eval
python3 scripts/yao.py output-exec
python3 scripts/yao.py output-review
python3 scripts/yao.py conformance .
python3 scripts/yao.py trust .
python3 scripts/yao.py python-compat .
python3 scripts/yao.py runtime-permissions . --package-dir dist
python3 scripts/yao.py skill-atlas --workspace-root .
python3 scripts/yao.py registry-audit .
python3 scripts/yao.py package-verify . --package-dir dist --require-zip
python3 scripts/yao.py install-simulate . --package-dir dist
python3 scripts/yao.py upgrade-check . --previous-package-json registry/examples/yao-meta-skill-1.0.0.json
python3 scripts/yao.py world-class-evidence .
SUBMISSIONS_DIR="${SUBMISSIONS_DIR:-evidence/world_class/submissions}"
python3 scripts/yao.py world-class-preflight . --submissions-dir "$SUBMISSIONS_DIR"
python3 scripts/yao.py world-class-submission-kit . --output-dir "$SUBMISSIONS_DIR"
# Alternative: prefill artifact SHA-256 digests while keeping drafts template-only.
python3 scripts/yao.py world-class-submission-kit . --output-dir "$SUBMISSIONS_DIR" --prefill-artifacts
python3 scripts/yao.py world-class-intake . --submissions-dir "$SUBMISSIONS_DIR"
python3 scripts/yao.py world-class-submission-review . --submissions-dir "$SUBMISSIONS_DIR"
python3 scripts/yao.py world-class-ledger . --submissions-dir "$SUBMISSIONS_DIR"
python3 scripts/yao.py world-class-runbook . --submissions-dir "$SUBMISSIONS_DIR"
python3 scripts/yao.py world-class-claim-guard .
python3 scripts/yao.py benchmark-reproducibility .
python3 scripts/yao.py evidence-consistency .
```

## 本地开发源

开发源：本仓库是编写与审阅的权威来源（source of truth）。

本地开发请使用 Python 3.11 或更高版本。GitHub Actions 在 Python 3.11 上运行测试套件，Makefile 在运行 `make test` 或 `make ci-test` 之前会检查当前解释器。

```bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --requirement requirements-ci.txt
make ci-test
```

如果 `python3` 指向较旧的系统解释器，请显式传入解释器：

```bash
make PYTHON=python3.11 ci-test
```

已禁用的镜像：`~/.agents/skills.disabled/yao-meta-skill` 是本源的本地备份镜像。将镜像放在 `~/.agents/skills` 之外，可避免在本仓库同时出现在活动工作区时，Codex 显示重复的 `Yao Meta Skill`。

将当前源同步到已禁用的镜像：

```bash
make sync-local-install
```

同步命令会先重新构建包，并对 `dist/yao-meta-skill.zip` 运行安装预检（install preflight）。当包提取、适配器可读性或安装器权限强制执行失败时，将拒绝同步。预检通过后，会复制 Git 跟踪的文件以及 `scripts/`、`tests/`、`references/` 和 `docs/` 等代码与指南目录中的新源文件。默认会跳过未跟踪的业务 skill 文件夹和未跟踪的私有报告，以免本地实验泄露到镜像中。

仅当你有意让此 skill 在开发工作区之外可被发现时，才恢复活动的全局 Codex 安装：

```bash
make sync-active-install
```

该活动安装会写入 `~/.agents/skills/yao-meta-skill`，并在本仓库作为 skills 工作区打开时，使 Codex 显示第二个 `Yao Meta Skill` 条目。

## 生成产物边界

保持本仓库聚焦于 meta-skill 工厂。

- 将可复用的工厂示例放在 `examples/` 中。
- 将可复用的基准证据、回归结果与发布证据放在 `reports/` 中。
- 除非有意提升为例或回归 fixture，否则将私有分析报告、客户专属输出和一次性生成的业务 skill 保留在本仓库之外。
- 将实际生成的 skill 作为本地 skill 工作区下的同级 skill 目录，而非 `yao-meta-skill` 内的顶层文件夹。

## 5 分钟工作流

1. 从原始工作流笔记开始。
2. 使用 `SKILL.md`、`agents/interface.yaml` 将其转化为 skill 包，且仅包含工作流实际需要的文件夹。
3. 使用 `evals/trigger_cases.json` 验证触发描述。
4. 为你关心的客户端导出兼容性产物。
5. 将结果与 `examples/` 中的示例进行对比。

最小命令集：

```bash
python3 scripts/trigger_eval.py --description-file evals/improved_description.txt --cases evals/trigger_cases.json
python3 scripts/run_description_optimization_suite.py
python3 scripts/judge_blind_eval.py --description-file SKILL.md --cases evals/blind_holdout/trigger_cases.json --semantic-config evals/semantic_config.json
python3 scripts/context_sizer.py .
python3 scripts/resource_boundary_check.py .
python3 scripts/governance_check.py . --require-manifest
python3 scripts/compile_skill.py .
python3 scripts/cross_packager.py . --platform openai --platform claude --platform generic --platform vscode --expectations evals/packaging_expectations.json --zip
python3 scripts/probe_runtime_permissions.py . --package-dir dist
python3 tests/verify_packager_failures.py
```

或一次性运行全部：

```bash
make test
```

统一编写流程：

```bash
python3 scripts/yao.py init my-skill --description "Describe what the skill does."
python3 scripts/yao.py validate my-skill
python3 scripts/yao.py workspace-flow --target root --label first-pass
python3 scripts/yao.py review-viewer my-skill
python3 scripts/yao.py review --target root
python3 scripts/yao.py release-snapshot --target root --label release-candidate
python3 scripts/yao.py skill-ir . --output-json skill-ir/examples/yao-meta-skill.json
python3 scripts/yao.py compile-skill .
python3 scripts/yao.py package . --platform openai --platform claude --platform generic --platform vscode --output-dir dist --zip
python3 scripts/yao.py runtime-permissions . --package-dir dist
python3 scripts/yao.py package-verify . --package-dir dist --require-zip
python3 scripts/yao.py test
```

## 结果

下方首页面板由当前 eval 套件生成，无需打开原始 JSON 即可查看家族（family）级别的结果。

<!-- BEGIN:EVAL_RESULTS -->
- 回归语料库：跨 `21` 个家族的 `66` 条提示
- 汇总结果：`0` 个假阳性（false positives）、`0` 个假阴性（false negatives），平均精确率 `1.0`，平均召回率 `1.0`
- 套件状态：

| Suite | Cases | FP | FN | Precision | Recall |
| --- | ---: | ---: | ---: | ---: | ---: |
| train | 31 | 0 | 0 | 1.0 | 1.0 |
| dev | 22 | 0 | 0 | 1.0 | 1.0 |
| holdout | 13 | 0 | 0 | 1.0 | 1.0 |

| Family | Cases | Pass Rate |
| --- | ---: | ---: |
| `brainstorm_only` | 2 | 1.0 |
| `brainstorm_vs_build` | 1 | 1.0 |
| `complex_multi_asset` | 3 | 1.0 |
| `document_export_vs_agent_skill` | 4 | 1.0 |
| `document_only` | 3 | 1.0 |
| `explain_not_package` | 1 | 1.0 |
| `explain_only` | 5 | 1.0 |
| `future_outline_vs_build` | 4 | 1.0 |
| `iterate_existing_skill` | 5 | 1.0 |
| `long_context_document_only` | 3 | 1.0 |
| `long_context_near_neighbor` | 3 | 1.0 |
| `long_context_summary_only` | 2 | 1.0 |
| `long_context_trigger` | 4 | 1.0 |
| `meta_skill_creation` | 1 | 1.0 |
| `one_off_vs_reusable` | 2 | 1.0 |
| `package_for_team` | 2 | 1.0 |
| `paraphrase_trigger` | 5 | 1.0 |
| `partial_scaffold_not_full_skill` | 4 | 1.0 |
| `summary_only` | 3 | 1.0 |
| `translate_only` | 4 | 1.0 |
| `workflow_to_skill` | 5 | 1.0 |

完整报告：[reports/eval_suite.json](reports/eval_suite.json) 与 [reports/family_summary.md](reports/family_summary.md)
<!-- END:EVAL_RESULTS -->

- 打包验证：`openai`、`claude`、`generic` 与 `vscode` 目标通过契约检查，并携带 IR 溯源、语义一致性元数据与目标原生行为契约
- 目标编译器验证：`openai`、`claude`、`generic`、Agent Skills 兼容以及 VS Code / Copilot 契约均从 Skill IR 编译，包含生成文件映射、适配器模式、原生界面、权限强制执行说明与不支持功能说明
- 运行时权限探测：`openai`、`claude`、`generic` 与 `vscode` 适配器暴露显式权限契约；当前目标报告 `0` 个原生强制执行适配器与 `4` 个元数据回退，残留风险对审阅者可见
- 可移植性评分：`100/100`，中性激活、执行、信任与降级元数据在所有导出目标间保持一致
- 描述优化套件：root、team frontend review 与 governed incident command 通过盲测与对抗 holdout 门控；governed incident command 仍有一处可见的 holdout 漏检，对抗校准与家族漂移现已单独跟踪
- 评委支持的盲测评估：root、team frontend review 与 governed incident command 现已在盲测 holdout 提示上通过独立评分准则评委
- 人工盲测 A/B 快照：在 `5/5` 个真实 skill 创建场景中，单一审阅者选择了 `yao-meta-skill` 而非捆绑的 OpenAI `skill-creator`；证据见 [reports/blind-human-review-2026-06-29/adjudication.md](reports/blind-human-review-2026-06-29/adjudication.md)
- 打包失败 fixture：无效元数据、无效 YAML 与不支持的目标均按预期失败
- 失败库回归：反模式家族通过自动化检查
- 治理与资源边界检查属于默认测试路径的一部分
- root 治理成熟度评分：`90/100`；受治理基准示例：`95/100`
- 支持 CJK 的触发匹配现已由明确的中文构建、打包、评估与近邻用例覆盖
- 上下文预算：root `944/1000`，复杂基准 `790/1000`，受治理基准 `760/1000`
- 质量密度：root `137.7`，复杂基准 `164.6`，受治理基准 `171.1`
- 回归里程碑见 [reports/regression_history.md](reports/regression_history.md)
- 描述漂移历史见 [reports/description_drift_history.md](reports/description_drift_history.md)
- 路由混淆见 [reports/route_scorecard.md](reports/route_scorecard.md)
- 晋升证据汇总见 [reports/iteration_ledger.md](reports/iteration_ledger.md)
- 晋升决策见 [reports/promotion_decisions.md](reports/promotion_decisions.md)
- 候选生命周期状态见 [reports/candidate_registry.md](reports/candidate_registry.md)
- 轻量级 with-skill 与 baseline 对比见 [reports/baseline-compare.md](reports/baseline-compare.md)
- Review Studio 2.0 门控证据见 [reports/review-studio.html](reports/review-studio.html)
- Review Studio 修复操作嵌入于 [reports/review-studio.json](reports/review-studio.json)
- Skill OS 2.0 蓝图覆盖见 [reports/skill_os2_coverage.md](reports/skill_os2_coverage.md)
- 审阅者豁免证据见 [reports/review_waivers.md](reports/review_waivers.md)
- 剩余世界级证据任务见 [reports/world_class_evidence_plan.md](reports/world_class_evidence_plan.md)
- 当前世界级证据验收状态见 [reports/world_class_evidence_ledger.md](reports/world_class_evidence_ledger.md)
- 世界级证据 intake 就绪状态见 [reports/world_class_evidence_intake.md](reports/world_class_evidence_intake.md)
- 世界级提交审阅队列见 [reports/world_class_submission_review.md](reports/world_class_submission_review.md)
- 世界级运维 runbook 见 [reports/world_class_operator_runbook.md](reports/world_class_operator_runbook.md) 与 [reports/world_class_operator_runbook.html](reports/world_class_operator_runbook.html)
- 世界级公开声明防护状态见 [reports/world_class_claim_guard.md](reports/world_class_claim_guard.md)
- 基准可复现性证据见 [reports/benchmark_reproducibility.md](reports/benchmark_reproducibility.md)
- 跨报告证据一致性见 [reports/evidence_consistency.md](reports/evidence_consistency.md)
- 目标编译器证据见 [reports/compiled_targets.md](reports/compiled_targets.md)
- Python 运行时兼容性证据见 [reports/python_compatibility.md](reports/python_compatibility.md)
- 注册表包元数据与审计状态见 [reports/registry_audit.md](reports/registry_audit.md)
- 包归档验证见 [reports/package_verification.md](reports/package_verification.md)
- 临时本地安装模拟见 [reports/install_simulation.md](reports/install_simulation.md)
- 升级 diff、版本号提升建议与发布说明证据见 [reports/upgrade_check.md](reports/upgrade_check.md)
- 本地优先采用与漂移遥测汇总见 [reports/adoption_drift_report.md](reports/adoption_drift_report.md)
- 上下文预算汇总见 [reports/context_budget.md](reports/context_budget.md)
- 可移植性状态见 [reports/portability_score.md](reports/portability_score.md)

## 当前优势

最新加权评审将 Yao 评为 `91.5/100`。最强的维度，正是技能成为长期团队资产时最重要的那些方面：

- **方法深度 `9.5`**：正式的技能工程方法论、原型（archetypes）、门禁选择、非技能决策、生命周期治理与资源边界。
- **工具链完整性 `9.5`**：创作、校验、基准扫描、描述优化、报告生成、晋升检查、打包、CI 与可移植性检查，已串联为一条运营流程。
- **评测与测试严谨性 `9.5`**：通过 train/dev/holdout、盲测 holdout、对抗性 holdout、裁判支持的盲评、路由混淆、漂移历史与晋升门禁来检验触发质量。
- **治理与生命周期 `9.5`**：重要技能可携带负责人、生命周期状态、评审节奏、成熟度评分、信任边界、晋升决策与回归历史。
- **本地执行可靠性 `9.5`**：本仓库可通过 `make test`、`make ci-test` 以及统一的 `scripts/yao.py` 创作 CLI 在本地执行。
- **可移植性与分发 `9.0`**：中立的源元数据、客户端适配器、降级规则、打包契约与可移植性评分，可在目标环境中保留可复用语义。
- **系统稳定性**：生成的技能现包含系统模型，将边界纪律、反馈回路、漂移监测与杠杆点分析转化为评审可见的证据。
- **上下文纪律 `8.0`**：入口点仍控制在预算内，但现作为实时约束进行跟踪，因为系统承载了更多报告、示例、基准资产与生成证据。
- **上手与评审体验 `6.5`**：快速入门、HTML 概览、并排评审查看器与反馈日志改善了首次运行体验，但这仍是最明显的 UX 改进方向。

当前方向是刻意的：保持入口轻量、让评测难以造假、让治理可见，并继续降低首次创作与评审的摩擦。

## 为何选择 Yao

- **轻量**：入口保持紧凑，上下文预算明确，仅在物有所值时才增加额外结构。
- **严谨**：通过族级回归、盲测 holdout、对抗性 holdout、路由混淆、裁判支持的盲评与晋升门禁检验触发质量。
- **可治理**：重要技能被视为可维护资产，具备生命周期状态、成熟度预期、归属与评审节奏。
- **可移植**：源元数据保持中立，适配器、降级规则与打包契约在各环境中保留可复用语义。

## 它能做什么

本项目帮助你以持久能力包（而非一次性提示词）的形式创建、重构、评测并打包技能。

设计逻辑很简单：

1. 捕捉用户请求背后真实、反复出现的工作。
2. 设定清晰的技能边界，使一个包完成一项连贯工作。
3. 在过度编写正文之前，先优化触发描述。
4. 保持主技能文件精简，将细节移至 references 或 scripts。
5. 仅在物有所值时添加质量门禁。
6. 仅为实际需要的客户端导出兼容性产物。

## 方法学

本仓库现将方法论视为一等资产，而非零散指引。

- [Skill Engineering Method](references/skill-engineering-method.md)
- [Intent Dialogue](references/intent-dialogue.md)
- [Reference Scan Strategy](references/reference-scan.md)
- [Pattern Extraction Doctrine](references/pattern-extraction-doctrine.md)
- [Output Quality Risk](references/output-quality-risk.md)
- [Authoring Discipline](references/authoring-discipline.md)
- [Skill Archetypes](references/skill-archetypes.md)
- [Gate Selection](references/gate-selection.md)
- [Iteration Philosophy](references/iteration-philosophy.md)
- [Non-Skill Decision Tree](references/non-skill-decision-tree.md)
- [Regression Cause Taxonomy](references/regression-cause-taxonomy.md)
- [Human Review Template](references/human-review-template.md)

## 为何存在

大多数团队将有价值的运营知识散落在聊天、个人提示词、口头习惯与未记录的工作流中。本项目将这些隐性流程知识转化为：

- 可发现的技能包
- 可重复的执行流程
- 低上下文指令
- 可复用的团队资产
- 兼容就绪的分发形态

## 仓库结构

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

## 核心组件

### `SKILL.md`

主技能入口点。定义触发面、运行模式、紧凑工作流与输出契约。

### `agents/interface.yaml`

中立的元数据单一事实来源。存储展示与兼容性元数据，而不将源树锁定到某一厂商专属路径。

### `references/`

不应撑大主技能文件的长文材料。包括设计规则、评测指引、兼容性策略与质量量表。

### `scripts/`

使元技能可运营的实用脚本：

- `trigger_eval.py`：用语义意图概念、显式排除项与近邻提示词评测触发描述
- `run_eval_suite.py`：运行 train/dev/holdout 触发套件，报告族级回归，并在出现聚合回归时失败
- `optimize_description.py`：生成候选描述，在 dev、可见 holdout、盲测 holdout 与对抗性 holdout 套件上评分，然后报告校准与族健康度
- `judge_blind_eval.py`：对盲测 holdout 提示词应用独立量表裁判，使盲测通过不仅依赖主阈值评分器
- `run_description_optimization_suite.py`：在根技能与受治理示例上运行描述优化，然后写入可复用报告与可选漂移快照（含校准与族摘要）
- `promotion_checker.py`：对当前描述候选应用晋升策略，写入晋升决策、构建候选注册表，并输出带评审存根的迭代包
- `create_iteration_snapshot.py`：将当前晋升决策冻结为带评审、路由与上下文证据的版本化发布快照
- `yao.py`：统一创作 CLI，将 init、validate、optimize-description、promote-check、python-compat、review、release-snapshot、workspace-flow、report、skill-report、skill-interpretation、skill-ir、compile-skill、output-exec、output-review、skill-os2-audit、skill-os2-coverage、world-class-evidence、world-class-ledger、world-class-intake、world-class-preflight、world-class-submission-kit、world-class-submission-review、world-class-runbook、world-class-claim-guard、benchmark-reproducibility、evidence-consistency、adapt-scan、adapt-propose、adapt-apply、daily-skillops、weekly-curator、telemetry-emit、telemetry-hooks、telemetry-import、package、registry-audit、package-verify、install-simulate、upgrade-check、review-waivers 与 test 作为单一入口暴露
- `render_description_drift_history.py`：将描述优化快照转化为可读的漂移历史报告
- `build_confusion_matrix.py`：在受跟踪的兄弟技能与 `no_route` 用例上评分路由混淆，然后写入路由记分卡与可选里程碑快照
- `render_iteration_ledger.py`：将回归里程碑、描述优化漂移与路由记分卡压缩为面向迭代的台账
- `context_sizer.py`：估算上下文权重，并在初始加载过大时发出警告
- `resource_boundary_check.py`：审计细节是否恰当分布在 `SKILL.md`、`references/`、`scripts/`、`assets/` 与 `evals/` 中
- `governance_check.py`：校验负责人、评审节奏、生命周期阶段与成熟度元数据
- `render_context_reports.py`：生成根级与示例级上下文预算报告，以及共享上下文摘要
- `render_regression_history.py`：将里程碑快照转化为可读的回归历史报告
- `render_skill_os2_audit.py`：渲染逐项 Skill OS 2.0 审计，区分已落地的本地证据与需人工、需外部的缺口
- `render_skill_os2_coverage.py`：将 Skill OS 2.0 升级蓝图映射到本地产物、命令、测试与剩余证据边界
- `render_daily_skillops_report.py`：渲染显式来源的 Daily SkillOps 运营报告，汇总脱敏用户模式、仅提案式适配、审批状态、发布证据与世界级证据缺口，且不扫描私有日志或应用补丁
- `render_weekly_curator_report.py`：从生成的日报、Skill Atlas、基准锁定、证据一致性与世界级台账状态渲染每周 SkillOps 策展报告，且不扫描私有日志或应用补丁
- `skillops_opportunity.py`：为脱敏 SkillOps 机会评分，并映射到需审批的门控动作类型，如仅报告、AGENTS 更新、既有技能补丁或评测增补
- `render_world_class_evidence_plan.py`：为剩余世界级缺口渲染可执行证据任务，不将计划中的外部工作视为已完成证据
- `render_world_class_evidence_ledger.py`：为当前世界级证据验收、防过度宣称守卫、来源要求与隐私契约渲染机器可校验台账
- `render_world_class_evidence_intake.py`：在台账评审前，按来源、隐私、产物与防过度宣称要求校验世界级外部与人工证据包
- `render_world_class_preflight.py`：为待处理的提供商、人工、原生权限与原生客户端证据渲染脱敏采集预检，不接受证据
- `render_world_class_submission_review.py`：渲染只读队列，比较提交、 intake 校验、来源证据与台账状态，不接受证据
- `render_world_class_operator_runbook.py`：为采集待处理世界级证据渲染面向运维人员的检查清单与命令映射，不接受证据
- `render_world_class_claim_guard.py`：在已验收证据仍待处理时，扫描 README、文档与报告中的过早世界级完成宣称
- `render_benchmark_reproducibility.py`：为公开基准宣称渲染方法论、产物、失败披露与复现命令证据
- `render_evidence_consistency.py`：在基准可复现性、概览、解读、采用漂移、世界级台账、覆盖率与 Review Studio 产物之间比较生成报告事实
- `python_compat_check.py`：检查 Python 源码是否存在受支持运行时的兼容性风险，例如 Python 3.11 f-string 表达式反斜杠
- `cross_packager.py`：从 Skill IR 加中立元数据构建客户端专属导出产物，含显式平台契约与校验
- `render_portability_report.py`：从中立元数据、降级规则与消费者校验覆盖率评分跨环境可移植性
- `render_skill_overview.py`：生成白底双语 HTML 技能审计报告，含粘性四字中文导航、右上角语言切换、v2 记分卡、内联 SVG 图表、契约边界、质量评审、风险治理、资产与迭代路线图
- `render_skill_interpretation.py`：将 `reports/skill-interpretation.html/json` 渲染为一等创作后解读报告，同时复用 Skill Overview v2 模型与 Kami 白色版式
- `export_skill_ir.py`：从 `SKILL.md`、manifest、接口元数据、evals、resources 与 reports 导出 2.0 平台中立的 Skill IR 契约
- `compile_skill.py`：将 Skill IR 编译为目标专属语义契约、生成文件映射、适配器模式、目标原生行为契约、保留语义、警告与不支持特性说明
- `run_output_eval.py`：运行 Output Eval Lab v0，含静态 with-skill 与 baseline 断言评分、盲测 A/B 评审包生成，以及独立答案键产物
- `run_output_execution.py`：记录 output-eval 执行证据，区分记录型 fixture、命令运行器与提供商支持的模型运行（含时序与 token 元数据）
- `local_output_eval_runner.py`：命令执行 output-eval 冒烟证据的确定性本地运行器，不宣称提供商支持的模型生成
- `adjudicate_output_review.py`：记录盲测 A/B output eval 的评审者选择，与答案键比较，并渲染待处理、匹配、分歧与无效决策审计报告
- `render_review_annotations.py`：记录与 Review Studio 门禁、来源/报告路径及可选行号绑定的评审者批注，开放阻塞批注会反映在 Review Studio 决策中
- `run_conformance_suite.py`：校验 OpenAI、Claude、Agent Skills、VS Code/Copilot 风格与通用目标的运行时一致性
- `trust_check.py`：为脚本、依赖、密钥风险、有界网络主机策略、执行级 `--help` 冒烟检查、权限输入、信任元数据与稳定源契约完整性生成信任/安全报告
- `build_skill_atlas.py`：构建 Skill Atlas 目录、路由重叠矩阵、依赖图、陈旧报告、负责人缺口、聚合漂移信号，以及多技能工作区的 HTML 概览
- `registry_audit.py`：构建注册表包元数据，并审计版本、负责人、许可证、校验和、Skill IR 来源与兼容性矩阵
- `verify_package.py`：校验生成的包 manifest、目标适配器、zip 归档安全性、归档校验和与注册表一致性
- `simulate_install.py`：将生成的 zip 解压到临时技能根目录，并校验入口点、manifest、接口、报告与适配器可加载
- `upgrade_check.py`：比较当前与上一版注册表包元数据，推荐版本号提升，并阻止不兼容的升级宣称
- `render_adoption_drift_report.py`：记录仅元数据的本地遥测，并渲染采用、漏触发、差输出、脚本错误与评审漂移信号，不打包原始事件日志
- `import_telemetry_events.py`：在全文件隐私校验后导入外部仅元数据遥测 JSONL，然后刷新聚合采用漂移报告
- `emit_telemetry_event.py`：向本地 spool 发出一条仅元数据的外部客户端事件，供后续 `telemetry-import` 使用，含 dry-run 校验与 raw-content 字段阻断
- `render_telemetry_hook_recipes.py`：渲染 Browser、Chrome、VS Code、CLI wrapper 与 provider-adapter 遥测 hook 配方，含 dry-run 命令与显式原生集成注意事项
- `telemetry_native_host.py`：接收 Browser/Chrome Native Messaging 长度前缀 JSON 事件，拒绝 raw-content 字段，追加仅元数据事件，并为运维安装写入本地启动器/manifest 文件
- `yao_cli_telemetry.py`：可选的仅元数据 `yao.py` 运行捕获，记录命令名、来源、结果与失败类别，不含命令参数或原始内容
- `render_review_waivers.py`：校验人工评审者风险审批，含门禁键、原因、过期日期与阻塞安全的豁免策略
- `init_skill.py`、`lint_skill.py`、`validate_skill.py`、`diff_eval.py`：最小创作工具链
- `check_update.py`：检查 GitHub 是否有更新的 `VERSION` 或远程 manifest 版本，并报告重装提示，不修改本地文件
- `render_output_risk_profile.py`：预测输出专属失败模式，如通用标题、引用杂乱、截图错误、薄弱 Markdown 表格与缺失执行假设

### `evals/`

可复用的触发器与打包检查，包含用于对比的基线与改进版描述，以及驱动描述优化的根语义配置。

本目录还包含路由混淆（route confusion）测试夹具，以及用于判断路由是否可晋升（promotable）的晋升策略规则。

### `examples/`

端到端示例，展示原始工作流输入、设计摘要、最终生成的 skill 形态，以及针对示例的定向描述优化包——其中路由措辞会依据示例专属的 dev 与 holdout 用例进行调优。

### `.github/workflows/test.yml`

持续集成入口，在 push 与 pull request 时运行完整的本地回归套件。

## 验证说明

- 触发器评估现使用本地语义意图（semantic-intent）模型，并显式包含正向概念、排除概念与边界用例报告。
- 示例触发器报告现覆盖更大的正向、负向与近邻（near-neighbor）集合，而不再局限于极小的演示集。
- Train/dev/holdout 触发器套件现已将迭代调优与最终验证分离。
- 描述优化现使用 dev 进行排序，使用可见 holdout 做非回归检查，使用盲 holdout 做验收，并使用对抗 holdout 做更严格的路由碰撞检查，且不会将其喂入排序循环。
- 由 Judge 支撑的盲评（blind eval）现为盲提示增加基于评分量表（rubric）的第二意见，因此盲验收不再由单一评分器单独决定。
- 描述漂移历史现会记录对抗校准差距与家族覆盖度，从而可依据置信度与家族稳定性评判路由变更，而不仅依赖原始错误计数。
- 路由混淆现会在根 meta-skill、前端评审 skill、受治理 incident skill 以及 `no_route` 用例中被显式跟踪，使路由窃取（route theft）可见，而非隐含发生。
- 晋升策略现要求在将某描述视为可晋升之前，可见 holdout、盲 holdout、对抗 holdout 与路由混淆均保持干净。
- 晋升检查现会输出显式决策、候选生命周期状态、迭代捆绑包与人审占位项，而不再将晋升仅作为散文式步骤。
- 晋升决策现可区分“无候选优于当前版本”与“当前版本仍存在残余路由风险”，从而可在不将每个问题强行记为阻断的情况下审计迭代。
- 打包验证现使用显式契约与 YAML 解析，但它仍是轻量级本地验证层，而非完整的平台集成套件。
- `evals/failure-cases.md` 记录应继续纳入回归检查的已知薄弱点。
- `failures/` 收录可复用的反模式说明，以及针对路由、打包与编写失败的可机器运行失败用例。
- `tests/verify_packager_failures.py` 检查无效元数据、无效 YAML 与不支持的 target 是否会明确失败。
- 治理元数据与资源边界规则现已有可运行检查，而不再仅以散文形式存在。
- 治理检查现会输出成熟度评分，使受治理资产可进行对比，而不仅是通过/失败检查。
- 描述优化漂移历史现与主触发器回归历史分开版本化，以便路由改进可随时间可见。
- 迭代证据现通过共享回归原因分类法与捆绑工件，记录候选被保留、阻断或可晋升的原因。
- 声明的成熟度层级会对照推荐最低治理分数进行检查，从而可对比 `production`、`library` 与 `governed` 资产，而无需将每个强示例强行归入同一标签。
- 上下文预算（context budget）现已分层且显式化，因此受治理 skill 仍可选择更严格的 `production` 规模初始加载预算。
- 资源边界检查现可检测装饰性目录，并计算本地质量密度信号，而不仅检查原始 token 计数。

### `templates/`

适用于简单与更高级 skill 包的入门模板。

## 使用方法

### 1. 直接使用 skill

当你希望执行以下操作时，调用 `yao-meta-skill`：

- 创建新 skill
- 改进现有 skill
- 为 skill 添加 eval
- 将工作流转换为可复用包
- 为 skill 在更广团队范围内采用做准备

### 2. 生成新的 skill 包

典型流程如下：

1. 描述工作流或能力
2. 识别触发短语与输出
3. 选择 scaffold、production 或 library 模式
4. 生成包
5. 如有需要，运行规模与触发器检查
6. 从 Skill IR 契约导出 target 专属兼容工件

### 3. 导出兼容工件

示例：

```bash
python3 scripts/export_skill_ir.py ./yao-meta-skill --output-json ./yao-meta-skill/reports/skill-ir.json
python3 scripts/compile_skill.py ./yao-meta-skill --target openai --target claude --target generic
python3 scripts/cross_packager.py ./yao-meta-skill --platform openai --platform claude --expectations evals/packaging_expectations.json --zip
python3 scripts/context_sizer.py ./yao-meta-skill
python3 scripts/resource_boundary_check.py ./yao-meta-skill
python3 scripts/governance_check.py ./yao-meta-skill --require-manifest
python3 scripts/trigger_eval.py --description-file evals/improved_description.txt --cases evals/trigger_cases.json --baseline-description-file evals/baseline_description.txt
```

## 优势

- **方法优先，而非提示优先**：skill 创建被视为正式工程工作流，包含原型（archetype）、门禁选择与“非 skill”决策。
- **按设计具备触发器感知能力**：描述优化会结合路由混淆、盲 holdout、对抗家族与晋升策略，而非依赖一次性直觉。
- **入口点保持轻量**：`SKILL.md` 保持紧凑，而 references、scripts 与 evals 仅在物有所值时才会添加。
- **工具链支撑**：初始化、验证、优化、报告、打包与测试可通过统一 CLI 与 CI 路径使用。
- **作为资产受治理**：重要 skill 可携带所有权、生命周期状态、成熟度预期与评审节奏。
- **默认可移植**：源元数据保持中性，而适配器与降级规则可在不同 target 环境间保持兼容性。
- **证据丰富**：路由记分卡、回归历史、上下文预算、可移植性评分与晋升决策会作为工件发布，而非隐藏在实现细节中。

## 最适合场景

本项目最适合：

- agent 构建者
- 内部工具团队
- 正迈向结构化 skill 的提示工程师
- 正在构建可复用 skill 库的组织

## 文档

| Language | Entry |
| --- | --- |
| English | [README.md](README.md) |
| 中文 | [docs/README.zh-CN.md](docs/README.zh-CN.md) |
| 日本語 | [docs/README.ja-JP.md](docs/README.ja-JP.md) |
| Français | [docs/README.fr-FR.md](docs/README.fr-FR.md) |
| Русский | [docs/README.ru-RU.md](docs/README.ru-RU.md) |

## 示例与 Eval

- Examples: [examples/README.md](examples/README.md)
- Evals: [evals/README.md](evals/README.md)
- Failure library: [failures/README.md](failures/README.md)
- Failure regression check: [verify_failure_regressions.py](tests/verify_failure_regressions.py)
- Regression history: [reports/regression_history.md](reports/regression_history.md)
- Root governance score: [reports/governance_score.json](reports/governance_score.json)
- Packaging contracts: [references/packaging-contracts.md](references/packaging-contracts.md)
- Governance model: [references/governance.md](references/governance.md)
- Resource boundary spec: [references/resource-boundaries.md](references/resource-boundaries.md)
- Platform capability matrix: [references/platform-capability-matrix.md](references/platform-capability-matrix.md)
- Failure fixtures: [tests/fixtures](tests/fixtures)
- Adapter snapshots: [tests/snapshots](tests/snapshots)
- Evolution example: [examples/evolution-frontend-review/README.md](examples/evolution-frontend-review/README.md)
- Governed example: [examples/governed-incident-command/design-summary.md](examples/governed-incident-command/design-summary.md)
- Governed example score: [examples/governed-incident-command/generated-skill/reports/governance_score.json](examples/governed-incident-command/generated-skill/reports/governance_score.json)

## 许可证

MIT。详见 [LICENSE](LICENSE)。