oma-skill-creator

Skill Creator - SSL-lite 技能编写专家

调度

目标

使用基于 Scheduling-Structural-Logical 技能表示法的 SSL-lite Markdown 结构创建、修订和验证 OMA 技能，同时确保结果易读、可执行且易于维护。

意图特征

• 用户要求创建新的 OMA 技能、Agent 技能、专业技能或 .agents/skills/*/SKILL.md。
• 用户要求将技能转换为或规范化为项目技能格式。
• 用户询问技能是否包含足够的调度、结构、逻辑、参考资料或规范执行细节。
• 用户提到 SSL-lite、Scheduling / Structural / Logical、技能格式、技能模板或 skill creator。

何时使用

• 在 .agents/skills/{name}/SKILL.md 下创建新技能
• 将现有 OMA 技能更新为 SSL-lite 格式
• 为执行密集型技能添加 Canonical command path 或 Canonical workflow path
• 审核技能是否可供路由、执行、验证和恢复逻辑使用
• 决定详细示例应内嵌还是放在 resources/ 中

何时不使用

• 将第三方技能安装到 $CODEX_HOME/skills -> 使用 Codex 内置的技能安装程序（外部工具；不是 OMA 技能）
• 创建 Codex 插件包 -> 使用 Codex 插件工具（外部工具；不是 OMA 技能）
• 编写与技能创作无关的通用项目计划 -> 使用 PM Agent
• 直接编辑产品代码、基础设施、前端、后端或移动端实现 -> 使用对应的专业技能

预期输入

• skill_name：目标目录名称，建议使用 oma-{domain}
• skill_goal：该技能应增加的能力
• trigger_intents：应触发该技能的用户提示或领域
• boundaries：不应使用该技能的情形，以及应由哪个技能处理
• execution_model：技能属于命令密集型、工作流密集型、判断密集型还是参考资料密集型
• 必须保留的现有文件、工具、命令、资源或标准

预期输出

• 使用 SSL-lite 顶层章节的完整 SKILL.md
• 仅当渐进式披露或确定性执行有此需要时，才提供可选的 resources/*.md、config/*.yaml、scripts/* 或 assets/*
• 验证报告，包含结构检查、路由检查、执行检查和未解决的假设

依赖项

• .agents/skills/*/SKILL.md 中现有的 OMA 技能约定
• resources/ssl-lite-template.md 中的 SSL-lite 模板
• resources/validation-checklist.md 中的验证清单
• 用于读取相邻技能和检查输出的本地文件系统与搜索工具

控制流特征

• 根据新建技能或更新现有技能进行分支
• 根据命令密集型、工作流密集型或参考资料密集型的技能类型进行分支
• 读取和写入本地技能文件
• 必须保留用户修改，避免无关重写

结构流程

入口

1. 确定任务是创建新技能、更新现有技能，还是审核技能。
2. 在确定措辞和结构之前，先阅读附近或类似的 OMA 技能。
3. 确定技能类型：命令密集型、工作流密集型、判断密集型或参考资料密集型。

场景

1. 准备：收集技能目的、触发意图、边界、输入、输出、依赖项以及风险和资源限制。
2. 获取：阅读类似技能、现有资源、项目约定以及用户提供的源材料。
3. 推理：决定哪些内容应内嵌在 SKILL.md 中，哪些应放在 resources/、config/、scripts/ 或 assets/ 中。
4. 执行：使用 SSL-lite 模板创建或更新技能。
5. 验证：进行结构、路由、执行、资源和格式检查。
6. 完成：报告创建或修改的文件、验证结果以及任何剩余假设。

转换

• 如果技能会执行脆弱或重复的命令，请内联包含 ### Canonical command path。
• 如果技能主要涉及人工判断或调查，请内联包含 ### Canonical workflow path。
• 如果详细示例篇幅较长、因变体而异或属于可选内容，请将其移至 resources/，并明确引用。
• 如果技能已存在，请保留有效内容，仅规范化目标格式所必需的部分。
• 如果触发描述过于宽泛，请先缩小范围，再编写技能。

失败与恢复

失败	恢复
技能范围与另一项技能严重重叠	添加明确的 When NOT to use 边界，并交叉引导
执行路径含糊不清	内联添加规范的命令或工作流路径
SKILL.md 过长	将详细示例移至 resources/，并在 References 中保留导航
没有可靠的验证命令	使用结构性 grep/awk 检查和人工清单验证
用户输入不够明确	做出保守假设并列出，除非目标行为存在安全风险

退出

• 成功：技能包含 SSL-lite 的四个顶层部分、规范路径、明确的路由边界、资源约束和验证证据。
• 部分成功：结构有效，但缺少命令、工具、源材料或用户决策，并已报告。
• 失败：未写入技能文件，或已明确说明阻碍性歧义。

逻辑操作

操作

操作	SSL 原语	证据
阅读类似技能	READ	现有的 .agents/skills/*/SKILL.md
选择技能类型	SELECT	命令密集型／工作流密集型／判断密集型／参考资料密集型分类
推断边界	INFER	触发意图和相邻技能的重叠情况
编写技能文件	WRITE	新建或更新的 SKILL.md
添加资源	WRITE	resources/、config/、scripts/ 或 assets/
验证结构	VALIDATE	标题和规范路径检查
报告结果	NOTIFY	变更文件和验证摘要

工具和工具链

• rg、find、awk、sed、git diff --check
• 使用 apply_patch 手动编辑文件
• 将现有 OMA 技能作为示例
• 使用 resources/ssl-lite-template.md 作为规范章节骨架
• 使用 resources/validation-checklist.md 作为验收标准

规范工作流路径

1. 编写前阅读 1-3 个类似的现有技能。
2. 将新技能归类为命令密集型、工作流密集型、判断密集型或参考资料密集型。
3. 根据 resources/ssl-lite-template.md 起草 SKILL.md。
4. 恰好添加一个内联规范路径：
   • 对脆弱或可重复的命令，使用 ### Canonical command path
   • 对决策、审查、设计或研究流程，使用 ### Canonical workflow path
5. 将长篇示例、特定提供方的细节或可选协议移至 resources/。
6. 验证顶层标题、规范路径、前置元数据和空白字符。

资源范围

范围	资源目标
CODEBASE	.agents/skills/*/SKILL.md、相邻资源、项目技能规范
LOCAL_FS	新建的技能目录和资源文件
PROCESS	验证命令以及可选的生成器／检查脚本
MEMORY	用户要求、假设和验证备注

前置条件

• 已知目标技能的名称和用途，或能够安全地推断出来。
• 已检查与相邻技能的重叠情况。
• 如果项目规则原本会保护 .agents/，用户已授权修改 .agents/skills/ 下的内容。

效果和副作用

• 在 .agents/skills/ 下创建或修改文件。
• 可能添加资源文件，以支持渐进式披露。
• 除非明确要求，否则不会暂存或提交更改。

Guardrails

1. 完整保留四个顶级章节：Scheduling、Structural Flow、Logical Operations、References。
2. 保留 YAML frontmatter，并明确填写 name 和 description；路由效果取决于描述的质量。编辑描述后运行 oma skills audit，确认新措辞不会与相邻技能冲突（TF-IDF 余弦相似度 ≥ 60% 时警告，≥ 75% 时失败）。
3. 明确说明具体的「何时不应使用」边界，并提供指向相邻技能的交叉路由。
4. 写明预期输入、预期输出、依赖项和控制流特性。如果产物可通过 glob 匹配，优先使用结构化的 outputs: 块，以便 oma verify 执行闭环检查。
5. 在适当情况下，使用 SSL 场景词汇编写结构化场景：PREPARE、ACQUIRE、REASON、ACT、VERIFY、RECOVER、FINALIZE。
6. 使用 SSL 原语编写逻辑操作，例如 READ、SELECT、VALIDATE、INFER、WRITE、CALL_TOOL、NOTIFY 和 TERMINATE。
7. 写明资源范围和资源目标，包括文件系统、代码库、进程、凭据、网络、用户数据或记忆。
8. 写明效果和副作用，尤其是命令、网络调用、凭据、破坏性操作、生成的文件和长时间运行的进程。
9. 在正文中加入一个规范路径，让 Agent 无需加载所有资源文件即可执行或推理。
10. 将特定变体的详细内容放入 resources/，而非技能正文。
11. 不要在技能目录中创建额外的 README、changelog 或安装文档。
12. 不要覆盖与当前任务无关的用户修改。

References

• SSL-lite 模板：resources/ssl-lite-template.md
• 验证清单：resources/validation-checklist.md
• 共享上下文加载：../_shared/core/context-loading.md
• 共享质量原则：../_shared/core/quality-principles.md
• 技能效用评估：创建新技能时，可考虑在 .agents/eval/<skill>/ 下添加留出任务样例，以便 oma skills eval 衡量该技能是否能改善任务结果。样例格式和检查器类型请参阅 web/docs/guide/skill-eval.md。