纸飞机的信笺
博客Awesome开源Demos制品库

从零开始搭建 Agent:③ Agent Skills

  1. Agent Skills 功能简介
  2. 基础版 Agent Skills
  3. 支持多文档的 Agent Skills

从零开始搭建 Agent:③ Agent Skills

2026年 7月 10日AI#AI#JS留言: ...

截至上篇,我们已经介绍了如何从零开始搭建一个支持双端工具调用的会话系统。 本文基于之前的代码,实现 Agent Skills 功能。

Agent Skills 功能简介#

Agent Skills 是一种用于 “扩展 AI 能力” 的功能。

Skill 是一段很长的提示词文本,用于教 AI 大模型做某件事情。在中文语境下,它也被称为 “技能”。Skill 可以扩展 AI 能力,或者让某些工作流程可被复用。


那么问题来了,为什么要使用 Skill 扩展 AI 能力?直接通过系统提示词来做,不是更简单?

首先,Agent 有可能安装了很多个 Skill,文本量太大;其次,我们的话题并不是每次必定涉及到 Skill,每次对话固定携带一大堆文本,如果用不到,既会分散 AI 的注意力,又会浪费 Token。

更何况,有些 Skill 的内容可能特别长。 例如某个第三方服务或者 SDK,它的文档可能有几十页,直接超出了 Agent 的最大上下文长度,直接注入上下文是不可能的。


而 Agent Skills 便是以上问题的解决方案: 它利用了大模型原生支持的工具调用,实现了一个核心概念:“渐进式披露”。

基础版 Agent Skills#

首先,Skill 的定义方式是这样的:

  • Skill 内容是一段提示词,可以是 Markdown 格式,可以写的很长;
  • 每个 Skill 都必须有一个唯一的名字 name,它被当作标识符使用,有一定格式要求;
  • 每个 Skill 都必须提供一段短小的描述 description,简单介绍这个 Skill 能做什么事情。

开发者对 Agent 进行以下配置:

  • Agent 初始化时,先扫描现有的所有 Skill 的 name 和 description,组成一个列表,通过系统提示词传达给 AI 大模型; 因为 name 和 description 都是短小的描述,所以这块内容占用不了多少上下文;
  • 同时注册一个 read_skill 的工具给 AI,当 AI 觉得自己需要用到某个 Skill 时,便把这个 Skill 的 name 作为参数来调用此工具,此工具便会找到这个 Skill,把它完整内容返回给 AI。

这样便实现了对提示词的 “按需加载”,也就是 “渐进式披露”。

首先,我们实现 Agent Skills 的 TypeScript 定义:

interface AgentSkills {
  name: string
  description: string
  content: string
}

基于这个定义,开发一个支持增删改查的 Agent Skills 列表,目前只需要在前端使用 JS 变量存储 Skill 数组。

组件如下:

在线 Demo
已加载 1 个 Skill

这个列表实现很简单,源码省略。

把 Agent Skills 列表和 AI 对话组件结合在一起,就可以实现允许前端自选 Skill 的 AI 对话。

一个完整的 Agent 工程是服务端数据库存储 Skills。但我们这里是 Demo,因此 Skills 存储于前端 JS 变量里,每次发送消息时,都要把 Skills 列表一起发给接口。

基于 前篇博客 的前端代码进行更新,在提交消息时,把 Agent Skills 列表带上:

// 之前是这样发送消息的:
sendMessage({ text: message.text.trim() })
 
// 改为:
sendMessage({ text: message.text.trim() }, { body: { skills } })

Vercel AI SDK 的 sendMessage 允许我们在第二个参数中定制请求,其中 body 里的字段会合并到请求的 Body 里。

后端的代码可以这样更新:

// 之前是这样接收参数的:
const { messages, skills } = (await request.json()) as { messages: UIMessage[] }
 
// 改为:
interface MessageWithSkills {
  messages: UIMessage[]
  skills: AgentSkills[]
}
 
const { messages, skills } = (await request.json()) as MessageWithSkills

拿到 Skills 列表后,我们需要拼装系统提示词,告知 AI 现在有哪些 Skills 可以使用。

在接口代码中,使用以下代码来生成系统提示词:

let system = undefined
if (skills.length > 0) {
  system = `你可以使用以下已加载的 Skills。先根据用户需求判断是否需要某个 Skill;需要时调用 \`read_skill\` 工具读取完整内容,并严格遵守 Skill 内容中的要求。\n\n`
  system += skills.map(skill => `- ${skill.name}: ${skill.description}`).join('\n')
}

除此之外,还需要提供 read_skill 工具。使用以下代码实现:

const read_skill = tool({
  description: '读取指定 Skill 的完整内容。当用户的需求匹配列表中的某个 Skill 时使用。',
  inputSchema: z.object({
    name: z
      .string()
      .describe('需要读取的 Skill 名称,必须与已加载 Skill 列表中的 key 完全一致。'),
  }),
  execute: async ({ name }) => {
    const skill = skills.find(skill => skill.name === name)
 
    if (!skill) {
      return {
        error: `未找到名为 ${name} 的 Skill。`,
        availableSkills: skills.map(skill => ({
          name: skill.name,
          description: skill.description,
        })),
      }
    }
 
    return skill.content
  },
})

将以上的系统提示词、工具注册,传给 AI SDK,代码如下:

const result = streamText({
  model: mainModel,
  system,
  messages: modelMessage,
  tools: { read_skill },
  stopWhen: stepCountIs(10),
})
 
return createUIMessageStreamResponse({
  stream: toUIMessageStream({ stream: result.stream }),
})

系统提示词通过 system 来传递,tools 也需要注册好,stopWhen 的步骤数可以相对提高。

这样,我们就实现了一个支持 Agent Skills 的 AI 对话:

在线 Demo

你好,我是 AI 工作助理,工作安排等问题尽管问我!

已加载 1 个 Skill

这个 Demo 中,预加载了一个名为 “会议通知的格式规范” 的 Skill 作为样品。

使用预填的提问内容,直接点击发送即可测试。 如果正确运作,可以看出 Agent 触发了 “读取 Skill 内容” 的工具调用,这样以来 Agent 便了解了 “会议纪要如何编写” 这个要求,因此大模型便得以根据我们的要求输出准确且符合需要的结果。

支持多文档的 Agent Skills#

有些时候,这份为 AI 准备的 “教学手册” 可能内容特别长,例如某个工具库的 Skill 可能有几十页之多;而 AI 每次可能只会用到其中的一部分,没有必要完整加载。

因此,Agent Skills 还需要允许对 Skill 内容的拆分,避免一次加载过多内容。而将一份 Markdown 文档拆分为多份,那它们之间必须建立关联,最简单的方式就是 Markdown 的超链接语法 [标题](路径.md)。

让 Skill 支持 “多文档”,可以将定义方式更新为:

  • 现在每个 Skill 都被当作是一个 “文件夹”,文件夹名必须和这个 Skill 的 name 完全相同;
  • Skill 的主 Markdown 文档只能有一个,放置于文件夹根级,且必须命名为 SKILL.md;
  • 其它拆分出来的文档,必须各自想好文件名,必须放置在 Skill 文件夹下的 references/ 目录中,彼此之间用 Markdown 超链接语法互相建立关联; 可以在 references/ 目录中再次划分子目录,例如 references/spec/、references/faq/ 等。

这样一来,Agent 的配置也必须更新:

  • Agent 初始化时扫描所有 Skill 的方式和之前不同了,因为每个 Skill 现在都是一个 “文件夹”;
  • 工具 read_skill 原来只支持传入 name,现在必须支持传入超链接的相对目录,解析目录来找到这个 Markdown 文件。

这便实现了 Skill 内容的 “按需加载”,进一步深化实践了 “渐进式披露”。

首先,更新 Agent Skills 的类型定义:

interface AgentSkillsReference {
  path: string
  content: string
}
 
interface AgentSkills {
  name: string
  description: string
  content: string
  references?: AgentSkillsReference[]
}

新增的 AgentSkillsReference 就是 Skill 的参考文档,每个 Skill 都有可能有多个参考文档。

接下来我们要更新 Agent Skills 的前端控件,支持多文档:

在线 Demo
已加载 1 个 Skill

点开其中项目,可以看到现在多了个 “references” 字段,列出了 Skill 的参考文档。

代码依然是把完整的 Skill 对象列表放在 Body 里提交,只不过这次的 Skill 带有 references 字段。这部分代码不用赘述。

然后是后端代码,现在 read_skill 工具需要支持传递 path 路径以加载多文档:

const read_skill = tool({
  description:
    '读取指定 Skill 的内容。可按名称读取列表中的 Skill,或按超链接的路径读取引用的文档(通常位于 references/ 下)。',
  inputSchema: z.object({
    name: z
      .string()
      .describe('需要读取的 Skill 名称,必须与已加载 Skill 列表中的 name 完全一致。'),
    path: z.string().trim().min(1).optional()
      .describe('可选。需要读取的相对路径,例如 references/some_file.md。不传时读取该 Skill 的主文档。'),
  }),
  execute: async ({ name, path }) => {
    const skill = parsedSkills.find(skill => skill.name === name)
 
    if (!skill) {
      return {
        error: `未找到名为 \`${name}\` 的 Skill。`,
        availableSkills: parsedSkills.map(skill => ({
          name: skill.name,
          description: skill.description,
        })),
      }
    }
 
    if (!path) {
      return skill.content
    }
 
    const reference = skill.references?.find(reference => reference.path === path)
    if (!reference) {
      return {
        error: `Skill \`${name}\` 中未找到路径为 \`${path}\` 的引用文档。`,
        availableReferences: (skill.references ?? []).map(reference => reference.path),
      }
    }
 
    return reference.content
  },
})

这里,为工具添加了 path 参数,因此工具描述、参数定义都要补全。

接下来,更新系统提示词,表明 Skill 有可能有参考文档:

let system = undefined
if (parsedSkills.length > 0) {
  system = `你可以使用以下已加载的 Skills。先根据用户需求判断是否需要某个 Skill;需要时调用 \`read_skill\` 工具读取内容,并严格遵守 Skill 内容中的要求。读取主文档时只传 \`name\`;如果主文档里出现了 Markdown 链接路径,例如 \`references/some_file.md\`,可继续传入 \`path\` 读取对应引用文档。\n\n`
 
  system += parsedSkills.map(skill => `- ${skill.name}: ${skill.description}`).join('\n')
}

这样,一个支持 references 多文档 Agent Skills 的 AI 对话工具就完成了。

下面给出示例,你可以用不同的提示词来测试:

在线 Demo

你好,我是 AI 工作助理,工作安排等问题尽管问我!

已加载 1 个 Skill

这个 Demo 中,会议纪要的 Skill 包含了三份子文档,分别是: “每日会议”、“项目组会议”、“年度会议”; 预填写的提示词要求编写一份 “每日会议”。

把提示词中的 “每日会议” 换成 “项目组会议”、“年度会议”,可以会发现 Agent 加载了不同的 Skill 文档,准确按照文档的规范进行输出。

这便是完整的 Agent Skills 功能中,最重要的多文档支持能力。

修订记录

  • 2026年 11月 18日
    feat(blog/article): 更新《Agent》系列文章
修订记录

留言