skill-creator

技能编写流程

按照以下步骤生成符合 agentskills.io 规范和渐进式披露原则的技能。

步骤 1：初始化并验证元数据

1. 定义唯一的 name：长度为 1–64 个字符，仅包含小写字母、数字和单个连字符。此名称必须与父目录名称完全一致（例如，名称为 angular-testing 的技能必须位于 angular-testing/SKILL.md）。
2. 起草 description：最多 1,024 个字符，使用第三人称撰写。包含正向触发条件（“Use when...”）和负向触发条件（“Don't use for...”）。
3. **执行验证脚本：**继续之前，运行验证脚本以确保符合要求： python3 scripts/validate-metadata.py --name "[name]" --description "[description]"
4. 如果脚本返回错误，根据 stderr 输出自行修正元数据，然后重新运行，直到验证通过。

步骤 2：构建目录结构

1. 使用经过验证的 name 创建根目录。
2. 初始化以下子目录：
   • scripts/：用于存放小型 CLI 工具和确定性逻辑。
   • references/：用于存放扁平（仅一层深）的上下文文件，例如架构或 API 文档。
   • assets/：用于存放输出模板、JSON 架构或静态文件。
3. 确保不创建面向人的文件（例如 README.md、CHANGELOG.md、INSTALLATION.md）。

步骤 3：起草核心逻辑（SKILL.md）

1. 使用 assets/SKILL.template.md 中的模板作为起点。
2. 所有指令均使用第三人称祈使句撰写（例如，“提取文本”“运行构建”）。
3. 采用具体的流程化格式：
   • **使用逐步编号：**将工作流定义为严格的时间顺序。清晰列出决策分支（例如，“步骤 2：如果需要源映射，则运行 scripts/build.sh。否则，跳至步骤 3。”）。
   • **提供具体模板：**如果输出有特定结构，请将模板放在 assets/ 中，并指示 Agent 复制其结构，而不是用文字描述。
   • **使用一致、具体的术语：**在全文中使用相同的领域术语（例如，在 Angular 中始终使用“template”，而不是混用“html”或“view”）。
4. 落实渐进式披露：
   • 将主 SKILL.md 控制在 500 行以内。
   • 如果某个流程需要大型架构、复杂规则集或大量上下文，则将其移至 references/ 中的扁平文件。
   • 指示 Agent 仅在需要时读取特定文件（JiT 加载）：“读取 references/api-spec.md 以确定正确的端点。”

步骤 4：识别并打包脚本

1. 识别“脆弱”的任务（正则表达式、复杂解析或重复样板代码）。
2. 为 scripts/ 目录规划一个单一用途的脚本，将其设计为带参数的小型 CLI。
3. 确保脚本使用标准输出（stdout/stderr）传达成功或失败。编写清晰易懂的错误消息，使 Agent 无需用户介入即可准确地自行修正。

步骤 5：组合技能（可选）

如果技能较复杂，可使用路由器/子技能模式进行组合：

1. 创建一个高级路由器技能。
2. 定义有条件的触发条件或流程，引用其他特定技能文件夹（例如，“要构建客户端，请参阅 [客户端构建技能的路径]。要构建服务端，请参阅 [服务端构建技能的路径]。”）。

步骤 6：验证最终逻辑

1. 检查 SKILL.md 是否存在“幻觉缺口”（即 Agent 被迫猜测的地方）。
2. 确认所有文件路径均为相对路径，并使用正斜杠（/）。
3. 对照 references/checklist.md 检查最终输出。

错误处理

• **元数据验证失败：**如果 scripts/validate-metadata.py 验证失败，找出具体错误（例如，“STYLE ERROR”），并重写字段以去除第一人称或第二人称代词。
• **上下文膨胀：**如果草稿超过 500 行，则提取最大的流程块，并将其移至 references/ 中的文件。