Agent skills

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

可以直接通过 agent 的 skills 配置附加 skills，也可以在 workspace 上配置它们。Agent 级 skills 属于单个 agent，可以在没有 workspace 的情况下用代码定义；而 workspace skills 从文件系统发现，并由使用该 workspace 的每个 agent 共享。本页介绍如何定义和加载带按请求解析的 agent 级 skills。

何时使用 agent 级 skills

在以下情况下使用 agent 级 skills：

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

如需在项目中基于文件系统发现 skills，请改用 workspace skills。

快速开始

内联定义一个 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 工具，以便在对话中发现和加载 skills。

定义内联 skills

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

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 工具读取的辅助文档，类似文件系统 skill 中的 references/ 文件。关于完整 API，请访问 createSkill() 参考。

文件系统路径 skills

指向磁盘上的 skill 目录，无需 workspace：

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 skills相同格式的 SKILL.md 文件。

动态 skills

如需按请求解析 skills，传入一个函数：

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 让你可以为自己的工作创建子 spans，方式与工具相同。解析器也会在元数据读取（例如 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
}

关于在 agents 和 workflows 中使用 request context 的更多信息，请参阅 Request Context。

与 workspace skills 合并

当 agent 同时配置了 skills 和带 skills 的 workspace 时，它们会合并。名称冲突时 agent 级 skills 优先：

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
})

以编程方式访问 skills

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

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() 参考。

保存前校验 skills

如果你的应用写入 SKILL.md 文件（来自工具、上传或 shell 命令），请先使用 validateSkillContent() 校验内容。它会应用加载 skills 时使用的相同规则，包括检查 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 lists non-blocking issues, such as very long instructions

要校验已解析的 frontmatter 对象，请使用 validateSkillMetadata({ metadata, directoryName })。

相关

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