arcdodo Skill Factory From Case
把一个成功案例反向拆解成可复用的 Codex skill。
目标不是写一段漂亮提示词，而是给 agent 搭一个小型操作系统：触发条件、阶段流程、状态文件、契约、参考资料、脚本模板和验证机制。
核心模型
反向分析时，把案例拆成四层：
- 流程层：阶段、检查点、用户决策、必须暂停的位置。
- 契约层：目录结构、命名规则、schema、唯一真相源、不变量。
- 判断层：什么叫好、什么叫差、反模式、自检清单。
- 自动化层：脚本、模板、资产、可重复命令、确定性搭建步骤。
SKILL.md 只放每次运行都必须知道的规则。详细规范、示例、变体和检查表放进 references/。重复且易错的操作放进 scripts/。可复用输出骨架放进 templates/ 或 assets/。
工作流
Phase 1: 理解案例
收集这些材料：
- 成功案例文件夹、现有 skill、提示词、流程文档、脚本、仓库或样例输出
- 目标用户会怎么使用这个 skill
- 至少 3 条可能触发 skill 的用户说法
- 期望最终产物
- 已知失败模式
如果用户只给了模糊想法，优先要一个具体例子；如果可以安全假设，就先做最小可用版，并说明假设。
分析真实案例时读 references/CASE-ANALYSIS.md。
Phase 2: 提炼方法
先产出一份方法地图，再写 skill：
- 输入类型：用户可能给什么
- 输出产物：skill 最终应该交付什么
- 阶段流程：工作顺序
- 硬检查点：哪些节点必须停下来和用户对齐
- 状态文件：哪些文件保存用户决策或中间真相
- 唯一真相源：哪个文件/字段防止多处漂移
- 质量门槛：汇报完成前必须检查什么
- 引用拆分：哪些内容应该移出
SKILL.md - 自动化候选：哪些脚本/模板/资产值得打包
- 问题边界：代表性任务是否共享输入、流程、Gotchas、验收和风险
方法地图不清楚时，不要急着写文件。
设计前使用 $audit-skill-design 的“五同测试”判断边界。行业、输出类型或工具不同不自动意味着需要拆分；如果代表性任务无法共享核心流程或验收标准，应先拆分再创建。
Phase 3: 设计 skill 架构
默认结构：
skill-name/
├── SKILL.md
├── references/
│ ├── METHOD.md
│ ├── OUTPUT-SPEC.md
│ └── CHECKLIST.md
├── scripts/
│ └── optional-deterministic-task
└── templates/
└── optional-output-scaffold
只保留必要文件夹。除非用户明确要发布包，否则不要加 README.md、changelog、安装指南或宽泛用户文档。
创建文件前读 references/SKILL-ARCHITECTURE.md。
创建新 Skill 时优先使用 skill-creator 提供的 init_skill.py 初始化，并生成匹配 SKILL.md 的 agents/openai.yaml。更新现有 Skill 时检查 metadata 是否仍然匹配。
Phase 4: 编写 skill
按这个顺序写：
SKILL.mdfrontmatter：准确的name和触发覆盖完整的description。SKILL.md正文：精简流程、何时读哪些文件、何时停、如何验收。- reference 文件：详细规范、反模式、示例、检查表。
- scripts/templates/assets：只在能减少重复脆弱劳动时加入。
规则：
- 标题用动作导向。
- 路由规则、文件契约优先用表格。
- 明确 agent 必须做什么、什么时候停、完成前验证什么。
- 判断空间大的地方给原则；容易漂移或破坏的地方给硬规则。
- 不要在
SKILL.md和 reference 里重复大段相同内容。
Phase 5: 验证
交付前按 references/VALIDATION.md 自检。
最低检查：
- frontmatter 有
name和触发充分的description SKILL.md说清楚何时使用- workflow 有阶段和停顿点
- reference 都从
SKILL.md直接链接 - 每个脚本/模板/资产都有明确用途
- 没有不必要文档
- 至少有一个质量门槛
- 冷启动 agent 不依赖隐藏上下文也能使用
发现失败项后先修，再告诉用户 skill 做好了。
如果环境提供 quick_validate.py，运行它检查结构。随后使用 $audit-skill-design 对成品做一次自身审查；至少验证问题边界、触发、Gotchas、完成条件和资源用途。复杂 Skill 应使用真实请求进行前向测试。
交付说明
交付生成的 skill 时，简短说明：
- 创建位置
- 关键文件
- 编码了哪套方法
- 做了什么假设
- 进行了什么验证
重点是产物本身，不要长篇解释。