ray-skill-generator — Skill 制作器

从零创建 AI Agent Skill 的元工具。整合了业界多套方法论：

• 六步创建流程：理解示例 → 规划内容 → 初始化 → 编辑 → 打包 → 迭代
• 五阶段质量审计：需求澄清 → 设计 → 构建 → 验证 → 发布
• 四类型分类：Tool / Workflow / Capability / Scenario
• 核心设计原则：渐进式披露、imperative 写作、安全审查、反模式扫描

> 定位分工：本 skill 管从零创建；ray-skill-evolve 管已有 skill 优化（外部搜索对比找差距）。两者互补——创建后交给 evolve 持续进化。

四个 Skill 类型（先判类型，再选模板）

判断口诀："这个 skill 是'做一件事'（Tool）、'走一套流程'（Workflow）、'懂一个领域'（Capability）、还是'扮一个角色'（Scenario）？"

渐进式披露原则（三层加载，贯穿全程）

Level 1: frontmatter（name + description）—— 常驻 ~100 词，决定触发
Level 2: SKILL.md 正文 —— 触发时加载，目标 <600 行软上限 / <8000 token（信息密度优先，不为压行数砍内容）
Level 3: references/ —— 按需加载，不触发零成本

铁律：详细内容（schema/模板/案例/清单）放 references/，SKILL.md 只留核心流程 + 索引。信息只存一处（SKILL.md 或 references，不同时存）。

脱敏原则（v1.2 新增，创建时就遵守，不等到发布前补救）

> 脱敏不是发布前的"最后一道工序"，而是写每一行时的默认习惯。三处都要脱敏：正文来源署名、维护记录第三方名、示例/实战经验的个人隐私。

保留项（不脱敏）：功能性引用（neat-freak 关系表、xlsx 插件示例）+ 工具/依赖包名（qwen-tts、edge-tts、python-pptx）——这些是 skill 运作依赖，删了破坏功能。

创建完验证：Phase 3 用 sanitize_skill.py 扫描确认零残留（这是"确认"不是"补救"——写的时候就应该干净）。

五阶段创建流程

Phase 0：需求澄清（不能跳过）

先理解具体使用场景，再动手。问最核心的 2-3 个问题（一次别问太多）：

• "这个 skill 解决什么问题？"
• "举个具体使用例子——用户会怎么说、期望什么结果？"
• "属于哪种类型？（Tool/Workflow/Capability/Scenario）"

触发词设计：明确"用户说什么话会触发这个 skill"，写进 description。第三人称（"This skill should be used when..."），禁结尾空话（"灵活应用/根据情况"）。

问题契约 + 行为契约（v1.12 新增，澄清产出落纸，不留在脑子里）——需求澄清的结论写成两段契约再进设计：

问题契约：反复出现的问题 / 使用情境 / Skill 应交付的结果 / 完成证据（什么算做完了）/ 不处理的近邻问题
行为契约：目标任务 / 输入变化范围 / 必须做到 / 禁止出现 / 允许变化 / 关键失败（最不能发生的错）

• 价值：①"好用、聪明"等模糊要求被迫改写成可观察行为，验证阶段直接对照；②"不处理的近邻问题"提前圈出边界，与 near-miss 验证互为表里；③问题太一次性、成功无法观察 → 当场说明"不适合沉淀成 skill"，省下整个后续流程。

Phase 1：设计

1. 规划可复用内容：分析使用例子，列出需要的 scripts/（可执行代码）、references/（按需加载文档）、assets/（输出用文件）
2. 确定类型 + 模板：见 references/skill-types.md
3. 冻结设计：写清 skill 的 purpose、触发条件、核心流程、资源清单

规划原则（来自官方）：
- 同一段代码反复重写 → scripts/（token 高效、确定性）
- 需要查的 schema/规范/知识 → references/
- 输出要用的模板/图标/字体 → assets/

工具准备与可持续进化（v1.9 新增，通用原则）——创建任何 skill 前，按具体功能先想清楚"要准备哪些工具"，并让工具成为随任务持续沉淀、优化、增强的活资产：
- 按功能定工具：从需求倒推需要哪些 scripts/ 可执行工具——检索类要搜索渠道库、分析类要打分/聚合脚本、转换类要格式转写器、生成类要模板引擎——工具是能力的主体，SKILL.md 只是说明书
- 工具可持续进化：工具不是一次写死，要设计成随任务生长——自带反馈回流口（任务执行中发现边界案例→修正脚本）、版本化（每次进化 bump 版本）、可测试（跑一次验证输出）。ray-synth-search 的公式边界断言就是工具进化的实例
- 内置沉淀口：在 SKILL.md 中显式声明"任务中发现的新渠道/新规则/新边界案例 → 记入待沉淀区 → 任务结束前正式入库"，让每次执行都产生活资产
- 判断口诀："这个 skill 的能力靠什么实现？" 靠脚本 → scripts/ 做主体；靠知识 → references/ 做主体；靠模板 → assets/ 做主体。别让 SKILL.md 同时承担知识和工具——工具与知识分离，各自才能独立进化

检索/搜索类 skill 设计特例（v1.8 新增）——创建以"查信息"为核心能力的 skill 时默认采用（工具层原则在内容层的应用）：
- 内置高价值渠道库（references/source-database.md）：按任务类型分类（通用/专业标准/学术文献/官方政策/公众号/财经/开放数据/健康/素材）+ 三维评分（权威性 × 广度 × 深度，各 1-5）+ A/B/C 分级 + 动态更新机制（任务中发现新渠道 → 记入"待沉淀区" → 任务结束前正式入库）——渠道库是活资产，每次执行都是喂数据的机会，不用一次性静态清单
- 交叉验证必须量化：一致性分数 =（独立度×0.4 + 契合度×0.3 + 权威度×0.3）×100，且矛盾否决 + 强制封顶 ≤39——仅加权会让"权威源矛盾"错落 ✅ 区间（矛盾只能把契合度降到 0，权威度仍把总分拉高）
- 量化公式交付前跑边界断言：用 4 组代表性场景（权威源一致/权威源矛盾/弱源矛盾/单源）断言各自落标区间，公式自洽才可用

Phase 2：构建

1. 初始化脚手架：
   bash python scripts/init_skill.py <skill-name> [--type workflow]
   生成 SKILL.md 模板 + scripts/ + references/ + assets/ 空目录

2. 编辑 SKILL.md，回答三个问题：
   - 目的是什么（几句话）？
   - 何时使用（触发词）？
   - 实际怎么用（引用所有可复用资源）？

3. 写作风格（官方铁律）：
   - imperative 第三人称："To do X, run Y" 而非 "You should do X"
   - 客观指令式，不写"你"
   - 写"为什么"不只写"怎么做"——让 AI 理解背后原因

4. frontmatter 必填：name（小写连字符）、description（做什么+何时用+触发词）、version（SemVer x.y.z）、agent_created: true
   - 可选字段（v1.1 新增）：alwaysApply: false（大多数为 false，true 表示满足条件自动触发）；disable-model-invocation: true（仅手动触发，模型不自动调）
   - description 禁止写工作流总结（会令 agent 跳过主体，只看 description 就动手）——写"做什么 + 何时用"，不写"怎么做"
   - description 不得含 < > 字符、≤1024 字符（外部规范硬约束，v1.10 新增）

5. 环境变量占位符规范（v1.10 新增）——SKILL.md 与 scripts/ 中禁止硬编码真实值（API Key、路径、账号、主机地址），一律用 {{VAR_NAME}} 占位：

原因：skill 可能被发布/分发，硬编码真实值 = 泄露隐私 + 换环境即坏。占位符让 skill 可移植且无泄露风险。

5.5. 禁止文件清单（v1.10 新增）——skill 目录内只放功能必需文件，以下杂项文件一律不建：
- ❌ README.md ❌ INSTALLATION_GUIDE.md ❌ QUICK_REFERENCE.md ❌ CHANGELOG.md ❌ 其他说明文档
- 原因：这些文件不参与功能执行，只增加 clutter 和上下文噪音；维护记录放 references/changelog.md 即可（这是惯例例外，不违反禁项）
- 反模式黑名单同步补 2 条（见下）

5. 脱敏三规则（创建时内建，v1.2 新增）——写 SKILL.md 时就遵守，别等发布前才查：
   - 不写来源署名：不写"借鉴 xxx / 来自 xxx / 基于 xxx"，方法论直接写成自己的表述（"整合了业界多套方法论"而非"借鉴 xxx 的五阶段流程"）
   - 不写个人隐私：不写真实金额（¥xx万）、账号、基金名/股票名等个人财产数据；示例数据用占位符（XXXXXX）或模糊表述（"某中短债基金"）
   - 维护记录不列第三方名：写"对比外部 skill 吸收 N 项"，不写具体 skill 名

6. 弱模型适配写作三件套（v1.6 新增，提升信息密度、帮弱模型跑好）——写 skill 正文时遵守：
   - 输出格式模板：写死输出格式并带占位符（如"流量 = X m³/h；压力降 = Y kPa，小数点后保留两位"），不写"把结果写清楚"这类自由发挥指令——弱模型对严格格式很顺从，对自由发挥不擅长
   - Few-shot 示例：给 1-2 个完整"输入 → 输出"示例（如"输入：D=200, Q=50 → 输出：压力降=1.234 kPa"）——弱模型靠模式匹配就能跑得很好
   - 结构化标记：用 XML/Markdown 标签（<example>/<constraint>/## 输出格式）分隔不同部分，帮模型快速定位

7. 三档自由度（v1.7 新增，写每个章节前先选档）——不是所有章节都要同等具体，按操作脆弱性 × 有效变化空间给精确度分级：
   - 低自由度（精确命令/脚本）：操作脆弱易错、搞错代价高（文件修改、API 调用、多步有依赖的流程）→ 写死命令和步骤顺序，不许偏差
   - 中自由度（参数化伪码）：有已知好模式但细节随上下文变（配置生成、文件结构）→ 给带参数的模式模板
   - 高自由度（启发式文本）：决策依赖运行时上下文（用户代码库、项目类型）、创造性判断有价值（分析、建议）→ 写启发式和考虑因素，不写死步骤
   - 判断口诀："这一步搞错了会坏吗？会 → 低；有好模式但细节会变 → 中；多条路都对 → 高。"与弱模型三件套互补：三件套教"输出格式写多具体"，自由度教"哪些章节该具体、哪些放权"

8. Definition of Done 章节（v1.5 新增，模板必带）：新建 skill 的 SKILL.md 必须包含 ## Definition of Done 章节，列出可测量的完成标准——"skill-test 评分 ≥85 无 critical"、"至少 3 个示例 prompt"、"frontmatter 含 name/description/version"、"核心脚本跑通"等。为什么：没有 DoD 的 skill 是"做完就行"（主观），有 DoD 的 skill 是"满足 N 条标准才算完成"（可验收）——DoD 让 skill 的完成从"感觉"变成"测量"，验证阶段（Phase 3）直接对照 DoD 逐条打勾即可。同时模板带 ## When Not to Use 边界章节（列出不应触发本 skill 的场景），与 near-miss 验证互为表里。
   - ## Gotchas 章节（v1.7 新增，模板必带，与 DoD 同级）：承载环境专属怪癖—— defy 合理假设的事实：字段其实是带逗号的字符串、接口失败也返回 200、某步必须跑两遍。来源是构建中踩的坑与验证阶段的修正，随运行持续累积。None known 是合法值；⚠️ 禁止编造 gotcha 凑数——假怪癖会教模型一个错误约束，之后它一直绕着走。

Phase 3：验证（发布前必做）

# ① 健康检查（尺寸/去重/精简/卸载/失败模式/反例/脱敏/frontmatter）
python ~/.workbuddy/skills/ray-skill-evolve/scripts/health_check.py <skill目录>

# ② 脱敏扫描（来源署名清零）
python ~/.workbuddy/skills/ray-skill-evolve/scripts/sanitize_skill.py <skill目录>

# ③ 安全审查（见 references/security-review.md）
# ④ dry-run 验证
cd ~/.workbuddy/skills && skillhub publish ./<skill名> --dry-run --json

量化评分闭环（v1.10 新增，配合健康分使用）——健康分给"总分"，9 维评分给"短板定位"：

评分方法：9 维各 1-10 分，<7 分的维度当场补强，重跑健康检查确认总分提升。健康分 ≥B 且 9 维无 <7 → 才进入验证下一步。

验证标准：健康分 ≥B、脱敏零来源署名残留、安全审查无红旗、dry-run 通过。

分级验证等级报告（v1.12 新增，诚实汇报纪律）——交付时按实际达到的最高等级报告，不许跳级宣称：

• 留出样本 = 建评测集时扣下不给执行者看的样本——执行者看过答案再跑就不算数
• 只跑到等级 1 时，只能说"结构校验通过"，不能说"skill 已验证可用"

触发双向验证（v1.3 新增）——证明 description 写得准：
- should-trigger：写 3 个典型用户 prompt（用户会怎么说），确认能正确路由到本 skill
- near-miss：写 3 个边界模糊的反向用例（关键词相似但不该触发本 skill），确认不误触发。例：建 PDF 处理 skill 时，near-miss 用"把这个 PDF 内容做成 PPT"（应路由 PPT skill）而非"今天天气如何"——明显无关的查询没有测试价值
- 误触发 → 在 description 补"不适用场景"边界
- 量化升级（v1.12 新增）：3+3 手工用例之外，重要 skill 建静态评测集 ~20 条（should-trigger 与 near-miss 各半，含口语/缩写/ typo 变体与"关键词撞车但应路由别处"的难例）；有条件时切 60/40 训练/测试两份——description 只按训练份调，测试份只做最终验收，防过拟合（改出来的 description 只对写过的用例生效 = 白改）
- description 适度"推"（官方经验，v1.12）：模型有 undertrigger 倾向（该触发不触发），description 在准确基础上可适度 pushy——把相关场景明写进去（"whenever the user mentions X, even if they don't explicitly ask"），比堆关键词有效

RED/GREEN 双门控（v1.11 新增，替代原增量价值验证）——证明 skill 有用，不是模型本来就会：

RED Gate（先于写 skill，只对 CREATE 场景）：
  用 1-2 个典型任务，让 fresh agent 在【无 skill】下执行
  → 记录基线失败（模型哪里做不到/做不好）
  → 基线无失败 = 这个 skill 没存在的必要，回去想清楚增量价值再动手
  → 基线有明确失败 → 进入 GREEN Gate

GREEN Gate（写完后）：
  同一任务让 agent【有 skill】执行
  → 必须清除 RED Gate 记录的全部基线失败
  → 失败仍在 → 回去补"模型不知道的东西"（领域坑/决策树/脚本/模板），
     不是堆砌模型已有的常识
  → 全清 → 行为差门控通过，skill 才成立

evals/ 随 skill 交付（v1.11 新增）——GREEN Gate 通过的测试 prompt 不丢弃，存进 skill 的 evals/ 目录（每个含 prompt + 预期行为），成为该 skill 的回归测试套件：下次优化/更新后重跑 evals 确认无回归（与 ray-skill-evolve 冒烟测试互补——evals 测行为，冒烟测脚本）。

重复造轮子信号 → 固化 scripts/（v1.12 新增，官方改进启发）：读测试执行记录（不只看最终产出）——若多个测试各自独立写出了相似的辅助脚本（都手搓了同一个转换函数/同样的多步操作），这是强信号：把它写一次放进 scripts/ 让 skill 直接调用，省掉此后每次调用的重复劳动。

> 与健康分的关系：RED/GREEN 证明"skill 有价值"（行为差），健康分证明"skill 写得好"（文档质量）——两者互补，不能互相替代。

验证失败处理（v1.0 新增）：
- 健康分 <B → 回去精简/卸载（超长段落拆表格、大代码块移 references/）
- 脱敏有来源署名残留 → 回去删"借鉴 xxx"署名，留机制描述
- frontmatter 缺字段/非 SemVer → 补齐三件套
- dry-run 失败 → 读报错信息修复（常见：.bak/.tmp 等非允许文件类型残留、name 格式错）
- 脚本报错 → 检查错误处理三路径（成功/失败/异常）是否齐全，缺则补

Phase 4：发布

按 ray-skill-evolve 的发布红线：绝不自动 publish，汇报结果后由用户当场确认。

安全审查协议（创建时就要考虑）

新建 skill 时检查自己产出的脚本/内容，不能有红旗：

权限声明：skill 需要网络/文件写/shell 权限时，在 SKILL.md 明确说明"需要什么权限、为什么"。

反模式黑名单（创建时避免）

❌ description 结尾加"灵活应用/根据情况判断"空话
❌ 只写正向流程，不写失败分支（"如果 X 失败 → Y"）
❌ SKILL.md 超 600 行仍不处理（软上限：先查冗余/结构/职责/token，仍超限才卸载；不为压行数砍信息密度）
❌ 信息重复存两处（SKILL.md 和 references 各一份）
❌ 用第二人称"你应该"（用 imperative 第三人称）
❌ 触发词模糊（"相关场景"而非具体话术）
❌ 不标注 agent_created: true
❌ 来源署名（"借鉴 xxx / 来自 xxx / 基于 xxx"）——方法论直接写成自己的表述
❌ 个人隐私（真实金额/账号/基金名）——示例用占位符 XXXXXX 或模糊表述
❌ 维护记录列第三方名——写"对比外部 skill 吸收 N 项"
❌ SKILL.md 缺 Definition of Done 章节（无可测完成标准，v1.5 新增）
❌ 只写"把结果写清楚"这类自由发挥指令（弱模型不擅长自由发挥、对严格格式很顺从——必须给输出格式模板 + 1-2 个 few-shot 输入输出示例，v1.6 新增）
❌ 编造 Gotcha 凑数（v1.7 新增）——假的"环境怪癖"会教模型错误约束，之后一直绕着走；没踩过坑就写 None known
❌ 硬编码真实值（API Key/路径/账号）——一律用 {{VAR_NAME}} 占位（v1.10 新增）
❌ 在 skill 目录建 README/CHANGELOG/QUICK_REFERENCE 等杂项文件——只放功能必需文件，维护记录放 references/changelog.md（v1.10 新增）
❌ RED Gate 基线无失败仍硬建 skill（v1.11 新增）——模型裸跑就能做好的任务不需要 skill；基线失败是 skill 存在的前提

Skill 构建陷阱（v1.1 新增）

参考资料

• references/skill-types.md — 四类型详情 + 模板选择 + 目录结构
• references/quality-checklist.md — 质量验证清单（整合 14 维审计精简版）
• references/security-review.md — 安全审查协议详情
• references/experience-archive.md — 实战经验归档（v1.10.0 卸载，按需加载）
• references/changelog.md — 维护记录（v1.10.0 卸载，按需加载）

实战经验

历史经验已卸载至 references/experience-archive.md（v1.10.0，token 精简）。当前活跃经验：

• 2026-08-16｜[LRN-20260816-001]｜正交切分 > 流水线切分（判据：两个 skill 的输出物能否完全独立）｜pending

维护记录

完整维护记录见 references/changelog.md（v1.10.0 卸载，遵守"维护记录不常驻正文"原则）。最近变更：v1.11.0（RED/GREEN 双门控 / evals 随 skill 交付）。