oil-skill-creator
把 Skill 当作需要长期维护的工具。先确认它解决了重复问题，再让它容易开始、稳定执行、能够验证，并如实说明兼容范围。不要把一次任务的提示词包装成 Skill。
先选择模式
| 模式 | 适用情况 | 路径 | 默认停止点 |
|---|---|---|---|
| 创建 | 还没有 Skill | 产品定义 → 最小骨架与评估 → 基线 → 实现与对照 → 按需发布 | 交付可用 Skill |
| Review | 用户只要求评审、审计或找问题 | 读取 → 需求适用表 → 静态检查 → 流程检查 → 报告 | 交付报告后停止 |
| 整改 | 已有 Skill，用户要求修复或优化 | 读取 → 需求适用表 → 静态检查 → 按需保存快照 → 局部修改 → 复验 | 问题修复且无回归 |
| 商业化 | 想为 Skill 收费，或评审已收费的 Skill | 能否收费 → 分界 → 引流与落地页 → 收款 → 交付与更新 | 交付方案或改好的 Skill |
Review 只读：不修改文件、不创建快照、不打包。用户看完报告再授权整改时，从整改路径重新开始。整改不用脚手架重建已有目录，只在用户要求交付发布包时打包。
开始前
已有 Skill 时，先完整读取 SKILL.md，再只读取当前模式和问题需要的资源。已有信息不要再问。只有目标或交付物不清楚、需要新增权限或服务、可能覆盖内容，或者主观方向会改变结果时才询问，并把问题一次问完。
分工如下：
- Agent 判断价值、边界、架构、例外和主观质量。
- 程序执行确定、重复、可验证、失败敏感的步骤。
- 隔离执行者运行触发测试和效果对照。它不继承作者的工作上下文，只拿到本次请求和指定 Skill，通常是子 Agent。
- 人判断审美、文案和整体体验。
下文的 <python> 指已确认版本不低于 3.10 的 Python 解释器：macOS 和 Linux 通常是 python3，Windows 通常是 py -3。不要假设 python 命令一定存在。
创建路径
先读 产品设计，确认问题值得做，并明确用户、当前做法、预期改善、输入、输出、边界、风险和任务类型。一次性需求、普通 Agent 已能稳定完成，或者说不清使用后会改善什么时，不要强行创建。
需要脚手架时先预览最小骨架，确认后去掉 --dry-run 再运行一次；骨架只确定目录和元数据，不先写长说明：
text<python> <oil-skill-creator>/scripts/scaffold_skill.py <skill-name> --output-root <目录> --description <描述> --public --dry-run
只用 --components 添加当前确实需要的目录，例如 --components scripts,tests，不为示例完整而创建空资源。需要版本号时加 --version 0.1.0。
再读 评估规范，准备至少 3 条真实评估并固定模型和执行者，先运行 without_skill 基线，再开始大量编写：
text<python> <oil-skill-creator>/scripts/prepare_evaluation.py <skill-path> --mode create --iteration 1 --model <模型> --executor <隔离执行者> --allow-missing-skill
--allow-missing-skill 只在目录还只有 evals 时使用；已有最小骨架可省略。基线完成后按“设计和编写”实现最小候选，沿用同一 run_plan.json 运行 with_skill，聚合并检查结果，再运行程序校验。
Review 与整改路径
先读 Review 与整改规范，按其中的检查顺序执行。三个节点不能跳过：
- 运行校验器之前先建需求适用表，批量评审时逐个 Skill 登记。需要用户输入 Key 的 Skill，第一次 Review 就核对凭据入口，这一项最容易漏。
- 校验器只确认结构问题。Skill 是否有用、流程是否合理、兼容性是否属实，要另外检查。
- 按 P0、P1、P2 报告。Review 交付报告后停止。
整改第一次编辑前判断是否需要旧版快照：要让隔离执行者运行旧版做前后对照、用户要求保留独立基线，或旧版无法从 Git 等可靠来源恢复时，运行 <python> <oil-skill-creator>/scripts/snapshot_skill.py <skill-path>；其他整改不建快照，直接局部修改并复验。
商业化路径
先读 商业化，按其中顺序推进：先回答“能不能收费”的四个问题，答不上就停在免费版并说明原因；能收费时再依次规划分界、引流与落地页、收款渠道、交付与更新。评审已收费的 Skill 时只做其中的“商业化体检”，按 Review 的规则只读交付。
设计和编写
核心规则：
- 触发信息只放在 frontmatter
description：做什么、什么时候用、哪些相似请求不该触发、与其他 Skill 怎么分工。先讲任务和产物，不用模型、服务商或宿主的名字代替功能介绍。正文不重复触发规则。 - 默认宿主中立：正式指令、参考资料、README、目录名和示例使用“Agent、宿主、能力、隔离执行者”等通用名称。确实依赖某个宿主时，专用适配器与通用流程分开，并在兼容性中写明。
- 登录、密钥、系统安装、覆盖、删除和外部写入先获得授权。密钥值不进 JSON、Skill 文件、日志或 Agent 上下文。
- 重复运行初始化或迁移不能破坏已有配置或产生重复结果。失败时保留可用的中间产物，说明停在哪一步、怎么恢复、还有哪些必做步骤没执行。
- 正文写目标、判断原则、主流程、必要分支和停止条件，不穷举情境。一步只表达一个主要动作，分支紧邻对应步骤，术语保持一致。有限、稳定、可验证的分支交给程序；依赖语义的选择留给 Agent。
- 只写能用于同类任务的规则、程序和回归测试。具体任务、个人目录、单次候选、Review 记录和修改历史不进 Skill。
- 不得包含与 description 不一致的隐藏行为、误导能力、越权访问或数据外传。兼容性只声明实际实现或真实验证过的范围。
按问题读取参考资料：
| 要解决的问题 | 参考 |
|---|---|
| 首次使用、配置、确认操作、失败恢复；大型产物分段产出或可复用操作页面 | 产品设计 |
| 批量、破坏性、复杂校验或高代价操作 | 计划、校验与执行 |
| 宿主依赖、平台差异、普通配置与凭据存储 | 兼容性 |
| 本机需要输入 API Key 等单行凭据，且没有现成安全入口 | 凭据输入页，用安装脚本接入随附组件，不为每个 Skill 重新生成页面 |
| 拆分文件、篇幅、目录导航、Token 开销、弱模型可读性 | 信息架构 |
| 触发准确性、效果对照、迭代与停止 | 评估规范 |
| README、安装入口、发布门槛、打包、密钥筛查 | GitHub 发布 |
| 版本号设置、升版、标签 | 版本管理 |
| 收费、免费版与付费版、收款、交付、更新提示 | 商业化 |
程序校验
开发过程中运行 <python> <oil-skill-creator>/scripts/validate_skill.py <skill-path>。公开发布或整改完成前加上严格选项：
text<python> <oil-skill-creator>/scripts/validate_skill.py <skill-path> --public --strict --weak-model --universal
--weak-model 使用更严格的结构限制，--universal 检查是否写死了宿主品牌或专属路径；只有产品明确依赖某个宿主时才省略 --universal，并在兼容性中说明原因。校验通过只说明程序能确认的问题没有出现，不说明 Skill 有用。
效果评估
用户要求证明效果、整改带来静态检查确认不了的重大行为变化，或者正式发布需要效果证据时，按 评估规范 用程序准备目录、运行、聚合并生成评审页。创建模式与普通 Agent 对照，整改模式与写入前的快照对照。目标明确的小范围修正，用静态校验和针对性回归即可。
把候选结果、证据和对比报告交给用户，收到反馈前不再修改 Skill。没有隔离执行能力时，说明评估受限，不宣称已完成独立对照。效果不好时先查明原因，不直接追加规则。
兼容与发布
发布前读 兼容性 和 GitHub 发布，按其中的门槛检查并打包。README 面向使用者，说明价值、安装、配置、兼容范围、数据边界和输出，不复制 Agent 的执行步骤。版本号只记在源 Skill 的 metadata.version，按 版本管理 设置和升版。
完成标准
- 创建：价值成立，主流程可执行，静态校验通过，已说明效果证据与未验证项。
- Review：结论有证据，缺陷与取舍分开，给出按优先级排列的最小整改方案，没有修改文件或外部状态。
- 整改：需求适用表逐项有实现和验证证据，凭据项覆盖页面、保存、恢复和实际业务读取；P0、P1 已处理或由用户明确接受；相关回归测试通过，没有覆盖无关内容；做了前后效果对照的，快照和对照证据完整。
- 商业化：先给出能否收费的结论；规划或改动覆盖分界、引流、收款、交付和更新，没有遗漏的半截流程。
交付时只报告文件路径、主要能力、程序与测试结果、已确认的兼容范围、效果证据和剩余风险。不复述整个 Skill，也不把执行过程写回正式文件。
