Agent Skill

Skill 是可复用的指令，用于教 Agent 如何执行特定任务。它们遵循 Agent Skills 规范。

你可以通过 Agent 的 skills 配置直接附加 Skill，也可以在 Workspace 中配置。当 Skill 专属于某个 Agent，并且你希望直接在代码中定义而不需要 Workspace 时，请将其附加到 Agent。当你希望从文件系统中发现 Skill，并在使用该 Workspace 的所有 Agent 之间共享时，请使用 Workspace。本页介绍 Agent 级方式，包括在代码中定义 Skill、从文件加载 Skill，以及按请求解析 Skill。

何时使用 Agent 级 Skill

以下情况适合使用 Agent 级 Skill：

• 你希望 Agent 自包含，不依赖 Workspace
• Skill 在代码中定义，不需要文件系统发现
• 你正在构建包含 Agent 能力的包或库
• 你需要根据上下文按请求解析 Skill

如果需要在项目中基于文件系统发现 Skill，请改用 Workspace Skill。

快速开始

以内联方式定义 Skill，并将其附加到 Agent：

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { createSkill } from '@mastra/core/skills'

const codeReview = createSkill({
  name: 'code-review',
  description: 'Use when reviewing code changes.',
  instructions: `
    When reviewing code:
    1. Check for correctness and edge cases
    2. Verify style consistency
    3. Look for potential bugs
  `,
})

export const reviewer = new Agent({
  id: 'reviewer',
  model: 'openai/gpt-5.6-sol',
  instructions: 'You are a code review assistant.',
  skills: [codeReview],
})

Agent 会自动获得 skill、skill_read 和 skill_search Tool，因此可以在对话中发现并加载 Skill。

定义内联 Skill

使用 createSkill() 完全在代码中创建 Skill：

src/mastra/skills.ts

import { createSkill } from '@mastra/core/skills'

export const releaseChecklist = createSkill({
  name: 'release-checklist',
  description: 'Use when preparing a release.',
  instructions: `
    ## Release Checklist
    1. Run the full test suite
    2. Update CHANGELOG.md
    3. Bump version numbers
    4. Create a git tag
  `,
  references: {
    'changelog-format.md': '# Changelog Format\nUse Keep a Changelog...',
  },
})

references 字段会将支持文档打包，Agent 可使用 skill_read Tool 读取它们，就像读取文件系统 Skill 中的 references/ 文件一样。有关完整 API，请参阅 createSkill() 参考。

文件系统路径 Skill

无需 Workspace，即可指向磁盘上的 Skill 目录：

src/mastra/agents/index.ts

import { 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', // path to a SKILL.md directory
    './skills/testing', // another filesystem skill
    createSkill({/* ... */}), // inline skill
  ],
})

文件系统路径在底层使用 LocalSkillSource，它读取遵循与 Workspace Skill 相同格式的 SKILL.md 文件。

动态 Skill

要按请求解析 Skill，请传入函数：

src/mastra/agents/index.ts

import { 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]
  },
})

解析器函数接收 { requestContext, tracingContext }，并返回 SkillInput[] 数组或 Promise<SkillInput[]>。

解析器会为每个 RequestContext 运行一次。在 Agent 执行期间，它会在 resolve-skills span 内运行，而 tracingContext.currentSpan 让你可以像 Tool 一样为自己的工作创建子 span。解析器也会在 agent.listSkills() 和服务器 Agent 端点等元数据读取操作中运行；此时不存在 span，且 tracingContext.currentSpan 为 undefined，因此请确保它运行迅速，并对任何 span 用法添加保护：

src/mastra/agents/index.ts

skills: 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 Skill 合并

当 Agent 同时配置了 skills 和带有 Skill 的 Workspace 时，两者会合并。如果名称冲突，Agent 级 Skill 优先：

src/mastra/agents/index.ts

import { 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'], // provides "code-review" skill
})

const customReview = createSkill({
  name: 'code-review', // same name as workspace skill
  description: 'Custom review process.',
  instructions: '...',
})

export const reviewer = new Agent({
  id: 'reviewer',
  model: 'openai/gpt-5.6-sol',
  workspace,
  skills: [customReview], // agent-level "code-review" wins
})

以编程方式访问 Skill

使用 agent.getSkill() 和 agent.listSkills() 从应用代码（例如 Workflow 或 API 路由）访问 Skill：

src/routes/skills.ts

import { reviewer } from '../mastra/agents'

// Get a specific skill by name
const skill = await reviewer.getSkill('code-review')
if (skill) {
  console.log(skill.instructions)
}

// List all available skills
const allSkills = await reviewer.listSkills()
for (const meta of allSkills) {
  console.log(`${meta.name}: ${meta.description}`)
}

有关完整 API，请参阅 .getSkill() 参考和 .listSkills() 参考。

相关内容

• Workspace Skill
• createSkill() 参考
• .getSkill() 参考
• .listSkills() 参考
• Agent Skills 规范