> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Agent Skill

Skill 是可复用的指令，用于教 Agent 如何执行特定任务。它们遵循 [Agent Skills 规范](https://agentskills.io)。

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

## 何时使用 Agent 级 Skill

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

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

如果需要在项目中基于文件系统发现 Skill，请改用 [Workspace Skill](https://mastra.zisheng.pro/docs/workspace/skills)。

## 快速开始

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

```typescript
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：

```typescript
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()` 参考](https://mastra.zisheng.pro/reference/agents/createSkill)。

## 文件系统路径 Skill

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

```typescript
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](https://mastra.zisheng.pro/docs/workspace/skills) 相同格式的 `SKILL.md` 文件。

## 动态 Skill

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

```typescript
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 用法添加保护：

```typescript
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](https://mastra.zisheng.pro/docs/server/request-context)。

## 与 Workspace Skill 合并

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

```typescript
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：

```typescript
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()` 参考](https://mastra.zisheng.pro/reference/agents/getSkill)和 [`.listSkills()` 参考](https://mastra.zisheng.pro/reference/agents/listSkills)。

## 相关内容

- [Workspace Skill](https://mastra.zisheng.pro/docs/workspace/skills)
- [`createSkill()` 参考](https://mastra.zisheng.pro/reference/agents/createSkill)
- [`.getSkill()` 参考](https://mastra.zisheng.pro/reference/agents/getSkill)
- [`.listSkills()` 参考](https://mastra.zisheng.pro/reference/agents/listSkills)
- [Agent Skills 规范](https://agentskills.io)