skill-builder

Agent Skill 构建器

目标

把一个想法或已有 Skill 直接推进到结构合规、指令清晰、资源克制、脚本可靠、评测可复现的完整能力包。除非关键信息确实无法推断，不要停在建议或模板阶段。

核心原则

• 先读现状：修改已有 Skill 时，先完整读取 SKILL.md、已引用资源、脚本、测试和仓库约定。
• 只问阻塞问题：能从上下文合理推断的内容直接处理；必须提问时每轮不超过 3 个。
• 渐进披露：主文件保留触发、决策、流程和质量门槛，长知识放 references，确定性操作放 scripts。
• 验证比例随风险增长：至少覆盖正常输入、缺失输入和边界输入；共享脚本需要单元测试。
• 描述决定发现：description 同时写清任务、典型触发、边界和交付结果，不塞入完整工作流。
• 自动推进：用户已经授权实施时，各阶段通过后直接进入下一阶段，不重复索要确认。

工作流程

1. 建立任务契约

从用户输入和现有文件中提取：

• 用户要反复完成的具体任务。
• 典型触发话术与相邻但不应触发的请求。
• 必需输入、可选输入和合理默认值。
• 最终交付物、保存位置和完成信号。
• 依赖的工具、网络、凭据、运行时或应用。
• 至少 3 条可判定的质量标准和主要失败模式。

只有触发边界、交付格式或高风险行为仍不明确时才提问。用户给出完整规格时直接进入设计；用户只给一句模糊想法时，优先询问“最终交付什么”“谁会在什么场景触发”“什么算成功”。

产出一份内部任务契约。只有存在会改变实现方向的互斥选择时才展示给用户确认，不把确认仪式当成固定门槛。

2. 设计最小能力包

先区分目标：可移植的 Agent Skills 包只要求根目录有 SKILL.md；下面是需要适配 Codex 展示并满足本仓库发布门禁时采用的 Sanqi 完整结构，不是开放标准的强制目录：

skill-name/
├── SKILL.md
├── agents/
│   └── openai.yaml # 仅在目标客户端需要时
├── scripts/       # 仅在确定性操作能提高可靠性时添加
├── references/    # 仅放按需读取的领域知识或长规范
├── assets/        # 仅放最终输出会直接使用的模板或素材
└── evals/       # 本仓库的发布约定
    ├── evals.json
    └── trigger-evals.json

不要为了目录完整而创建空目录。脚本、引用和资产必须在主文件中说明何时使用；每个引用从 SKILL.md 直接链接，避免多层引用链。

选择适合的工作流模式时读取 references/design-patterns.md。

3. 编写标准元数据

顶层使用 Agent Skills 支持的字段。最小可移植包需要 name 和 description；license、compatibility、metadata 属于可选字段。本仓库另外要求 MIT 和统一的展示元数据，不能把这些仓库约定称为开放标准的强制要求：

---
name: skill-name
description: >
  [做什么；用户何时会需要；典型话术；相邻边界；最终交付什么。]
license: MIT
compatibility: [运行时、工具、网络或应用要求。]
metadata:
  author: "author-name"
  version: "1.0.0"
---

要求：

• name 与目录名完全一致，只含小写字母、数字和单连字符，长度不超过 64。
• description 非空且不超过 1024 字符，使用具体名词和用户话术，不依赖只有作者懂的简称。
• 自定义展示信息放进 metadata，所有值使用字符串。
• 仅在 Skill 确实需要时声明 allowed-tools；不要用它掩盖未说明的依赖。

目标是 Codex 等使用该文件的客户端，或发布到本仓库时，补充 agents/openai.yaml。本仓库要求其中字符串加引号，default_prompt 明确提到 $skill-name；其他客户端可能忽略此文件。

4. 编写可执行指令

正文使用祈使语气，包含：

1. 一句话目标。
2. 开始条件和输入缺失策略。
3. 有顺序、分支和产出物的工作流。
4. 错误、降级、重试和停止条件。
5. 可用“通过/不通过”判断的质量标准。
6. 最终交付内容、文件路径和已知局限。