第24章 Zed Agent Skills：构建可复用的智能体指令包指南

Skill（技能）是一种可复用的指令包，为 Agent 在处理特定任务时提供专业知识，例如测试驱动开发工作流、文档处理、数据库集成，或是团队内部的编码规范。

一个 Skill 是一个包含 SKILL.md 文件的文件夹，该文件存储元数据和指令。Agent 会看到所有已安装 Skill 的目录，并能在需要时加载其中任意一个；或者，你也可以通过斜杠命令直接从消息编辑器中调用任何 Skill。

添加 Skills {#adding-skills}

创建自定义 Skill {#create-your-own}

Zed 内置了一个 create-skill Skill——输入 /create-skill 调用后，Agent 会引导你完成创建流程。

你也可以使用 {#kb agent::ManageSkills} 从 Agent 面板打开 Skills 管理器，或者点击 ... 并选择 Skill。在面板外部，可以通过命令面板使用 {#action agent::OpenSkillCreator} 操作，或在 AI > Skill 设置页面点击 创建 Skill。创建器会在设置窗口中打开一个页面，你可以填写 Skill 的名称、描述、正文，并可选择切换 disable-model-invocation。Skill 会被保存到设置窗口中选择的设置文件作用域——用户标签页创建全局 Skill，而项目标签页创建项目本地 Skill——表单会准确显示文件将写入的位置。

最后，你还可以通过从现有的 GitHub Markdown 文件导入来添加 Skill。打开命令面板，查找 {#action agent::CreateSkillFromUrl} 操作。如果你的剪贴板中包含受支持的 GitHub .md 链接，Zed 会自动预填并获取内容。

完整的格式参考请参阅下文 Skill 格式。

来自 skills.sh 注册表 {#from-the-registry}

skills.sh 是一个开源 Skill 的社区注册表。你可以在这里找到适用于流行框架、工具、工作流等的 Skill：

• find-skills：从开放生态中发现并安装 Skill
• frontend-design：具备设计润色的高质量前端界面
• pdf：支持 PDF 文本提取、合并、拆分、表单填充及 OCR

要安装技能，请将技能文件夹复制到 ~/.agents/skills/ 以实现全局使用，或复制到项目下的 .agents/skills/ 目录以实现项目内使用。

管理技能 {#managing-skills}

打开设置编辑器（macOS 按 Cmd+,，Linux/Windows 按 Ctrl+,），导航至 AI > Skills，或直接访问 agent.skills。

User 标签页显示全局技能，每个 Project 标签页显示对应项目的技能。

对于每个技能，你可以：

• Copy Share Link — 复制一个内嵌该技能的 zed://skill 链接，方便发送给他人（参见 共享技能）
• Open — 在编辑器中打开该技能的 SKILL.md 文件
• Delete — 从磁盘删除该技能文件夹

在技能页面中，你会看到一个 Create Skill 按钮，点击后打开设置窗口，允许通过 UI 直接创建技能。

共享技能 {#sharing-skills}

你可以直接将技能传递给同事，无需托管在任何地方。在 Skills 设置页面中，点击某条技能记录上的 link 图标，即可将 zed://skill?data=… 链接复制到剪贴板。 该链接是独立的：它内嵌了完整的 SKILL.md 内容（采用 base64url 编码），因此接收方无需访问你的项目或任何注册中心。

当某人打开该链接（例如粘贴到浏览器中或在聊天中点击）时，Zed 会在设置窗口中打开“Create Skill”页面，并预先填充共享的技能内容。 接收方可以审查名称、描述及完整正文，选择作用域（选中 User 标签页表示全局，或选中某个 Project 标签页），然后点击 Save 进行安装。 直到明确保存之前，不会有任何内容写入磁盘，因此共享链接永远不会在幕后向他人的 Agent 静默安装指令。

使用技能 {#using-skills}

默认情况下，Agent 会自主调用 skills。系统提示中会包含所有已安装 skill 的目录（名称和描述），当任务与某个 skill 的描述匹配时，Agent 就会调用 skill 工具。

当 Agent 调用你创建或安装的 skill 时，Zed 会弹出提示让你允许或拒绝，权限流程与其他工具一致。Zed 内置的 skills 则不会弹出提示。你可以在 Tool Permissions 中为每个 skill 设置默认权限，这样常用的可信 skill 就不会再被打断询问。

手动调用 {#manual-invocation}

你也可以手动加载 skill：

• 斜杠命令：在消息编辑器中输入 /，按名称选择 skill
• @-提及：在消息编辑器中输入 @skill，从补全菜单中选择 skill

两种方式都会把 skill 的指令注入为上下文。已加载的 skill 会以折角按钮的形式显示在线程中，点击即可打开对应的 skill 文件。

禁止自主调用 {#disable-model-invocation}

在 skill 的 frontmatter 中添加 disable-model-invocation: true，即可阻止 Agent 自主调用该 skill。 它仍会以斜杠命令的形式存在，何时运行完全由你掌控。

这适用于你不希望 Agent 自动触发的流程，比如部署或发布操作。

---
name: deploy
description: Deploy the current branch to production.
disable-model-invocation: true
---

Skill 格式 {#skill-format}

目录结构 {#folder-structure}

一个 skill 就是一个包含 SKILL.md 文件的命名目录：

my-skill/
├── SKILL.md          # 必需：元数据和指令
├── scripts/          # 可选：Agent 可运行的脚本
├── references/       # 可选：补充文档
└── assets/           # 可选：模板和静态文件

按照惯例，目录名应与 SKILL.md 中的 name 字段一致。

SKILL.md 格式 {#skill-md-format}

SKILL.md 以 YAML frontmatter 开头，后接 Markdown 格式的指令。

最简示例：

---
name: my-skill
description: 该 Skill 的功能及使用场景。
---

## Instructions

给 Agent 的分步操作说明...

Frontmatter 字段 {#frontmatter-fields}

提示： 编写有助于 Agent 识别 Skill 适用场景的描述。请明确具体的任务类型和触发短语。例如，写“在处理 PDF、提取文本或填写表单时使用”比笼统的“有助于处理 PDF”效果更佳。

我们计划在近期纳入 Agent Skills 规范中推荐的其他字段。

名称校验 {#name-validation}

name 字段必须满足以下要求：

• 仅包含小写字母（a-z）、数字和连字符
• 首尾不能有连字符
• 不能包含连续的连字符（--）
• 长度需在 1 到 64 个字符之间

名称不符合规范的 Skill 将无法加载，并在界面中报错。

捆绑资源 {#bundled-resources}

请将 SKILL.md 正文内容控制在 500 行以内。把详细资料移至参考文件，并在正文中通过链接指向它们：

完整的 API 详情请参阅 [参考指南](references/REFERENCE.md)。

运行提取脚本：
scripts/extract.py

Agent 会在需要时通过 read_file 和 list_directory 工具按需加载这些文件。位于 ~/.agents/skills/ 下的全局 Skill 即使不在当前项目目录内，Agent 依然可以访问。

编写有效的操作说明 {#writing-instructions}

Skill 采用 渐进式披露机制：在激活前，Agent 仅可见 Skill 的名称和描述；激活后才会加载完整内容。请据此组织你的 Skill 结构：

• 将最关键的指令置于正文顶部
• 控制 SKILL.md 在 500 行以内；详细参考资料移至 references/ 目录
• Agent 需执行的脚本放入 scripts/ 目录

完整的格式规范请参阅 Agent Skills 规范。

Skill 存放位置 {#where-skills-live}

Zed 从以下两个位置加载 Skill：

每个 Skill 必须直接位于 Skill 根目录下，不支持在子文件夹中嵌套。

项目本地 Skill 与信任机制 {#project-local-trust}

项目本地 Skill 仅从受信任的 worktree加载。新克隆或未受信任项目的 Skill 将被排除在目录和斜杠命令之外，直到你授予信任权限。

此机制可防止恶意项目在你审查其内容之前，向 Agent 的系统提示注入指令。

覆盖行为 {#override-behavior}

当全局 Skill 与项目本地 Skill 同名时，项目本地 Skill 优先。这允许项目根据自身场景自定义或替换全局 Skill。

编辑 Skill 文件 {#editing-skill-files}

即使是在受信任的项目中，Agent 未经明确授权也无法编辑 SKILL.md 文件及其捆绑资源。这防止了被污染的对话修改管理未来对话的 Skill。

Agent 路径边界 {#agent-path-boundaries}

Zed Skills 仅适用于 Zed Agent。外部 Agent 和终端线程可能拥有自身的原生 Skill、提示或指令系统，请通过外部 Agent 或 CLI 进行配置。

局限性 {#limitations}

• 仅支持扁平结构。Skill 必须直接放在 skills 根目录下，像 ~/.agents/skills/group/my-skill/ 这样的嵌套目录不会被识别。
• 目录预算 50KB。所有 skill 名称和描述的总大小上限为 50KB。超出预算的 skill 会被从目录中移除，并在 UI 中给出警告。请保持描述简洁。
• 不支持远程仓库。Zed 不会在运行时从远程位置发现或加载 skill，也不支持自定义搜索路径。（不过你可以从 GitHub URL 一次性导入一个 skill —— 参见创建自己的 skill。）Skill 只会从 ~/.agents/skills/ 和 <worktree>/.agents/skills/ 加载。如果需要指向其他位置，请使用符号链接。
• 热加载。新增、删除或编辑 SKILL.md 会立即生效，无需重启会话。但修改 skill 的 name 或 description 会使当前会话的模型 prompt 缓存失效。

另请参阅

• Agent Panel
• Tool Permissions
• Agent Skills 规范