第12章 Agent Skills 智能体技能

Agent Skills（智能体技能）

Skills 是可复用的指令集，用于教会 agent 完成特定任务。它遵循 Agent Skills 规范。

你可以直接在 agent 的 skills 配置中挂载 skill，也可以在工作区（workspace）上配置。Agent 级别的 skill 属于单个 agent，无需 workspace 即可在代码中定义；而 workspace 级别的 skill 则从文件系统中发现，并由使用该 workspace 的所有 agent 共享。本页介绍如何定义和加载 agent 级别的 skill，以及如何进行按请求解析（per-request resolution）。

什么时候使用 agent 级别的 skill

以下场景适合使用 agent 级别的 skill：

• 你希望 agent 自包含，不依赖 workspace
• skill 直接在代码中定义，不需要文件系统发现机制
• 你在开发包含 agent 能力的包或库
• 你需要根据上下文进行按请求的 skill 解析

如果需要在整个项目中基于文件系统发现 skill，请改用 workspace skill。

快速上手

内联定义一个 skill 并挂载到 agent 上：

src/mastra/agents/index.ts

该 agent 会自动获得 skill、skill_read 和 skill_search 三个工具，从而能在对话过程中发现并加载 skill。

定义内联 skill

使用 createSkill() 可以完全在代码中创建 skill：

src/mastra/skills.ts

references 字段用于打包支持文档，agent 可以通过 skill_read 工具读取，就像 filesystem skill 中的 references/ 文件一样。完整的 API 说明请参阅 createSkill() 参考文档。 文件系统路径技能（Filesystem path skills） 无需 workspace，直接指向磁盘上的 skill 目录： src/mastra/agents/index.tsimport { Agent } from '@mastra/core/agent'
import { createSkill } from '@mastra/core/skills'

export const agent = new Agent({
id: 'my-agent',
model: 'openai/gpt-5.6-sol',
skills: [
'./skills/code-review', // 指向包含 SKILL.md 的目录
'./skills/testing', // 另一个 filesystem skill
createSkill({/* ... */}), // 内联 skill
],
})
文件系统路径底层使用 LocalSkillSource，其读取 SKILL.md 文件的格式与 workspace skill 相同。 动态技能（Dynamic skills） 如果需要按请求解析 skill，可以传入一个函数： src/mastra/agents/index.tsimport { Agent } from '@mastra/core/agent'
import { createSkill } from '@mastra/core/skills'

const devSkill = createSkill({
name: 'dev-tools',
description: 'Developer productivity tools.',
instructions: '...',
})

const supportSkill = createSkill({
name: 'support-guide',
description: 'Customer support guidelines.',
instructions: '...',
})

export const agent = new Agent({
id: 'dynamic-agent',
model: 'openai/gpt-5.6-sol',
skills: ({ requestContext }) => {
const role = requestContext.get('userRole')
if (role === 'developer') return [devSkill]
return [supportSkill]
},
})
resolver 函数接收 { requestContext, tracingContext } 参数，返回 SkillInput[] 数组或 Promise。 每个 RequestContext 只执行一次 resolver。在 agent 执行期间，它运行在一个 resolve-skills span 内，tracingContext.currentSpan 允许你为自己的工作创建子 span，用法与 tools 相同。resolver 也会在读取元数据时执行，例如 agent.listSkills() 和服务端的 agent 端点，此时不存在 span，tracingContext.currentSpan 为 undefined，因此要保持 resolver 轻量，并对 span 的使用做好防护： src/mastra/agents/index.tsskills: async ({ requestContext, tracingContext }) => {
const span = tracingContext?.currentSpan?.createChildSpan({
type: 'generic',
name: 'entitlements-lookup',
})
const skills = await fetchSkillsFor(requestContext.get('userId')) span?.end()
return skills
}
关于在 agent 和 workflow 中使用请求上下文的更多信息，请参见 Request Context。 与 workspace 技能合并 当 agent 同时配置了技能和包含技能的 workspace 时，两者会合并。名称冲突时，agent 级别的技能优先： src/mastra/agents/index.tsimport { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
import { createSkill } from '@mastra/core/skills'

const workspace = new Workspace({
filesystem: new LocalFilesystem({ basePath: './workspace' }),
skills: ['skills'], // 提供 "code-review" 技能
})

const customReview = createSkill({
name: 'code-review', // 与 workspace 技能同名
description: 'Custom review process.',
instructions: '...',
})

export const reviewer = new Agent({
id: 'reviewer',
model: 'openai/gpt-5.6-sol',
workspace,
skills: [customReview], // agent 级别的 "code-review" 生效
})
以编程方式访问技能 在应用代码中（例如 workflow 或 API 路由），可以使用 agent.getSkill() 和 agent.listSkills() 访问技能： src/routes/skills.tsimport { reviewer } from '../mastra/agents'

// 按名称获取指定技能
const skill = await reviewer.getSkill('code-review')
if (skill) {
console.log(skill.instructions)
}

// 列出所有可用技能
const allSkills = await reviewer.listSkills()
for (const meta of allSkills) {
console.log(`${meta.name}: ${meta.description}`)
}
完整 API 请参见 .getSkill() 参考文档 和 .listSkills() 参考文档。 保存前校验技能 如果你的应用会写入 SKILL.md 文件（来自工具、上传或 shell 命令），请先用 validateSkillContent() 校验内容。它使用与技能加载时相同的校验规则（包括检查 name 是否与目录名一致），并以结构化结果返回而不是直接抛错： import { validateSkillContent } from '@mastra/core/skills'

const result = validateSkillContent({ content: skillMarkdown, directoryName: 'code-review' })

if (!result.valid) {
throw new Error(`Invalid skill:\n${result.errors.join('\n')}`)
}
// result.warnings 列出非阻断性问题，例如过长的 instructions
要校验已解析的 frontmatter 对象，可使用 validateSkillMetadata({ metadata, directoryName })。 相关链接 Workspace skills createSkill() 参考 .getSkill() 参考 .listSkillos() 参考 Agent skills 规范