Agent Skill

Skill 是可重複使用的指令，用來教導 Agent 如何執行特定任務。它們遵循 Agent Skills 規範。

你可以透過 Agent 的 skills 設定，直接將 Skill 附加至 Agent，也可以在 Workspace 上設定。若 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。

快速入門

以內嵌方式定義 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 可讓你為自己的工作建立子 span，方式與 Tool 相同。解析器也會在讀取中繼資料時執行，例如呼叫 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 使用請求情境，請參閱請求情境。

與 Workspace Skill 合併

當 Agent 同時設有 skills，且其 Workspace 也設定了 Skill 時，兩者會合併。若名稱衝突，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 規範