Workspace Skills

新增於： @mastra/core@1.1.0

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

一個 Skill 是包含以下內容的資料夾：

• SKILL.md：供 Agent 使用的指示及 metadata
• 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 pattern 可讓你探索巢狀目錄中的 Skill：

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

動態 Skill

如需根據 context 在 runtime 決定 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 會列於 system message 中，讓 Agent 知道有哪些 Skill，並可按需要載入任何 Skill。

Agent 有三個 Skill Tool：

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

此設計是無狀態的，因此無需追蹤啟用狀態。若 Skill 指示離開對話 context（例如因 context window 限制或內容壓縮），Agent 可以再次呼叫 skill 來重新載入指示。

同名 Skill

當多個 Skill 目錄包含同名 Skill 時，系統會探索並列出所有同名 Skill。Agent 可在 system message 中看到每個 Skill，以及其路徑和來源類型，從而分辨它們。

當 Agent 按名稱啟用 Skill 時，系統會按以下優先規則決定傳回哪一個：

1. 來源類型優先次序：本機 Skill 的優先次序高於受管理的（.mastra/）Skill，而受管理 Skill 的優先次序則高於外部（node_modules/）Skill。
2. 無法解決的衝突會拋出錯誤：如果兩個 Skill 名稱及來源類型均相同（例如兩個本機 Skill 均名為 brand-guidelines），get() 會拋出錯誤。請重新命名其中一個 Skill，或將其移至另一種來源類型，以解決衝突。
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 來源

預設情況下，系統會從 Workspace 檔案系統讀取 Skill。進階使用情境可提供自訂 skillSource，從其他後端載入 Skill。

VersionedSkillSource 從以內容定址的 blob store 提供已發佈的 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 項目的 manifest（{ entries: Record<string, { blobHash, size, mimeType?, encoding? }> }）。
• blobStore（BlobStore）：以內容定址的 blob store，保存由 hash 引用的實際文件內容。
• versionCreatedAt（Date）：此 Skill 版本的發佈時間戳記，用作該版本所有文件的修改時間。

提供 skillSource 後，Skill 探索會使用它，而非 Workspace 檔案系統。

Agent 層級 Skill

你亦可以使用 createSkill() 及 Agent 的 skills 設定，直接將 Skill 附加至沒有 Workspace 的 Agent。當 Agent 層級及 Workspace 層級的 Skill 同時存在時，兩者會合併；如名稱有衝突，Agent 層級 Skill 的優先次序較高。

詳情請參閱 Agent Skills。

相關內容

• Agent Skills
• Agent Skills 規範
• Workspace 概覽
• 搜尋及建立索引
• createSkill() 參考