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：

• 你想建立不依賴 Workspace、可獨立運作的 Agent
• 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/ 檔案。請參閱 createSkill() 參考資料，了解完整 API。

檔案系統路徑 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 可讓你建立子 span 來處理自己的工作，做法與 Tool 相同。解析器亦會在讀取 metadata 時執行，例如呼叫 agent.listSkills() 和存取伺服器的 Agent endpoint；這些情況下並不存在 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，請參閱 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 route）存取 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}`)
}

請參閱 .getSkill() 參考資料 和 .listSkills() 參考資料，了解完整 API。

相關內容

• Workspace Skill
• createSkill() 參考資料
• .getSkill() 參考資料
• .listSkills() 參考資料
• Agent Skills 規範