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

# Agent Skill

Skill 是可重複使用的指令，用來教導 Agent 如何執行特定任務。它們遵循 [Agent Skills 規範](https://agentskills.io)。

你可以透過 Agent 的 `skills` 設定，直接將 Skill 附加至 Agent，也可以在 [Workspace](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview) 上設定。若 Skill 專屬於特定 Agent，且你想直接在程式碼中定義、不要求使用 Workspace，請將 Skill 附加至 Agent。若想從檔案系統探索 Skill，並在所有使用該 Workspace 的 Agent 之間共用，則請使用 Workspace。本頁介紹 Agent 層級的做法，包括在程式碼中定義 Skill、從檔案載入 Skill，以及依每個請求解析 Skill。

## 何時使用 Agent 層級 Skill

在下列情況下，請使用 Agent 層級 Skill：

- 你想要不依賴 Workspace、可獨立運作的 Agent
- Skill 定義在程式碼中，不需要檔案系統探索功能
- 你正在建置包含 Agent 能力的套件或程式庫
- 你需要根據情境，為每個請求解析不同的 Skill

若要在整個專案中探索檔案系統型 Skill，請改用 [Workspace Skill](https://mastra.zisheng.pro/zh-TW/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/zh-TW/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/zh-TW/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` 可讓你為自己的工作建立子 span，方式與 Tool 相同。解析器也會在讀取中繼資料時執行，例如呼叫 `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 使用請求情境，請參閱[請求情境](https://mastra.zisheng.pro/zh-TW/docs/server/request-context)。

## 與 Workspace Skill 合併

當 Agent 同時設有 `skills`，且其 Workspace 也設定了 Skill 時，兩者會合併。若名稱衝突，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/zh-TW/reference/agents/getSkill)與 [`.listSkills()` 參考文件](https://mastra.zisheng.pro/zh-TW/reference/agents/listSkills)。

## 相關內容

- [Workspace Skill](https://mastra.zisheng.pro/zh-TW/docs/workspace/skills)
- [`createSkill()` 參考文件](https://mastra.zisheng.pro/zh-TW/reference/agents/createSkill)
- [`.getSkill()` 參考文件](https://mastra.zisheng.pro/zh-TW/reference/agents/getSkill)
- [`.listSkills()` 參考文件](https://mastra.zisheng.pro/zh-TW/reference/agents/listSkills)
- [Agent Skills 規範](https://agentskills.io)