yaojingang/yao-meta-skill

# Yao Meta Skill [](https://github.com/yaojingang/yao-meta-skill/actions/workflows/test.yml) [](LICENSE) [](README.md) [](docs/README.zh-CN.md) [](docs/README.ja-JP.md) [](docs/README.fr-FR.md) [](docs/README.ru-RU.md) `YAO` 代表 `Yielding AI Outcomes`（产出 AI 成果）—— 其目标不是生成更多的 prompt 文本，而是产出可复用的 AI 资产和真实的运营成果。 `yao-meta-skill` 是一个轻量但严谨的系统，用于创建、评估、打包和治理可复用的 agent 技能。 [快速开始](#quick-start) · [示例](examples/README.md) · [评估](evals/README.md) · [失败库](failures/README.md) · [方法准则](#method-doctrine) 它将粗糙的工作流、记录稿、prompt、笔记和操作手册转化为可复用的技能包，包含： - 清晰的触发面 - 精简的 `SKILL.md` - 可选的参考资料、脚本和评估 - 前置的意图对话与意图置信度门控，当真实任务、输出、排除项或标准仍然模糊时，系统会继续澄清 - 默认静默的 GitHub 基准扫描加上参考资料综合，研究顶级公共代码库和世界级模式轨迹，然后仅向用户展示真实的冲突或不确定性 - 为每个新初始化的技能生成可视化的 HTML 概览 - Review Studio 2.0 HTML 门控页面，结合了意图、触发器、输出评估、上下文、runtime、信任、图谱、采用漂移、审查者豁免、审查者批注、发布证据以及针对每个警告的修复动作 - Output Eval Lab 证据，包含断言评分、执行/时间/token 证据、盲测 A/B 审查包、单独的答案 key 以及审查者裁决报告 - runtime 权限探测报告，检查打包的 target adapter 是否具有显式的权限元数据、原生强制执行标志、元数据回退说明和残余风险 - 用于首轮人工审查的并排 HTML 审查工作室 - 制品设计配置文件，定义了报告、教程、仪表板、屏幕截图和审查页面的视觉方向、布局模式和质量门控 - prompt 质量配置文件，将需求建模、RTF 映射、复杂度和质量检查抽象为对审查者可见的证据，而不是让 `SKILL.md` 变得臃肿 - 系统思考模型，映射边界、反馈循环、漂移风险、反复出现的失败模式以及最高杠杆的质量动作 - 首次创建技能包后的三个高价值下一步迭代方向 - 不需要完整晋升周期的轻量级反馈日志 - 本地优先、仅基于元数据的采用和漂移报告，将实际使用信号转化为下一轮迭代的候选方案 - 用于带有技能与基准对比审查的基准比较报告 - 对话式、原型感知的快速入门，引导新的技能包适应 scaffold、production、library 或 governed 模式 - Skill IR 作为平台无关的语义合约，加上编译器报告和特定 client 的 adapter - Registry 审计元数据，包含包版本、所有者、license、checksum 和兼容性矩阵 - 内置于默认流程中的治理、晋升和可移植性检查 ## 架构 核心视图：通过一个紧凑的流程，将混乱的运营输入转化为受治理且可复用的技能包。 ``` flowchart LR A["Inputs
workflow / prompt / transcript / docs / notes"] --> B["Route
SKILL.md"] B --> C["Design
method + gates"] C --> D["Run
create / validate / eval / promote"] D --> E["Outputs
skill package + reports + adapters"] ``` 10 秒钟读懂它： - **输入**：从粗糙的运营材料开始。 - **路由**：在精简的 `SKILL.md` 中定义边界和触发器。 - **设计**：选择合适的原型、门控和资源拆分。 - **运行**：使用统一的 CLI 进行构建、验证、优化和晋升。 - **输出**：交付可复用的技能，以及证据、治理信号和可移植性制品。 ## 加权质量基准 该基准测试是项目级的工程审查，每个维度得分从 `0-10` 并加权至 `100`。特意排除了 GitHub star 数量，因为它们衡量的是生态热度，而不是元技能工程质量。 加权得分公式：`sum(score / 10 * weight)`。 | Meta Skill | Method Depth 15 | Context Discipline 10 | Toolchain 15 | Eval/Test Rigor 20 | Governance 15 | Portability 10 | Onboarding/Review 5 | Local Reliability 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 | | 排名 | Meta Skill | 得分 | 核心定位 | | ---: | --- | ---: | --- | | 1 | Yao Meta Skill | 91.5 | 面向可复用技能的完整工程、评估、治理和可移植性系统。 | | 2 | Anthropic Skill Creator | 67.5 | 强大的方法论和迭代循环，但本地执行可靠性和治理覆盖率较弱。 | | 3 | OpenAI Skill Creator | 50.5 | 最好将其视为编写精简技能指令的简明方法指南，而不是完整的工程系统。 | ## 最佳适用场景 - 当目标是具有明确边界、触发评估、治理、打包、可移植性和本地执行检查的可复用团队资产时，请选择 **Yao Meta Skill**。 - 当目标是优先考虑对话优先的创建循环，且重点是仓库级治理之上的人工引导迭代时，请选择 **Anthropic Skill Creator**。 - 当目标是作为编写精简技能指令和保持上下文精简的紧凑参考时，请选择 **OpenAI Skill Creator**。 - 一种实用的混合模式仍然很有用：先通过对话起草，然后使用 `yao-meta-skill` 来加固技能包、添加证据并使其达到团队可用标准。 ## 快速开始 1. 描述你想要转化为技能的工作流、prompt 集或重复性任务。 2. 从简短的人工意图对话开始，明确真实的任务、输出、排除项、约束和标准。 3. 让 `quickstart` 先澄清意图，然后运行静默基准扫描和参考资料综合；只有当意图仍不清晰或存在真正的设计冲突时，它才会提出明确的问题。 4. 使用原型感知的 `quickstart` 或完整的创作流程，在 scaffold、production、library 或 governed 模式下生成或改进技能包。 5. 首先查看生成的 `reports/skill-overview.html` 以获取双语 HTML 技能报告。它默认为简体中文，并在右上角提供英文切换。然后打开 `reports/review-studio.html`，在添加更多结构之前，在同一页面中检查发布阻碍、权限批准和证据路径。 或者使用统一的创作 CLI： ``` 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 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 adoption-drift my-skill --record-event skill_activation --activation-type explicit --outcome accepted 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 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 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 ``` ## 本地开发源 开发源：此仓库是创作和审查的唯一事实来源。 已禁用的镜像：`~/.agents/skills.disabled/yao-meta-skill` 是此源的本地备份镜像。将镜像保留在 `~/.agents/skills` 之外，可以防止在此仓库在工作区中可见时，Codex 显示重复的 `Yao Meta Skill`。 将当前源同步到已禁用的镜像： ``` make sync-local-install ``` 同步命令会复制 Git 跟踪的文件以及 `scripts/`、`tests/`、`references/` 和 `docs/` 等代码和指导目录中的新源文件。默认情况下，它会跳过未跟踪的业务技能文件夹和未跟踪的私有报告，因此本地实验不会泄漏到镜像中。 仅当您有意希望在此开发工作区之外可以发现此技能时，才恢复活动的全局 Codex 安装： ``` make sync-active-install ``` 该活动安装会写入 `~/.agents/skills/yao-meta-skill`，并且当此仓库作为技能工作区打开时，可能会使 Codex 显示第二个 `Yao Meta Skill` 条目。 ## 生成的制品边界 保持此仓库专注于元技能工厂。 - 将可复用的工厂示例放在 `examples/` 中。 - 将可复用的基准证据、回归结果和发布证据放在 `reports/` 中。 - 将私有分析报告、特定于客户的输出以及一次性生成的业务技能保留在此仓库之外，除非有意将其晋升为示例或回归 fixture。 - 将实际生成的技能作为本地技能工作区下的同级技能目录放置，而不是作为 `yao-meta-skill` 内部的顶级文件夹。 ## 5 分钟工作流 1. 从原始的工作流笔记开始。 2. 使用 `SKILL.md`、`agents/interface.yaml` 以及工作流实际所需的文件夹将其转化为技能包。 3. 使用 `evals/trigger_cases.json` 验证触发器描述。 4. 为您关心的 client 导出兼容性制品。 5. 将结果与 `examples/` 中的示例进行比较。 最小命令集： ``` 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 --expectations evals/packaging_expectations.json --zip python3 scripts/probe_runtime_permissions.py . --package-dir dist python3 tests/verify_packager_failures.py ``` 或者一起运行所有内容： ``` make test ``` 统一的创作流程： ``` 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 --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 ``` ## 结果 下面的主页面板是根据当前的评估套件生成的，因此无需打开原始 JSON 即可看到家族级别的结果。 - 回归语料库：跨 `21` 个家族的 `66` 个 prompt - 汇总结果：`0` 个假阳性，`0` 个假阴性，平均准确率 `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 | | 家族 | Cases | 通过率 | | --- | ---: | ---: | | `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) - 打包验证：`openai`、`claude` 和 `generic` target 通过合约检查，并带有 IR 来源、语义对等元数据和 target 原生行为合约 - target 编译器验证：从 Skill IR 编译 `openai`、`claude`、`generic` 和 Agent Skills 兼容合约，包含生成的文件映射、adapter 模式、原生表面、权限强制执行说明和不受支持的功能说明 - runtime 权限探测：`openai`、`claude` 和 `generic` adapter 暴露了显式的权限合约；当前 target 报告了 `0` 个原生强制执行 adapter 和 `3` 个元数据回退，其对审查者可见残余风险 - 可移植性得分：`100/100，在所有导出的 target 中保留了中性激活、执行、信任和降级元数据 - 描述优化套件：root、团队前端审查和 governed 事件指挥通过了盲测和对抗性 holdout 门控；governed 事件指挥仍然存在一个可见的 holdout 未命中，对抗性校准和家族漂移现在被分开跟踪 - 评委支持的盲测评估：root、团队前端审查和 governed 事件指挥现在通过了独立 rubric 评委对盲测 holdout prompt 的评估 - 打包失败 fixture：无效元数据、无效 YAML 和不支持的 target 按预期失败 - 失败库回归：反模式家族通过了自动检查 - 治理和资源边界检查是默认测试路径的一部分 - root 治理成熟度得分：`90/100`；governed 基准示例：`95/100` - 支持 CJK 的触发器匹配现在已涵盖显式的中文构建、打包、评估和近邻案例 - 上下文预算：root `987/1000`，复杂基准 `790/1000`，governed 基准 `760/1000` - 质量密度：root `131.7`，复杂基准 `164.6`，governed 基准 `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) 中 - 轻量级的带技能与基准比较发布在 [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) 中 - 审查者豁免证据发布在 [reports/review_waivers.md](reports/review_waivers.md) 中 - target 编译器证据发布在 [reports/compiled_targets.md](reports/compiled_targets.md) 中 - registry 包元数据和审计状态发布在 [reports/registry_audit.md](reports/registry_audit.md) 中 - 包归档验证发布在 [reports/package_verification.md](reports/package_verification.md) 中 - 临时本地安装模拟发布在 [reports/install_simulation.md](reports/install_simulation.md) 中 - 升级差异、版本升级建议和发行说明证据发布在 [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`**：正式的技能工程准则、原型、门控选择、非技能决策、生命周期治理和资源边界。 - **工具链完整性 `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`**：中性的源元数据、client adapter、降级规则、打包合约和可移植性评分在 target 环境中保留了可复用的语义。 - **系统稳定性**：生成的技能现在包含一个系统模型，该模型将边界规范、反馈循环、漂移观察和杠杆点分析转化为对审查者可见的证据。 - **上下文规范 `8.0`**：entrypoint 仍然保持在预算之内，但这被视为一个动态约束，因为系统现在承载了更多的报告、示例、基准资产和生成的证据。 - **入门和审查体验 `6.5`**：快速入门、HTML 概览、并排审查查看器和反馈日志改善了首次运行体验，但这仍然是最需要改进的 UX 领域。 目前的方向是深思熟虑的：保持 entrypoint 轻量，使评估难以伪造，使治理可见，并继续减少首次创建和审查的摩擦。 ## 为什么选择 Yao - **轻量级**：entrypoint 保持紧凑，上下文预算明确，并且仅当额外结构能带来回报时才会添加它们。 - **严谨**：使用家族回归、盲测 holdout、对抗性 holdout、路由混淆、评委支持的盲测评估和晋升门控来检查触发器质量。 - **受治理**：重要的技能被视为具有生命周期状态、成熟度期望、所有权和审查节奏的可维护资产。 - **可移植**：源元数据保持中性，同时 adapter、降级规则和打包合约在各个环境中保留可复用的语义。 ## 它的功能 此项目可帮助您创建、重构、评估技能，并将其打包为持久的能力束，而不是一次性的 prompt。 设计逻辑很简单： 1. 捕获用户请求背后的真正重复性任务。 2. 设置清晰的技能边界，以便一个包只执行一项连贯的任务。 3. 在过度编写主体之前优化触发器描述。 4. 保持主技能文件精简，并将细节移至参考资料或脚本中。 5. 仅在质量门控物有所值时才添加它们。 6. 仅为实际需要的 client 导出兼容性制品。 ## 方法准则 该仓库现在将方法视为一等资产，而不是分散的指导。 - [技能工程方法](references/skill-engineering-method.md) - [意图对话](references/intent-dialogue.md) - [参考资料扫描策略](references/reference-scan.md) - [模式提取准则](references/pattern-extraction-doctrine.md) - [输出质量风险](references/output-quality-risk.md) - [创作规范](references/authoring-discipline.md) - [技能原型](references/skill-archetypes.md) - [门控选择](references/gate-selection.md) - [迭代理念](references/iteration-philosophy.md) - [非技能决策树](references/non-skill-decision-tree.md) - [回归原因分类](references/regression-cause-taxonomy.md) - [人工审查模板](references/human-review-template.md) ## 为什么存在 大多数团队将宝贵的运营知识分散在聊天、个人 prompt、口头习惯和未记录的工作流中。此项目将该隐藏的流程知识转化为： - 可发现的技能包 - 可重复的执行流程 - 低上下文的指令 - 可复用的团队资产 - 兼容就绪的分发 ## 仓库结构 ``` yao-meta-skill/ ├── SKILL.md ├── README.md ├── VERSION ├── LICENSE ├── .gitignore ├── agents/ │ └── interface.yaml ├── evals/ ├── examples/ ├── references/ ├── scripts/ └── templates/ ``` ## 核心组件 ### `SKILL.md` 主技能 entrypoint。它定义了触发面、操作模式、紧凑的工作流和输出合约。 ### `agents/interface.yaml` 中性的元数据事实来源。它存储显示和兼容性元数据，而不会将源代码树锁定到特定于供应商的路径。 ### `references/` 不应使主技能文件膨胀的长篇材料。这包括设计规则、评估指导、兼容性策略和质量标准。 ### `scripts/` 使元技能可操作的实用脚本： - `trigger_eval.py`：使用语义意图概念、显式排除和近邻 prompt 评估触发器描述 - `run_eval_suite.py`：运行 train/dev/holdout 触发器套件，报告家族级回归，并在出现总体回归时失败 - `optimize_description.py`：生成候选描述，在 dev、可见 holdout、盲测 holdout 和对抗性 holdout 套件上对它们进行评分，然后报告校准和家族健康状况 - `judge_blind_eval.py`：将独立的 rubric 评委应用于盲测 holdout prompt，因此盲测接受不仅由主阈值评分器支持 - `run_description_optimization_suite.py`：跨 root 技能和 governed 示例运行描述优化，然后编写可复用的报告和带有校准和家族摘要的可选漂移快照 - `promotion_checker.py`：将晋升策略应用于当前描述候选方案，编写晋升决策，构建候选 registry，并发出带有审查存根的迭代 bundle - `create_iteration_snapshot.py`：将当前的晋升决策冻结为带有审查、路由和上下文证据的版本化发布快照 - `yao.py`：统一的创作 CLI，将 init、validate、optimize-description、promote-check、review、release-snapshot、workspace-flow、report、skill-ir、compile-skill、output-exec、output-review、package、registry-audit、package-verify、install-simulate、upgrade-check、review-waivers 和 test 作为一个 entrypoint 暴露出来 - `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`：生成 root 和示例上下文预算报告以及共享上下文摘要 - `render_regression_history.py`：将里程碑快照转化为可读的回归历史报告 - `cross_packager.py`：利用显式的平台合约和验证，从 Skill IR 和中性的元数据构建特定于 client 的导出制品 - `render_portability_report.py`：根据中性元数据、降级规则和使用者验证覆盖率对跨环境可移植性进行评分 - `render_skill_overview.py`：生成白底色双语 HTML 技能审计报告，带有固定的四个汉字中文导航、右上角语言切换、v2 评分卡、内联 SVG 图表、合约边界、质量审查、风险治理、资产和迭代路线图 - `export_skill_ir.py`：从 `SKILL.md`、manifest、interface 元数据、评估、资源和报告中导出 2.0 平台无关的 Skill IR 合约 - `compile_skill.py`：将 Skill IR 编译为特定于 target 的语义合约、生成的文件映射、adapter 模式、target 原生行为合约、保留的语义、警告和不受支持的功能说明 - `run_output_eval.py`：运行带有静态带技能与基准断言评分、盲测 A/B 审查包生成和单独答案 key 制品的 Output Eval Lab v0 - `run_output_execution.py`：记录输出评估执行证据，区分记录的 fixture、命令运行程序和带有时间与 token 元数据的 provider 支持的模型运行 - `local_output_eval_runner.py`：用于命令执行的输出评估冒烟证据的确定性本地运行程序，不声称有 provider 支持的模型生成 - `adjudicate_output_review.py`：记录审查者对盲测 A/B 输出评估的选择，将其与答案 key 进行比较，并呈现待处理、匹配、分歧和无效决策的审计报告 - `render_review_annotations.py`：记录与 Review Studio 门控、源/报告路径和可选行号相关联的审查者批注，并在 Review Studio 决策中反映开放的阻碍性批注 - `run_conformance_suite.py`：验证 OpenAI、Claude、Agent Skills、VS Code/Copilot 风格和 generic target 的 runtime 一致性 - `trust_check.py`：为脚本、依赖项、secret 风险、有界网络主机策略、执行级 `--help` 冒烟检查、权限输入、信任元数据和稳定源合约完整性生成信任/安全报告 - `build_skill_atlas.py`：为多技能工作区构建 Skill Atlas 目录、路由重叠矩阵、依赖图、过期报告、所有者缺口和 HTML 概览 - `registry_audit.py`：构建 registry 包元数据，并审计版本、所有者、license、checksum、Skill IR 源和兼容性矩阵 - `verify_package`：验证生成的包清单、target adapter、zip 归档安全性、归档 checksum 和 registry 一致性 - `simulate_install.py`：将生成的 zip 提取到临时技能根目录中，并验证 entrypoint、manifest、interface、报告和 adapter 是否可以加载 - `upgrade_check.py`：比较当前和以前的 registry 包元数据，推荐版本升级，并阻止不兼容的升级声明 - `render_adoption_drift_report.py`：记录仅元数据的本地遥测，并呈现采用、触发遗漏、输出错误、脚本错误和审查漂移信号，而无需打包原始事件日志 - `render_review_waivers.py`：使用门控 key、原因、过期日期和阻碍安全的豁免策略验证人工审查者风险批准 - `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/` 可复用的触发器和打包检查，包括用于比较的基准和改进描述，以及驱动描述优化的 root 语义配置。 此目录还包含路由混淆 fixture 和用于决定路由何时可晋升的晋升策略规则。 ### `examples/` 端到端示例，展示原始工作流输入、设计摘要、最终生成的技能形状，以及针对特定示例的 dev 和 holdout 案例调整路由措辞的定向描述优化包。 ### `.github/workflows/test.yml` 持续集成 entrypoint，在 push 和 pull request 时运行完整的本地回归套件。 ## 验证说明 - 触发器评估现在使用具有显式正向概念、排除概念和边界情况报告的本地语义意图模型。 - 示例触发器报告现在涵盖了更大的正向、负向和近邻集合，而不是一个小型的演示集。 - Train/dev/holdout 触发器套件现在将迭代调整与最终验证分开。 - 描述优化现在使用 dev 进行排名，使用可见 holdout 防止回归，使用盲测 holdout 进行接受，使用对抗性 holdout 进行更严格的路由冲突检查，而不会馈送排名循环。 - 评委支持的盲测评估现在为盲测 prompt 添加了基于 rubric 的第二意见，因此盲测接受不再仅由一名评分者决定。 - 描述漂移历史现在记录对抗性校准差距和家族覆盖率，因此可以根据置信度和家族稳定性来判断路由更改，而不仅仅是原始错误计数。 - 路由混淆现在在 root 元技能、前端审查技能、governed 事件技能和 `no_route` 案例之间进行显式跟踪，因此路由窃取是可见的而不是隐式的。 - 晋升策略现在要求在认为描述可晋升之前，可见 holdout、盲测 holdout、对抗性 holdout 和路由混淆必须保持清洁。 - 晋升检查现在会发出显式的决策、候选生命周期状态、迭代 bundle 和人工审查存根，而不是将晋升仅作为一个纯文本步骤。 - 晋升决策现在区分“没有候选方案击败当前方案”和“当前方案仍有残余路由风险”，因此可以对迭代进行审计，而无需强制将每个问题都变成一个错误阻碍。 - 打包验证现在使用显式合约和 YAML 解析，但它仍然是一个轻量级的本地验证层，而不是一个完整的平台集成套件。 - `evals/failure-cases.md` 捕获了应继续作为回归检查一部分的已知弱点。 - `failures/` 捕获了用于路由、打包和创作失败的可复用反模式描述和机器可运行失败案例。 - `tests/verify_packager_failures.py` 检查无效元数据、无效 YAML 和不支持的 target 是否会明确失败。 - 治理元数据和资源边界规则现在具有可运行的检查，而不是仅作为文本保留。 - 治理检查现在会发出成熟度得分，以便可以比较 governed 资产，而不仅仅是检查通过/失败。 - 描述优化漂移历史现在与主触发器回归历史分开进行版本控制，因此随着时间的推移可以看到路由改进。 - 迭代证据现在通过共享的回归原因分类和 bundle 制品记录了保留、阻碍或晋升候选方案的原因。 - 声明的成熟度级别会根据推荐的最低治理得分进行检查，因此可以比较 `production`、`library` 和 `governed` 资产，而无需强制将每个强大的示例都归入相同的标签。 - 上下文预算现在是分层的且显式的，因此 governed 技能仍然可以选择更严格的 `production` 大小的初始加载预算。 - 资源边界检查现在会检测装饰性目录并计算本地质量密度信号，而不是仅检查原始 token 计数。 ### `templates/` 用于简单和更高级技能包的入门模板。 ## 如何使用 ### 1. 直接使用技能 在以下情况下调用 `yao-meta-skill`： - 创建新技能 - 改进现有技能 - 为技能添加评估 - 将工作流转化为可复用的包 - 为更广泛的团队采用准备技能 ### 2. 生成新的技能包 典型流程是： 1. 描述工作流或能力 2. 识别触发短语和输出 3. 选择 scaffold、production 或 library 模式 4. 生成包 5. 如果需要，运行大小调整和触发器检查 6. 从 Skill IR 合约导出特定于 target 的兼容性制品 ### 3. 导出兼容性制品 示例： ``` 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 ``` ## 优势 - **方法优先，而非 prompt 优先**：技能创建被视为具有原型、门控选择和非技能决策的正式工程工作流。 - **设计上感知触发器**：通过路由混淆、盲测 holdout、对抗性家族和晋升策略来优化描述，而不是一次性的直觉。 - **entrypoint 轻量**：`SKILL.md` 保持精简，仅在物有所值时才添加参考资料、脚本和评估。 - **工具链支持**：可通过一个统一的 CLI 和 CI 路径进行初始化、验证、优化、报告、打包和测试。 - **作为资产进行治理**：重要的技能可以包含所有权、生命周期状态、成熟度期望和审查节奏。 - **默认可移植**：源元数据保持中性，同时 adapter 和降级规则在 target 环境中保持兼容性。 - **丰富的证据**：路由评分卡、回归历史、上下文预算、可移植性得分和晋升决策作为制品发布，而不是隐藏的实现细节。 ## 最佳契合 此项目最适合： - agent 构建者 - 内部工具团队 - 向结构化技能过渡的 prompt 工程师 - 构建可复用技能库的组织 ## 文档 | 语言 | 入口 | | --- | --- | | 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) | ## 示例和评估 - 示例：[examples/README.md](examples/README.md) - 评估：[evals/README.md](evals/README.md) - 失败库：[failures/README.md](failures/README.md) - 失败回归检查：[verify_failure_regressions.py](tests/verify_failure_regressions.py) - 回归历史：[reports/regression_history.md](reports/regression_history.md) - Root 治理得分：[reports/governance_score.json](reports/governance_score.json) - 打包合约：[references/packaging-contracts.md](references/packaging-contracts.md) - 治理模型：[references/governance.md](references/governance.md) - 资源边界规范：[references/resource-boundaries.md](references/resource-boundaries.md) - 平台能力矩阵：[references/platform-capability-matrix.md](references/platform-capability-matrix.md) - 失败 fixture：[tests/fixtures](tests/fixtures) - Adapter 快照：[tests/snapshots](tests/snapshots) - 演进示例：[examples/evolution-frontend-review/README.md](examples/evolution-frontend-review/README.md) - Governed 示例：[examples/governed-incident-command/design-summary.md](examples/governed-incident-command/design-summary.md) - Governed 示例得分：[examples/governed-incident-command/generated-skill/reports/governance_score.json](examples/governed-incident-command/generated-skill/reports/governance_score.json) ## License MIT。请参阅 [LICENSE](LICENSE)。

标签：AI治理, Homebrew安装, LLM框架, 人工智能, 多模态安全, 大模型评估, 技能工程, 文档结构分析, 用户模式Hook绕过, 逆向工具