skill-best-practices

技能编写流程

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

捆绑路径规则

相对于包含此 SKILL.md 的目录解析捆绑路径。从其他工作目录调用辅助工具时，先将 <skill-best-practices-dir> 展开为该目录，以确保命令明确无歧义。

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

1. 定义唯一的 name：长度为 1–64 个字符，只能包含小写字母、数字和单个连字符。
2. 起草 description：最多 1,024 个字符，使用第三人称撰写，并包含否定触发条件。
3. 执行验证脚本（只读辅助工具）： 运行验证脚本，确保符合要求后再继续： python3 <skill-best-practices-dir>/scripts/validate-metadata.py --name "[name]" --description "[description]"
4. 如果脚本返回错误，根据 stderr 输出自行修正元数据并重新运行，直到验证成功。

步骤 2：构建目录结构

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

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

1. 使用 assets/SKILL.template.md 中的模板作为起点。
2. 所有说明均使用第三人称祈使句（例如，“提取文本”“运行构建”）。
3. 遵循渐进式披露原则：
   • 将主要逻辑控制在 500 行以内。
   • 如果某个流程需要大型架构或复杂规则集，将其移至 references/。
   • 仅在需要时命令 Agent 读取特定文件：“读取 references/api-spec.md，以确定正确的端点。”

步骤 4：识别并捆绑脚本

1. 识别“脆弱”的任务（正则表达式、复杂解析或重复的样板代码）。
2. 为 scripts/ 目录规划一个用途单一的脚本。
3. 确保脚本使用标准输出（stdout/stderr）向 Agent 报告成功或失败。
4. 在 SKILL.md 中，以从 Agent 工作目录可明确解析的路径引用捆绑辅助工具（即 Agent 将用于调用它们的同一路径），而非使用会隐式依赖 CWD 的 scripts/helper.py 片段。
5. 将每个辅助工具标记为只读、引导初始化或会修改状态，以便下游 Agent 了解该工具是只检查状态还是会对其进行更改。

步骤 5：最终逻辑验证

1. 检查 SKILL.md 中是否存在“幻觉缺口”（迫使 Agent 猜测的地方）。
2. 确认所有文件路径均为相对路径，并使用正斜杠（/）。
3. 确认每个引用的辅助工具路径从 Agent 工作目录来看都明确无歧义，且已注明辅助工具的作用（只读、引导初始化或会修改状态）。
4. 阅读 references/checklist.md，并逐项对照最终输出检查清单内容。

错误处理

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