Workspace Skills

新增於： @mastra/core@1.1.0

Skill 是可重複使用的指示，用來教導 Agent 如何執行特定任務。Skill 遵循 Agent Skills 規範，這是一項用於封裝 Agent 能力的開放標準。

一個 Skill 是包含下列項目的資料夾：

• SKILL.md：提供給 Agent 的指示與中繼資料
• references/：支援文件（選用）
• scripts/：可執行指令碼（選用）
• assets/：圖片與其他檔案（選用）

Folder structure

skills/
  code-review/
    SKILL.md
    references/
      style-guide.md
      pr-checklist.md
    scripts/
      lint.ts

在 Workspace 上設定 Skill 後，Agent 可以在對話期間探索並啟用它們。

SKILL.md 格式

建立 Skill 時，請遵循官方的 Skill 規範。以下是程式碼審查 Skill 的 SKILL.md 範例：

SKILL.md

---
name: code-review
description: Reviews code for quality, style, and potential issues
version: 1.0.0
tags:
  - development
  - review
---

# Code Review

You are a code reviewer. When reviewing code:

1. Check for bugs and edge cases
2. Verify the code follows the style guide in references/style-guide.md
3. Suggest improvements for readability
4. Run the linter using scripts/lint.ts

## What to look out for

- Unused variables and imports
- Missing error handling
- Security vulnerabilities
- Performance issues

設定 Skill

在 Workspace 上設定 skills 選項，即可啟用 Skill 探索功能：

src/mastra/workspaces.ts

import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'],
})

你可以指定多個 Skill 目錄：

src/mastra/workspaces.ts

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: [
    'skills', // Project skills
    'team-skills', // Shared team skills
  ],
})

也可以直接傳入 Skill 目錄或 SKILL.md 檔案的路徑：

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['path/to/my-skill'],
})

Glob 模式可讓你探索巢狀目錄中的 Skill：

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['./**/skills'],
})

動態 Skill

若 Skill 路徑需要依執行階段情境決定，請傳入函式：

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ctx => {
    const paths = ['skills']
    if (ctx.requestContext?.get('userRole') === 'developer') {
      paths.push('dev-skills')
    }
    return paths
  },
})

Agent 如何使用 Skill

Workspace 設定 Skill 後，Agent 會自動取得 Skill Tool。系統訊息會列出可用的 Skill，讓 Agent 知道有哪些選項，並能按需載入任何 Skill。

Agent 有三個 Skill Tool：

• skill：載入 Skill 的完整指示，並在 Tool 結果中傳回。每當 Agent 需要 Skill 的指引時，就會呼叫此 Tool。
• skill_read：讀取 Skill 的 references/、scripts/ 或 assets/ 目錄中的檔案。
• skill_search：搜尋所有 Skill 內容。若已設定 BM25 或向量搜尋，便會使用它們；否則會改用基本文字比對。

此設計不保留狀態，因此不需要追蹤啟用狀態。如果 Skill 指示離開對話情境（例如超出情境窗口限制或發生壓縮），Agent 可以再次呼叫 skill 重新載入。

同名 Skill

當多個 Skill 目錄包含同名 Skill 時，系統會探索並列出所有 Skill。Agent 會在系統訊息中看到每個 Skill 及其路徑與來源類型，因此能加以區分。

當 Agent 依名稱啟用 Skill 時，會透過下列優先規則決定傳回哪一個：

1. 來源類型優先順序：本機 Skill 優先於受管理的（.mastra/）Skill，而受管理的 Skill 又優先於外部（node_modules/）Skill。
2. 無法解析的衝突會擲回錯誤：如果兩個 Skill 的名稱與來源類型都相同（例如兩個本機 Skill 都名為 brand-guidelines），get() 會擲回錯誤。請重新命名其中一個，或將其移至不同來源類型以解決衝突。
3. 路徑替代方案：Agent 可以傳入 Skill 的完整路徑，而不是其名稱，直接啟用特定 Skill，完全略過優先規則。

Example: local skill shadows an external package skill

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: [
    'node_modules/@myorg/skills', // external: provides "brand-guidelines"
    'skills', // local: also provides "brand-guidelines"
  ],
})

// get('brand-guidelines') returns the local copy (local > external)
// get('node_modules/@myorg/skills/brand-guidelines') returns the external copy

Skill 搜尋

如果 Workspace 已啟用 BM25 或向量搜尋，系統會自動為 Skill 建立索引。Agent 可以搜尋所有 Skill 內容，找出相關指示。

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'],
  bm25: true,
})

自訂 Skill 來源

Skill 預設從 Workspace 檔案系統讀取。進階使用情境則可以提供自訂 skillSource，從不同後端載入 Skill。

VersionedSkillSource 會從內容定址的 Blob 儲存區提供已發布的 Skill 版本，因此正式環境 Agent 可以使用特定的已發布版本，而不必碰觸即時檔案系統：

import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
import { VersionedSkillSource } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'],
  skillSource: new VersionedSkillSource(versionTree, blobStore, versionCreatedAt),
})

VersionedSkillSource 接受三個參數：

• versionTree（SkillVersionTree）：將相對檔案路徑對應至 Blob 項目的資訊清單（{ entries: Record<string, { blobHash, size, mimeType?, encoding? }> }）。
• blobStore（BlobStore）：內容定址的 Blob 儲存區執行個體，存放雜湊所參照的實際檔案內容。
• versionCreatedAt（Date）：此 Skill 版本的發布時間戳記，會用作該版本中所有檔案的修改時間。

提供 skillSource 後，系統會以它取代 Workspace 檔案系統來探索 Skill。

Agent 層級的 Skill

你也可以使用 createSkill() 與 Agent 的 skills 設定，直接將 Skill 附加至不含 Workspace 的 Agent。當 Agent 層級與 Workspace 層級的 Skill 同時存在時，兩者會合併；若名稱衝突，Agent 層級的 Skill 優先。

詳情請參閱 Agent Skills。

相關資源

• Agent Skills
• Agent Skills 規範
• Workspace 概觀
• 搜尋與索引
• createSkill() 參考