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