Skills:可复用的 prompt 包

文档摘要

Skills:可复用的 prompt 包本节摘要:MCP 扩展「能力」,Skills 扩展「知识」。一个 Skill 是一个 SKILL.md 格式的可复用 prompt 包——它告诉 Agent 「在某种场景下,应该怎么做」。比如「代码审查 Skill」封装了一套审查流程,「Git 提交 Skill」封装了提交规范。Skills 不是可执行代码,而是注入到对话里的提示;触发后,它的内容被包成信封注入,引导 Agent 按某种方法论工作。本节会讲清 SKILL.md 的格式、Skills 的发现与 scope 优先级、信封注入机制、以及触发方式。理解 Skills,你就掌握了把「最佳实践」沉淀成 Agent 能力的方法。

Skills:可复用的 prompt 包

本节摘要:MCP 扩展「能力」,Skills 扩展「知识」。一个 Skill 是一个 SKILL.md 格式的可复用 prompt 包——它告诉 Agent 「在某种场景下,应该怎么做」。比如「代码审查 Skill」封装了一套审查流程,「Git 提交 Skill」封装了提交规范。Skills 不是可执行代码,而是注入到对话里的提示;触发后,它的内容被包成信封注入,引导 Agent 按某种方法论工作。本节会讲清 SKILL.md 的格式、Skills 的发现与 scope 优先级、信封注入机制、以及触发方式。理解 Skills,你就掌握了把「最佳实践」沉淀成 Agent 能力的方法。

一、Skills 扩展的是什么

回顾第 5 章,工具系统扩展的是「能力」——让 Agent 能做新的事(读文件、跑命令、查 API)。Skills 扩展的是另一种维度:「知识与方法论」——让 Agent 知道在某种场景下应该怎么做。

举几个例子说明区别:

工具(能力)扩展:让 Agent 能「跑 npm test」(给它一个新动作)
Skill(知识)扩展:让 Agent 知道「跑测试前先检查 package.json 的测试脚本是什么」(给它一套方法论)

工具是「手」,Skill 是「脑里的经验」。一个有丰富工具但没 Skill 的 Agent,像是个力气很大但没经验的新人——什么都能做,但不知道什么时候做什么。Skill 把「老手的经验」封装进去,让 Agent 在特定场景下表现得像个内行。

Skills 与系统提示的关系

系统提示(system prompt)也注入知识,但它是「全局的、固定的」——所有对话都用同一套。Skills 是「按需的、可发现的」——只在相关场景被激活,不相关时不占上下文。这种「按需注入」让 Agent 既能拥有大量 Skill,又不会被无关 Skill 撑爆上下文。

二、SKILL.md 的格式

一个 Skill 是一个 SKILL.md 文件,格式是「YAML frontmatter + Markdown 正文」:


---
name: code-review
description: 审查代码改动,关注 bug、可读性、安全性
when-to-use: 当用户要求审查代码,或提交 PR 前
allowed-tools:
  - GrokBuild:read_file
  - GrokBuild:bash
  - GrokBuild:grep
argument-hint: <可选的改动描述或文件范围>
user-invocable: true
disable-model-invocation: false
effort: medium
---

# 代码审查 Skill

## 审查流程

1. 先用 git diff 看全部改动
2. 对每个改动的文件,读取完整上下文(不只是 diff)
3. 按以下维度审查:
   - 正确性:逻辑是否正确?边界条件?
   - 可读性:命名、结构、注释
   - 安全性:输入校验、权限、敏感信息
4. 给出结构化的审查意见

## 输出格式

按严重程度分级:
- 阻塞:必须修改才能合并
- 建议:建议修改
- 讨论:可讨论的点

frontmatter 字段:

name:Skill 的唯一标识(kebab-case)
description:何时触发的自然语言描述——模型据此判断要不要用
when-to-use:与 description 互补,更详细的触发提示
allowed-tools:这个 Skill 内允许用的工具白名单(限制 Skill 的能力范围)
argument-hint:给模型的参数提示
user-invocable:用户能否用 /skill 显式调用
disable-model-invocation:是否禁止模型自动触发(只能用户显式调)
effort:推理强度
model:指定用哪个模型(可选)
license / compatibility / metadata:其他元信息

正文:

正文是注入给模型的内容——指令、流程、示例。模型调用这个 Skill 时,正文被包成信封注入对话,模型据此工作。

关键概念:SKILL.md 的核心是「用自然语言封装方法论」。frontmatter 描述「何时用、能用什么」,正文描述「怎么做」。一个好的 Skill,是把你脑子里的「这种事应该这么干」显式地写下来,让 Agent 也能这么干。

三、Skills 的发现与 scope

Grok Build 启动时(以及会话过程中)会扫描多个位置,发现所有 SKILL.md:


SkillScope(优先级从高到低):
├── Local       # <cwd>/.grok/skills(当前工作目录)
├── Repo        # <git-root>/.grok/skills(仓库根)
├── User        # ~/.grok/skills(用户级)
├── Server      # 服务端下发
├── Bundled     # 内置
└── Plugin      # 插件提供

优先级的意义

同一个 name 的 Skill,可能存在于多个 scope(比如用户级有一个 code-review,项目级也有一个 code-review)。Grok Build 按 scope 优先级保留唯一一份——Local > Repo > User > Server > Bundled > Plugin。

这种「近的覆盖远的」让你可以:

在用户级定义通用的 code-review Skill
在某个项目里定义项目专用的 code-review Skill(覆盖用户的)
在某个子目录里定义更专的 code-review Skill(覆盖项目的)

类似 AGENTS.md 的优先级逻辑(第 7 章详谈),Skills 也遵循「越具体越优先」。

发现的时机

发现不是只发生一次:

启动时扫描所有 scope
会话过程中,如果目录变化或插件加载,会重新扫描
用户用 /create-skill 创建新 Skill 后,立即发现

这保证了 Skill 集合是动态的,反映当前环境。

四、信封注入机制

模型决定用一个 Skill 时(或用户显式调用时),框架把这个 Skill 的正文注入对话。注入用「信封」形式:


<skill name="code-review" description="审查代码改动..." path="~/.grok/skills/code-review/SKILL.md">
<SKILL.md 的正文内容>
</skill>

信封的作用:

明确边界:用 <skill> 标签包起来,模型知道「这是一段 Skill 内容,不是用户消息或工具结果」
携带元信息:name、description、path 让模型知道「这是哪个 Skill、它自称干什么、文件在哪」
区分来源:与普通对话内容区分,便于模型正确理解角色

注入后,模型按 Skill 的指引工作:


模型看到信封,理解:「现在按 code-review Skill 的流程审查代码」
    ↓
按正文描述的流程:
    1. 调 git diff(用 allowed-tools 里的 bash)
    2. 读相关文件
    3. 按维度审查
    4. 输出结构化意见

注意:Skill 不限制模型的「思考」,只提供「指引」。模型仍然可以基于具体情况调整,不是机械执行。这是 Skill 与「脚本」的区别——Skill 是「方法论建议」,模型理解后灵活应用。

五、Skills 的触发方式

Skill 的触发有两种方式:

方式一:模型自动触发(默认)

框架把已发现的 Skill 列表(通过 SkillDiscoveryReminder,第 5 章提过)提示给模型。模型在推理时,判断「当前任务是否匹配某个 Skill」,若是,则调用 use_tool 工具传入 Skill 名。


用户:"帮我审查这次的改动"
    ↓
模型看到 SkillDiscoveryReminder:
    "已发现的 Skill:code-review(审查代码改动)、git-commit(规范提交)、..."
    ↓
模型判断:当前任务匹配 code-review
    ↓
模型调用 use_tool({skill: "code-review"})
    ↓
框架把 code-review 的正文包成信封注入
    ↓
模型按 Skill 流程工作

关键:模型是否触发 Skill,取决于 description 写得好不好。description 要清楚地告诉模型「这个 Skill 适合什么场景」。写得差,模型可能不触发或乱触发。

方式二:用户显式触发

用户可以用斜杠命令显式调用:


/code-review                  # 调用 code-review Skill
/code-review 只看 src/ 目录    # 带参数
/local:my-skill               # 显式指定 scope 前缀

显式触发适用于:用户明确知道要用某个 Skill,或 Skill 设了 disable-model-invocation(禁止模型自动触发)。

触发的前缀限定

如果有多个同名 Skill(不同 scope),用户可以用前缀限定:

local:code-review:用 Local scope 的
repo:code-review:用 Repo scope 的
user:code-review:用 User scope 的
plugin:code-review:用 Plugin 提供的

这避免了歧义,让你能精确指定用哪个版本。

六、Skills 与 allowed-tools 的限制

SKILL.md 的 frontmatter 里有个 allowed-tools 字段,限制这个 Skill 内能用的工具:


allowed-tools:
  - GrokBuild:read_file
  - GrokBuild:bash
  - GrokBuild:grep

限制的意义:

最小权限:Skill 只用它能用的工具,降低误操作风险
明确意图:从 allowed-tools 就能看出这个 Skill 会做什么(读文件、跑命令、搜索)
安全审计:管理员审查 Skill 时,看 allowed-tools 就知道能力边界

实现:Skill 触发后,框架在 Skill 的工作期间,把工具白名单限定为 allowed-tools(叠加会话原有的限制)。模型尝试调用白名单外的工具会被拒。

这种「Skill 自带工具范围」的设计,让每个 Skill 像一个「有明确职责的子助手」——它的能力被 Skill 定义清楚,不会越界。

七、几个典型 Skill 的例子

为了让概念更具体,几个典型 Skill:

代码审查 Skill(上文示例)

封装审查流程,让 Agent 按结构化维度审查代码。

提交规范 Skill


---
name: git-commit
description: 按团队规范创建 Git 提交
when-to-use: 当用户要提交代码,或描述说要 commit
allowed-tools:
  - GrokBuild:bash
  - GrokBuild:read_file
---

# 提交规范

1. 用 git diff --staged 看暂存的改动
2. 写提交信息:
   - 格式:<type>(<scope>): <subject>
   - type: feat/fix/docs/refactor/test/chore
   - subject: 祈使句,不超过 50 字
3. 如有必要,加空行与正文(每行 ≤72 字)
4. 用 git commit 提交

让 Agent 的提交符合团队规范,无需每次提醒。

测试编写 Skill

封装测试编写的最佳实践(测试结构、命名、断言风格等),让 Agent 写出符合项目风格的测试。

故障排查 Skill

封装「遇到错误时怎么排查」的流程:读错误信息、复现、定位、修复、验证。让 Agent 像老手一样系统化排查,而不是乱试。

八、Skills 与其他扩展的关系

Skills 与其他扩展机制的协作:

Skills + 工具

Skill 通过 allowed-tools 限定能用的工具。一个 Skill 通常组合多个工具完成方法论。比如 code-review Skill 组合 read_file + bash + grep。

Skills + 插件

Skill 是插件能打包的内容之一(第 03 节会详谈)。一个插件可以包含多个 Skill,作为「Skill 包」分发。

Skills + 记忆

Skill 提供通用方法论,记忆(第 7 章)提供项目特定的知识。两者结合:Skill 告诉「怎么审查」,记忆告诉「这个项目的审查重点是什么」。

Skills 与 MCP 的对比

维度	Skills	MCP
扩展什么	知识/方法论	能力/工具
实现形式	Markdown 文件	可执行 server
触发方式	模型自动/用户显式	模型调用工具
注入方式	prompt 信封	工具调用
适合	封装最佳实践	接入外部系统

两者互补:Skill 教 Agent 怎么想,工具/MCP 让 Agent 能做什么。

九、写好 Skill 的几个建议

写 Skill 是一种新的技能,几个建议:

建议一:description 要精准

description 决定模型何时触发。要写清楚「这个 Skill 适合什么场景」,避免过于宽泛(到处触发)或过于狭窄(从不触发)。

建议二:正文要具体

正文是给 Agent 的指引,要具体可执行。「审查代码」太抽象,「按正确性/可读性/安全性三个维度审查,每个维度列出问题」就具体。

建议三:用 allowed-tools 限定范围

不要让 Skill 能用所有工具。只给它需要的,既安全又明确意图。

建议四:提供示例

正文中给一两个具体示例,帮模型理解你期望的行为。示例比抽象描述更有效。

建议五:迭代优化

Skill 写完,实际用,观察 Agent 的行为。如果不符预期,调整 description 或正文。Skill 是「可进化的资产」,持续打磨。

十、Skills 的局限

公平起见,也看 Skills 的局限:

局限一:依赖模型理解

Skill 是自然语言,模型理解可能有偏差。复杂的 Skill 可能被模型简化或曲解。

局限二:占用上下文

Skill 触发后,正文进上下文。长 Skill 会占用宝贵的上下文空间。

局限三:不是强制

Skill 是建议,不是强制。模型可能不按 Skill 走,尤其在它「有自己想法」时。

局限四:触发可能不准

模型可能误触发(任务不匹配却用了 Skill)或漏触发(该用却没用)。description 质量是关键。

这些局限不否定 Skills 的价值,只是说明它是一种「软扩展」,效果取决于模型能力与 Skill 质量。

本节要点回顾

Skills 扩展知识与方法论:与工具扩展能力互补,让 Agent 知道「怎么做」。
与系统提示的区别:Skill 是按需、可发现的,不相关时不占上下文。
SKILL.md 格式:YAML frontmatter(name/description/when-to-use/allowed-tools 等)+ Markdown 正文。
发现按 scope 优先级:Local > Repo > User > Server > Bundled > Plugin,近的覆盖远的。
信封注入:<skill> 标签包正文,带 name/description/path,明确边界与元信息。
触发两种方式:模型自动(SkillDiscoveryReminder 提示)+ 用户显式(/skill 命令)。
触发依赖 description:写得好模型才能精准触发,可迭代优化。
allowed-tools 限定范围:最小权限、明确意图、便于审计,Skill 像有职责的子助手。
典型 Skill:代码审查、提交规范、测试编写、故障排查——封装最佳实践。
与其他扩展关系:组合工具、可被插件打包、与记忆互补、与 MCP 互补。
局限:依赖模型理解、占上下文、非强制、触发可能不准——是软扩展。

下一节,我们看插件系统——它把 skills、commands、agents、hooks、MCP 等多种扩展打包成一个可分发单位。