devetai/better-skill-gen

Better Skill Generator (better-skill-gen)

技能描述：该技能作为一个元技能（Meta-Skill）：接收用户的创意、问题或工作流程，与用户共同确定设计，然后为每个选定的 provider 生成完整的 Skill 目录。

Provider	目录（项目作用域）	特点
Codex 和 Antigravity	.agents/skills/<skill-name>/（一份共享）	仅包含 name、description；Codex 额外有 agents/openai.yaml 用于技能调用策略
Claude Code	.claude/skills/<skill-name>/	带有更多扩展的 frontmatter 字段，详见 references/frontmatter-spec.md

本文件同时用于 Codex 和 Antigravity。文件中的所有 scripts/...、references/... 路径均相对于本 SKILL.md 所在的目录。"运行命令" 指使用当前 provider 的 shell 命令工具（例如 Antigravity 中的 run_command）。

---

1. 核心设计原则

1. 三级渐进式披露架构：
   • 第1级：元数据（启动时始终加载）： YAML Frontmatter 中的 name、description。仅消耗极少量 token；description 须保持在 1,536 字符以下。
   • 第2级：指令（仅在技能被激活时加载）： SKILL.md 文件主体，必须少于 500 行。仅包含工作流、核心原则和约束。
   • 第3级：资源（仅在真正需要时加载）： templates/（输出模板）、examples/（黄金标准示例文本）、references/（技术规格）、scripts/（处理繁重任务的 bash/python 代码，避免占用上下文）。
2. 技能目的分类：
   • 参考技能（Reference Skills）： 编码约定、系统知识、设计模式，供 agent 作为背景知识使用。
   • 任务技能（Task Skills）： 执行操作的逐步流程。有副作用的任务（部署、提交、删除数据）必须仅在用户直接调用时执行。.agents/skills/ 版本需同时做两件事：创建 agents/openai.yaml 并设置 policy.allow_implicit_invocation: false（针对 Codex），以及在 description 中写入"仅当用户直接请求时使用"（针对 Antigravity，因为它没有等效字段）。详见 references/providers.md 第3节。
3. 各 provider 的独有特性： Claude Code 支持子 agent、参数变量和 SKILL.md 中的 shell 命令注入（见 references/frontmatter-spec.md）。仅在 Claude Code 版本中使用这些特性；其他 provider 的版本需根据 references/providers.md 第3节进行转换。
4. 验证，不信任：
   • 生成的每个技能必须附带 scripts/validate.sh，并遵循标准退出码（0 = 通过，1 = 失败）。
   • 100% 遵守 markdownlint 的所有 lint 规则。
5. 零工作区污染：
   • 所有配置文件、资源和脚本仅存放在各 provider 目录下的技能打包文件夹内。
   • 所有示例文档仅存放在技能的 examples/ 目录下。不得将示例文件生成或复制到项目的其他业务目录（如 src/、项目根目录）。
   • 测试过程中产生的临时文件应写入操作系统的临时目录（或用户指导中指定的临时目录），并在完成后立即清理。
6. 以结构化选项形式向用户提问：
   • 所有向用户提供的选择（作用域、provider、想法中不明确之处、设计方向）均以选项形式呈现。如果对话环境中存在多选工具，则使用该工具；否则，列出编号选项，然后暂停并等待用户回答。
   • 呈现顺序：(1) 将要创建的技能做什么；(2) 问题是什么以及为何产生；(3) 各个选项，每个选项用一句话说明利弊；(4) 推荐选项，放在列表首位并标注 （推荐）。
   • 每次最多提问4个问题，重要问题优先。始终允许用户回答不在所列选项中的内容。
   • 在未收到回答前，不得代替用户做选择。
7. 每个 provider 对应一份符合其规范的独立版本：
   • 共享资源（template.md、examples/、references/、scripts/）直接复制。但 SKILL.md（以及 Codex 的 agents/openai.yaml）需独立编写：一份用于 Claude Code，另一份通用用于 Codex 和 Antigravity。
   • Codex/Antigravity 版本必须在两个 provider 上都能正确运行：仅使用开放标准中的 frontmatter 字段，不得使用仅 Claude Code 能理解的变量或工具，也不得将正在运行的 agent 称为 "Claude"。Claude 仅在其作为技能主题时才被提及。

---

2. 所需输入

• 必填： 待创建技能的业务想法或目标描述。
• 可选： 特殊约束、所需工具、任务类型或参考资料。
• 每次创建新技能时必问： 作用域和 provider（第2.1节），以及想法中所有不明确之处（第2.2节）。只有在用户已在请求中明确回答的情况下，才能跳过某个问题。
• 不得自行决定不明确之处： 想法过于简略时，先进行分析并提出建议（第2.2节），不得自行填充内容再生成文件。仅对显而易见的规定（例如从想法推导出的 kebab-case 名称）可以自动设定，但必须在设计摘要中说明。

2.1. 询问作用域（Scope）和 Provider

在生成任何文件之前，按照原则6在同一轮中询问以下2个问题：

1. 作用域（可多选）：根据下表提供三个选项，project-shared 为推荐。
2. Provider（可多选）：Codex、Claude Code、Antigravity。如果技能适用于所有 provider，则推荐全部三个。如果技能仅对一个 provider 有意义（例如仅检查 Claude Code 的配置文件），则仅推荐该 provider 并说明理由。

作用域	含义	目标根目录	运行脚本时的变量
project-shared	当前项目独有，整个团队共享（提交到 git）	项目根目录	SCOPE=project（默认）
project-personal	当前项目独有，仅限该用户（不提交）	项目根目录	SCOPE=project，然后将已创建的目录添加到 .git/info/exclude
user-global	该用户的所有项目	$HOME	SCOPE=user

规则：

• 用户选择多个作用域时，依次部署每个作用域。
• 项目目录不是 git 仓库时，移除 project-personal 选项。
• 在交付报告中记录所选的作用域和 provider，并附上已创建的路径列表。
• 如果技能内容与项目特性相关，而用户选择了 user-global：在创建前显示一行警告。

2.2. 分析想法并提出建议

在确定作用域和 provider 后，在编写任何文件之前分析想法：

1. 总结已理解的内容： 技能解决什么问题、谁使用、何时触发、输出是什么。
2. 确定设计要点，每个要点注明是用户已说明还是 agent 正在推测：
   • 技能类型：任务还是参考；是否有副作用。
   • 激活方式：根据 description 自动激活、仅当用户直接调用时、或两者兼有；触发短语和不应使用的场景。
   • 输入、参数以及缺少时的处理方式。
   • 输出：格式、存储位置、是否需要 template.md 以及 scripts/validate.sh 中的检查标准。
   • 执行方式：仅指导还是需要脚本；需要使用的工具。
   • 抽取到 references/ 的部分，确保 SKILL.md 少于500行。
3. 推荐优化方向： 对于每个仍有多种实现方式的要点，提出2到3种方案并说明利弊，选择一个推荐方案。例如："使用脚本 scripts/check.sh 检查（快速、准确，但需要 bash）" 与 "agent 自行阅读和评估（灵活，但消耗 token 且容易遗漏）"。
4. 向用户提问： 将所有不明确之处和所有存在多种方向的要点按照原则6整理成问题。
5. 锁定设计： 收到回答后，编写设计摘要（技能名称、类型、激活方式、将创建的文件列表、provider、作用域、agent 自动设定的值）。回答引发新的不明确之处时，继续提问，暂不生成文件。

2.3. 研究 provider

在编写某个 provider 的版本之前，阅读 references/providers.md：

• 如果 验证日期 早于30天、技能需要的功能尚未包含在文件中、或文件信息与实际不符：查阅该文件第6节中的官方文档，更新文件，修改验证日期，然后使用 scripts/sync-skill.sh better-skill-gen 将文件复制到其他 provider。
• Antigravity 在项目级共享作用域下使用与 Codex 相同的目录 .agents/skills/（第5节）。不要创建 .agent/skills/。
• 不要猜测 provider 的规格说明。对于无法查到的点，向用户说明并询问。

---

3. 执行流程

flowchart TD
    A["用户业务想法"] --> A2["0. 询问作用域和 Provider"]
    A2 --> B["1. 分析想法、提出建议、询问不明确之处"]
    B --> B2["2. 研究 provider"]
    B2 --> C["3. 参考 template.md 和 references/"]
    C --> D["4. 生成原始版本"]
    D --> E["5. 同步资源并编写各 provider 的 SKILL.md"]
    E --> F["6. 使用 scripts/validate.sh 自行验证"]
    F -->|通过| G["完成并交付"]
    F -->|失败| D

0. 询问作用域和 Provider： 执行第2.1节，等待回答后再继续。
1. 分析想法： 执行第2.2节，直到设计被锁定。技能名称采用 kebab-case（长度≤64字符，禁止包含 anthropic-skills、synced、claude、anthropic）。
2. 研究 provider： 对所有选定的 provider 执行第2.3节。
3. 参考标准文档： 阅读 template.md（结构框架）、references/providers.md（各 provider 差异）、references/frontmatter-spec.md（Claude Code 的字段）和 examples/sample.md（写作风格和脚本逻辑）。
4. 生成原始版本： 在第一个选定 provider 的目录中编写所有组件：
   • SKILL.md：安全的 Frontmatter（使用 quote/scalar block >-），少于500行。
   • template.md（或 templates/）：包含模板变量 ${VARIABLE} 的输出模板。
   • examples/sample.md：不含占位符的真实示例文本。
   • references/（如果存在需要分离的复杂规范/知识文档）。
   • scripts/validate.sh：检查结果完整性的脚本。
   • 共享资源编写时应与 provider 无关：脚本使用相对于技能目录的相对路径调用。
5. 按 provider 部署：
   • 复制共享资源：运行 PROVIDERS="<已选 provider>" bash scripts/sync-skill.sh <skill-name>。该脚本会复制除 SKILL.md 和 agents/ 之外的所有文件，并针对缺少 SKILL.md 的 provider 报告 [TODO]。
   • 对于剩余目录，根据 references/providers.md 第3节的转换表编写独立的 SKILL.md。重写正文内容，而不仅仅是移除 frontmatter 字段。如果同时选择了 Codex 和 Antigravity，则仅有一个 .agents/skills/ 目录，脚本会自动合并。
   • 有副作用的技能：.agents/skills/ 版本额外创建 agents/openai.yaml，设置 policy.allow_implicit_invocation: false，并在 description 中写入"仅当用户直接请求时使用"。
   • 作用域 user-global：在运行脚本时额外设置 SCOPE=user。
   • 作用域 project-personal：将刚创建的技能目录添加到 .git/info/exclude（不修改 .gitignore，不提交）。
6. 自行验证：
   • 运行 PROVIDERS="<已选 provider>" bash scripts/validate.sh <skill-name>（如果是 user-global 则额外添加 SCOPE=user）。
   • 脚本检查：YAML frontmatter 有效性、markdownlint、SKILL.md 行数 ≤500、每个选定 provider 的必选文件是否齐全、以及 Codex/Antigravity 的 SKILL.md 中是否不再包含仅 Claude Code 能识别的字段或标记。
   • 阅读每行 [WARN]：如果提及 Claude 且 Claude 是主题则保留，否则修复。
   • 如有错误，自行修改直到收到 [PASS]。

---

4. 约束与标准

• 强制规则：
  • 所有选择必须按照原则6提问，并在继续前等待回答。
  • 在创建新技能前必须始终询问作用域和 provider（第2.1节）。
  • 不得自行决定不明确之处： 在生成文件前进行分析、提出建议并提问（第2.2节）。
  • 在编写某个 provider 的版本前必须研究该 provider（第2.3节）；不得猜测规格说明。
  • 不得在不同 provider 之间直接复制 SKILL.md： 每个 provider 一份独立的符合其规范的版本；validate.sh 必须对所有选定的 provider 返回 [PASS]。
  • 零工作区污染： 示例文档仅存放在 examples/ 中；不得在技能打包目录之外创建文件。
  • 保持 SKILL.md 少于500行： 将详细内容移至 references/ 或 templates/。
  • Frontmatter 规范化： description 中包含冒号 : 时，必须使用 scalar 块 >- 或双引号 "..."。
  • 遵守 Markdownlint（MD001 - MD047），针对所有生成的 Markdown 文件。
• 应做事项：
  • 对于所有有副作用的技能，按照各 provider 的正确方式声明"仅当用户调用时执行"机制（Codex：agents/openai.yaml；Antigravity：description 中的语句）。
  • 在模板中使用具有较高描述性的模板变量 ${TEN_BIEN}。
  • 立即清理在自动测试过程中生成的临时文件。
• 禁止事项：
  • 不得将冗长的参考资料直接塞入 SKILL.md。
  • 不得在 markdown 文件中放置裸 URL 而不加 <> 或 markdown 链接。
  • 不得使用超过64个字符或包含大写字母/特殊字符的技能名称。
  • 在非 Claude Code 的 provider 版本中，不得将 agent 称为 "Claude"。