skill-builder

Skill Builder

统一且以安全为先的技能构建器。

本技能有意采用明确的主张：

• 如果更简单的改动可行，优先不创建新技能。
• 如果确实要创建技能，就让它保持简单、可测试且不易被误用。
• 保持一个清晰的路由器，避免不同技能的描述相互重叠。
• 除非目标环境明确要求，否则不依赖特定模型或运行框架。

操作路由器

用户意图	操作	输出
创建/构建/制作/新建技能	CREATE	新技能文件夹 + SKILL.md + 仅包含实际需要的配套文件
更新/修改/改进技能	UPDATE	最小差异，保持范围稳定
删除/移除技能	DELETE	移除技能 + 更新所有依赖引用
向技能添加内容/路由/工作流	ADD	新路由条目 + 最少量的配套流程
验证技能	VALIDATE	有证据支持的验证报告 + 修复
重命名技能	RENAME	安全重命名 + 更新引用

操作选择规则

使用能够解决请求的最小操作：

• CREATE — 新的面向用户的能力，或明显不同的意图/描述领域。
• UPDATE — 改进现有技能，但不改变其核心范围。
• ADD — 在当前范围内添加一条新路由、示例或子工作流。
• RENAME — 在基本保留原有行为的同时，更改身份/路径/名称。
• DELETE — 因功能已被取代、合并或不再有用而移除过时能力。
• VALIDATE — 检查正确性，但不扩大范围。

如不确定，默认选择 UPDATE，而不是 CREATE。

“正确”的含义

本技能对“正确”的定义如下：

• 在规范有明确要求时，符合 Agent Skills 规范。
• 采用渐进式披露：SKILL.md 简洁，仅在需要时查阅更深入的文档。
• 激活条件明确：描述具体，且与相邻技能不重叠。
• 安全：不包含机密，不默认执行破坏性命令，并明确需要确认的边界。
• 提供有验证证据的结果，而不是依赖直觉。

阶段 0：第一性原理检查（必须执行）

执行任何 CREATE 或 UPDATE 之前，先完成以下步骤：

1. 询问：要解决什么问题？为谁解决？如何衡量？
2. 删除：现有技能、README 章节、脚本或模板能否解决？
3. 简化：能奏效的最小改动是什么？
4. 加速：仅在完成（2）和（3）之后进行
5. 自动化：只有在新技能会被重复使用时才创建

如果答案是“不需要技能”，请提出以下方案之一：

• 添加一个 README 章节
• 编写一个小脚本
• 提供一段用户可复制的用法示例
• 有针对性地更新现有技能

阶段 1：检测目标并命名

Agent Skills 规范的要求

• 技能目录中包含 SKILL.md。
• SKILL.md 以有效的 YAML frontmatter 开头。
• name 与父目录名称一致。
• description 说明技能的功能及其适用场景。

本技能的建议

• 让 SKILL.md 专注于路由器和核心规则。
• 仅在确有价值时添加 references/、scripts/、assets/ 或 README.md。
• 参考资料与 SKILL.md 保持一层目录深度。
• 将非标准元数据放在 metadata 下，不要自行创建新的顶层字段。

命名

• 使用 kebab-case（my-skill-name）。
• 避免使用通用名称（tools、helper）。
• 优先选择能描述明确工作任务的名称。

描述设计

description 字段是主要的发现入口。

编写时应涵盖：

• 技能做什么
• 何时使用
• 可能的用户表述、领域术语和近义词

不要依赖自定义顶层 triggers 字段，以确保可移植性。如果需要提供触发示例，请将其放在正文、metadata 或评测样例中。

确认边界

无需确认即可执行：

• 只读检查
• 起草内容
• 本地验证
• 提出差异

以下操作前必须先确认：

• 删除文件或文件夹
• 重命名技能文件夹
• 覆盖用户编写的内容
• 以可能改变发现行为的方式更改触发语义
• 编辑仓库索引或目录
• 安装依赖项或执行会产生网络副作用的操作

阶段 2：CREATE 流程

输入（最低要求）

• 名称
• 目标 + 非目标
• 涵盖内容和适用时机的描述草稿
• 如果目标客户端支持，可选的能力约束

CREATE 步骤

1. 探查目标仓库中现有的规范。
2. 起草微型规格说明：目标、非目标、路由、安全边界。
3. 创建 /<skill-name>/SKILL.md，其中包含：
   • frontmatter（name、description、可选的规格支持字段）
   • 路由表
   • 安全与确认规则
   • 简短工作流或指向 references/ 的链接
4. 仅在有充分理由时添加配套文件：
   • 面向用户的安装/概览文档 README.md
   • 用于详细工作流的 references/
   • 用于可执行辅助程序的 scripts/
   • 用于模板/资源的 assets/
5. 使用下方的证据规则进行验证。
6. 如果仓库维护索引，则更新索引。

输出约定（CREATE）

始终返回：

• 创建/编辑的文件
• 添加或更改的描述
• 是否使用了 compatibility、metadata 或 allowed-tools 等可选字段
• 一个最简烟雾测试提示词
• 验证报告：通过/失败 + 证据 + 剩余风险

阶段 3：UPDATE 流程

1. 阅读当前技能。
2. 确定用户的实际目标。
3. 应用能解决问题的最小差异。
4. 重新运行验证。
5. 除非明确要求进行更广泛的更改，否则保持范围和描述稳定。

输出约定（UPDATE）

返回：

• 更改的文件
• 更改的行为
• 描述是否更改：是/否
• 验证报告
• 风险或后续事项

阶段 4：DELETE 流程

1. 确认目标技能文件夹。
2. 查找依赖项：索引、引用、相邻技能。
3. 移除技能并更新引用。
4. 提供回滚说明。

输出约定（DELETE）

返回：

• 移除的路径
• 更新的引用
• 回滚说明
• 对任何剩余失效链接的验证/报告

阶段 5：向技能添加内容

技能扩展规则：

• 同一安装中的多个技能不得重复描述意图。
• 优先按意图进行路由，然后再加载更深入的章节。
• 保持 SKILL.md 易于阅读：使用简短表格和稳定模板，将详细内容放在 references/ 中。

添加步骤：

1. 添加一行新的路由规则，或一个范围明确的章节。
2. 添加最少量的新流程。
3. 如果内容增长，则拆分到 references/<topic>.md。
4. 添加或更新示例。
5. 重新检查相邻技能是否有重叠。

阶段 6：RENAME 流程

1. 确认旧名称和新名称。
2. 重命名文件夹并更新 frontmatter 中的 name。
3. 更新内部及仓库级引用。
4. 验证链接、名称/路径一致性以及发现相关措辞。

输出约定（RENAME）

返回：

• 旧名称 → 新名称
• 移动的路径
• 更新的引用
• 验证报告

验证

验证要求

只有在以下三个层面均提供证据后，技能才算通过验证：

1. 规格验证 — 结构和 YAML 正确性
2. 触发验证 — 描述应在适用时触发，在近似但不适用的情况下不触发
3. 输出验证 — 技能能在真实任务中改进或约束最终工作

技能验证清单

• Frontmatter 包含有效的 name 和 description。
• Frontmatter 是有效的 YAML，而不只是看起来像 Markdown 元数据。
• name 与父目录名称一致。
• 描述清楚说明用途和适用时机。
• 除非目标环境明确支持更多字段，否则额外的 frontmatter 字段应符合规范支持的范围。
• 存在路由器。
• 明确说明确认边界。
• 不包含机密；除非目标仓库有意设为私有，否则不包含私有路径。
• 不包含未限定范围的破坏性指令。
• 遵循渐进式披露原则。
• 已对照相邻技能检查触发条件的规范性。

规范验证（建议）

如果可用：

skills-ref validate ./<skill-name>

如果不可用，请使用 references/validation.md 中的规则手动验证。

能力安全

• 优先使用能够完成任务的最低权限能力。
• 执行命令前先检查或搜索。
• 如需执行命令，应严格限定其范围。
• 切勿将 rm -rf、git reset --hard 或 push --force 作为默认建议。

模板

技能 Frontmatter

---
name: my-skill
description: Use this skill when you need to do X, Y, or Z. It handles A and B and is relevant when the user asks for C.
compatibility: Optional. Mention required runtimes, system tools, or environment assumptions.
metadata:
  version: "0.1"
allowed-tools: Optional experimental field. Only include it when the target client supports it and the skill benefits from a constrained tool list.
---

最小可行的可移植技能

1. Frontmatter
2. 一段用途／激活指南
3. 路由表
4. 安全与确认规则
5. 简短工作流
6. 仅在需要时添加可选的 references/

参考资料

• references/checklist.md（编写清单）
• references/templates.md（可复制粘贴的模板）
• references/validation.md（规范、触发条件和输出验证）

此技能的用途（实际示例）

• “创建一个用于搭建新技能的技能” → CREATE。
• “让此技能更便于在不同 Agent 产品间移植” → UPDATE。
• “重命名此技能，同时不破坏引用” → RENAME。
• “检查此技能能否可靠触发” → VALIDATE。
• “统一不同仓库中的技能” → UPDATE 或 ADD，具体取决于范围。