skill-creator

Builder.io Fusion 技能创建器

创建和改进技能，扩展 Builder.io Fusion 在项目中的能力。

你将要做什么

通过以下工作流之一帮助用户：

1. 创建新技能——了解意图、搭建目录结构、编写 SKILL.md
2. 改进现有技能——阅读技能、诊断问题、重写
3. 选择合适的工具——帮助判断应使用技能、AGENTS.md 还是 .builderrules

创建新技能

第 1 步：了解意图

提出以下问题，了解用户的需求。根据用户的技术水平调整措辞——如果用户不熟悉技术，跳过术语并替他们做决定。

1. 这个技能应该做什么？ 它应该提供什么任务能力或知识？
2. 什么时候应该触发？ 用户说什么或提出什么问题时，应激活这个技能？
3. 输出是什么？ 文件、代码、报告还是工作流步骤？
4. 是否需要针对用户的设置？（例如，API 密钥、频道名称、团队偏好）→ 使用 config.json 模式

第 2 步：选择合适的工具

创建技能前，先确认它是否是合适的选择：

需求	使用方式	原因
任何可复用的 AI 指令或工作流	技能（.builder/skills/<name>/SKILL.md）	仅在需要时加载，保持上下文精简。支持捆绑文件、脚本和渐进式披露。
背景知识和配套文件	技能	指令旁可附带参考文档和脚本，按需加载
AI 始终需要遵循的指令	AGENTS.md	像系统提示词一样加载到上下文中。适用于重要的项目级约定。
针对特定目录的简单规则	.builderrules 或 .builder/rules/*.mdc	轻量级规则，可限定在特定目录中
可由代码检查工具强制执行的样式规则	代码检查工具配置（ESLint、Prettier 等）	不要让机械检查占用 AI 上下文

技能是推荐的默认选择。 与始终加载到 AI 上下文中的 AGENTS.md 不同，技能仅在相关时加载。这意味着你可以拥有许多技能，而不会撑大上下文窗口。AGENTS.md 应仅用于少量 AI 在每次对话中都真正需要的指令。

第 3 步：搭建技能结构

在 .builder/skills/<name>/SKILL.md 创建技能目录：

project/
└── .builder/
    └── skills/
        └── <skill-name>/
            └── SKILL.md

写入任何文件之前：

• 如果 .builder/ 或 .builder/skills/ 不存在，请创建这些目录
• 如果目标路径下已存在技能，请先阅读，然后询问用户：更新现有技能，还是选择其他名称？

命名规则：

• 只能使用小写字母、数字和连字符（例如，pdf-processor、deploy-staging）
• 不得使用连续连字符，也不得以连字符开头或结尾
• 最多 64 个字符
• 目录名称即技能标识符
• 嵌套路径使用目录：.builder/skills/office/word/SKILL.md，而不是 office-word
• 避免使用与 Builder.io 目录冲突的名称：rules、config、settings

第 4 步：编写 SKILL.md

每个 SKILL.md 都包含两部分：YAML frontmatter 和 Markdown 正文。

Frontmatter

至少包含 name 和 description：

---
name: my-skill
description: >
  What the skill does AND when to use it. Include trigger
  keywords and phrases. This is what the AI reads to decide
  whether to load the skill.
---

完整字段说明请参阅 references/frontmatter-reference.md。

编写描述（关键）

描述是技能中最重要的一行。它决定 AI 是否会在恰当的时机加载你的技能。写错了，技能就永远不会触发；写对了，它就能可靠地激活。

使用“做什么 + 何时使用”的模式。 每条描述都需要包含：

• 技能做什么
• 何时使用（具体的触发场景）

不佳示例：

description: Helps with documents
# Too vague — the AI has no activation signal

description: Extract text from PDF files
# Only says WHAT, not WHEN — the AI must guess when to trigger

description: Use when the user says "create a PDF"
# Too narrow — misses related phrasings

良好示例：

description: >
  Extract text and tables from PDF files, fill forms, merge
  documents. Use when working with PDF files or when the user
  mentions PDFs, forms, document extraction, or .pdf files.

description: >
  Generate commit messages by analyzing git diffs. Use when the
  user asks for help writing commit messages, reviewing staged
  changes, or preparing code for commit, even if they don't
  explicitly ask for a "commit message."

确保可靠触发的提示：

• 使用第三人称（“处理文件”，而不是“我帮你处理文件”）
• 包含文件扩展名、领域术语和非正式同义词
• 加入“即使用户没有明确要求执行 X”
• 控制在 1024 个字符以内
• 描述是写给 AI 模型的，不是写给人的——把它当作触发条件定义
• AI Agent 往往会触发不足，因此应尽量具体地说明何时激活

编写正文

Markdown 正文是技能的指令。控制在 500 行以内，并清晰地组织结构：

# Skill Title

## Quick Start
Immediate, actionable guidance.

## Instructions
Step-by-step procedures.

## Gotchas
Common failure points and how to avoid them.

## Examples
Concrete input/output pairs.

编写原则：

• 不要陈述显而易见的内容。 AI 已经知道如何编码。重点说明那些会让它偏离默认行为的内容——项目的特殊之处、约定和注意事项。
• 建立一个注意事项部分。 这是任何技能中最有价值的内容。发现失败点时就记录下来，并随着时间不断更新。一个好的注意事项部分胜过数页指令。
• 避免限制过死。 技能会在许多场景中重复使用。应提供信息和灵活性，而不是僵化的分步脚本。让 AI 自行调整。
• 解释原因，而不只是说明做法。 “使用 UTC 时间戳，因为聚合管道假设时间为 UTC”胜过“始终使用 UTC 时间戳”。
• 从小处开始，逐步迭代。 大多数成功的技能最初只有几行内容和一个注意事项。随着 AI 遇到边缘情况，它们逐渐完善。不要试图第一次就写出完美的技能。

步骤 5：添加辅助文件（如有需要）

技能是一个文件夹，而不只是一份 Markdown 文件。使用文件系统逐步披露信息：

my-skill/
├── SKILL.md              # Required — main instructions (<500 lines)
├── references/            # Detailed docs, loaded on demand
│   └── api-docs.md
├── scripts/               # Executable helpers
│   └── validate.sh
└── assets/                # Templates, static files
    └── template.html

逐步披露分为三个层级：

层级	加载内容	时机	大小
元数据	name + description	始终在上下文中	~100 个令牌
指令	完整的 SKILL.md 正文	技能触发时	<500 行
资源	参考文件、脚本	AI 需要时	不限

规则：

• SKILL.md 控制在 500 行以内。如果接近 400 行，将详细内容拆分到参考文件中。
• 在 SKILL.md 中添加参考链接：“有关 API 详情，请参阅 references/api-docs.md。”
• 参考文件只嵌套一层。不要让参考文件再指向其他参考文件——AI 可能只会部分读取深层嵌套内容。
• 如果技能会以固定格式生成文件，请将模板放入 assets/。
• 将可复用脚本放入 scripts/，让 AI 组合使用，而不是重新构建样板代码。

步骤 6：高级模式

用户专属设置的 Config.json

如果技能需要因用户而异的上下文（API 密钥、频道名称、团队设置）：

my-skill/
├── SKILL.md
└── config.json

在 SKILL.md 中说明：“如果此技能目录中不存在 config.json，请向用户询问[所需设置]，并在继续之前将其保存到 config.json。”

记忆与数据存储

技能可以维护状态：

• 只追加的日志文件（例如，站会技能使用的 standups.log）
• JSON 数据文件
• 甚至 SQLite 数据库

这样 AI 就可以在不同会话中参考自己的历史记录。

组合技能

在指令中按名称引用其他技能。如果已安装这些技能，AI 就会调用它们。例如：“验证后，使用 /deploy 技能推送更改。”

步骤 7：测试技能

创建技能后：

1. 启动新会话。 技能会在会话开始时加载，因此请启动一个全新会话以加载新技能。
2. 尝试有实质内容的提示词。 使用符合技能描述的多步骤或专业提示词进行测试——提示词越具体，技能越容易触发。
3. 尝试 2-3 种不同说法。 用不同方式表达用户可能提出的需求。
4. 检查易出错之处。 刻意尝试 AI 之前失败过的场景。

如果技能没有触发，问题可能出在描述上。重新检查“做什么 + 何时”的模式，并添加更多触发词。

改进现有技能

当用户想要改进某项技能时：

1. 阅读当前的 SKILL.md——了解其目的和结构
2. 诊断问题：
   • 没有触发？→ 改进描述中的“做什么 + 何时”
   • 在不合适的时机触发？→ 描述范围太广，应缩小“何时”的范围
   • 输出质量差？→ 在指令中补充易出错之处或约束
   • 速度太慢或消耗上下文过多？→ 拆分内容，采用渐进式披露
3. 保留名称和目录——除非用户要求，否则不要重命名
4. 展示更改——写入之前，解释你改了什么以及原因

审核清单

使用此清单检查技能质量：

• Frontmatter： 有效的 YAML，包含 name 和 description
• 描述： 使用“做什么 + 何时”模式，少于 1024 个字符
• 描述： 包含具体的触发词和使用场景
• 命名： 目录名使用小写字母和连字符，且与 name 字段一致
• 大小： SKILL.md 少于 500 行
• 易出错之处： 包含 Gotchas 部分（或注明应随时间逐步完善）
• 渐进式披露： 参考文件与 SKILL.md 的目录层级相差一级
• 没有显而易见的知识： 不解释 AI 已经知道的内容
• 灵活性： 指令为 AI 留出调整空间，而不是规定僵化的脚本
• 路径： 位于 .builder/skills/<name>/SKILL.md

应避免的反模式

• 描述含糊——“帮助编写代码”没有告诉 AI 何时触发
• 参考资料嵌套过深——SKILL.md → A.md → B.md 的结构会出问题；参考资料最多嵌套一级
• 过度解释显而易见的内容——不要教 AI 什么是 REST API。重点说明你自己的具体要求。
• 流程僵化——过于严格的分步脚本在情况变化时会失效。提供上下文，让 AI 灵活应对。
• 选项太多且没有默认值——“使用库 X、Y 或 Z”会迫使 AI 随意选择。选定一个，并注明替代方案。
• 正文中使用 XML 标签——使用标准 Markdown 标题，不要使用 <section> 标签
• 本应由代码检查工具处理的风格规则——分号、空格、导入顺序 → 放入 ESLint/Prettier 配置，而不是技能

参考文件

详细的字段文档请参阅 references/frontmatter-reference.md。

不同复杂程度的完整技能示例请参阅 references/examples.md。