oma-skill-creation

OMA 技能编写

调度

目标

创建或修订可用的 OMA 技能，确保路由清晰、执行路径唯一、具备特定领域的恢复措施，并合理控制上下文。

意图特征

• 创建、更新、审计或规范化 OMA 技能、其资源或 SSL-lite 格式。
• 判断内容应放在正文中、条件加载的资源中，还是应当删除。

适用场景

• 编写 .agents/skills/{name}/SKILL.md 及其支持资源。
• 审查技能路由、执行约定、参考资料加载或重复指令。

不适用场景

• 安装第三方技能 → 使用技能安装器；创建 Codex 插件 → 使用插件工具。
• 应用实现 → 交由负责的专家处理；项目需求 → 使用 oma-pm。

预期输入

技能用途、触发条件、边界、执行模型，以及需要保留的现有命令、资源或用户编辑内容。

预期输出

包含四个部分的 SKILL.md、仅有必要的支持资源，以及验证结果和未解决的限制。

依赖项

使用 resources/ssl-lite-template.md 提供骨架，使用 resources/validation-checklist.md 提供验收标准。使用原生文件工具和可用的 oma skill 验证器。遵守关于源文件归属和生成副本的仓库规则。

结构流程

转换

• 新技能：对比 1–3 个类似技能，然后使用模板。
• 现有技能：保留有效的领域细节，只修改请求涉及的范围。
• 重复指令：保留一个权威位置；独立调用的入口需要时，添加简短引用。
• 篇幅较长或带条件的细节：移至具名资源，并注明加载条件。不要仅仅为了将副本放在别处而移动重复内容。
• 可由机器检查的产物：按模板文档所述声明结构化的 outputs:。

失败与恢复

失败	恢复
路由范围过宽	收紧触发条件，并添加具体的“不适用场景”交叉路由
执行说明含糊	在规范路径中补充实际对象、路径、命令标志和证据
多个部分中重复相同流程	保留规范流程；其他位置仅保留不同分支或状态转换
必需工具不可用	使用文档说明的回退方案；否则报告无法验证的结果
源文件与生成副本冲突	使用仓库的生成流程；不要手动编辑受保护的定义

结束条件

完成的技能应具备有效的结构、实用的路由、可执行的步骤、可恢复的失败处理、有效的引用和适用的验证证据。缺少的工具或未解决的假设必须明确说明。

逻辑操作

规范工作流

1. 阅读目标文件、其调用的资源和相关仓库规则。确定哪些入口会独立运行，以及运行时已注入哪些内容。
2. 选择命令密集型、判断密集型或参考资料密集型行为。使用模板的最简骨架，仅在能提供额外信息时添加可选部分。
3. 只编写一次规范流程。保留准确的命令和输出约定、失败机制、副作用及有害操作限制；删除泛泛的重复说明和多余示例。
4. 在 References 下为资源编制索引，并注明加载条件。尽可能使源文件旁的证据与 SKILL.md 仅隔一跳。
5. 运行 oma skill lint --skill <name> 和 git diff --check。如果路由描述有变更，再运行 oma skill audit。应用 resources/validation-checklist.md 中自动 lint 无法覆盖的内容检查。
6. 报告变更、检查结果和剩余限制。仅删除重复文件并不能证明 token 用量减少；只有在声称用量减少时，才测量实际加载的上下文。

资源范围与影响

Skill 工作会通过授权的仓库流程读取和更改本地定义/资源以及生成的供应商副本。用户数据和凭据不是 Skill 示例。提交和发布需要相应授权。

防护措施

1. 保留 YAML name 和可用于路由的 description。保留四个顶级标题：Scheduling、Structural Flow、Logical Operations、References。
2. 保留一条规范的命令/工作流路径、Intent 签名、何时使用/何时不使用、输入/输出预期、失败恢复，以及相关影响/防护措施。如果某些信息已通过其他方式呈现，则可省略这些以外的章节标题。
3. 入口、场景、操作以及工具/范围表必须提供不同的信息。不要为了填充模板而重复流程。
4. 将 SKILL.md 控制在 500 行正文以内。按需加载辅助资源；不要在 Skill 中创建 README/变更日志/安装文档来解释 Skill。
5. 保留解析后的输出/架构示例。不要规定装饰性报告布局，也不要添加通用的自我审查循环；使用可运行的验证器和明确的证据要求。
6. 使用确定性工具处理批量数据，并返回摘要/产物路径，而不是将原始数据流式传入上下文。
7. 保留无关的用户编辑。将共享执行策略应用于澄清、授权和验证。

参考资料

• 提示词行为和模型比较：resources/prompt-evaluation.md（路由、注入、授权或审查约定变更时）
• 骨架和可选章节：resources/ssl-lite-template.md（编写或重构时）
• 验收标准：resources/validation-checklist.md（验证时）
• 上下文加载：../_shared/core/context-loading.md（资源/注入决策）
• 质量原则：../_shared/core/quality-principles.md（领域验证要求）
• 评估夹具：web/docs/guide/skill-eval.md（使用 oma skill eval 或 oma skill optimize 衡量留出任务效用时）