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

# Workspace Skills

**新增於：** `@mastra/core@1.1.0`

Skill 是可重用的指示，用於教導 Agent 如何執行特定任務。Skill 遵循 [Agent Skills 規範](https://agentskills.io)，這是一項用於封裝 Agent 能力的開放標準。

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

- `SKILL.md`：供 Agent 使用的指示及 metadata
- `references/`：輔助文件（可選）
- `scripts/`：可執行腳本（可選）
- `assets/`：圖片及其他文件（可選）

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

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

## `SKILL.md` 格式

建立 Skill 時，請遵循官方的 [Skill 規範](https://agentskills.io/specification)。以下是程式碼審查 Skill 的 `SKILL.md` 範例：

```markdown
---
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 探索功能：

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

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

你可以指定多個 Skill 目錄：

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

你亦可以直接傳入 Skill 目錄或 `SKILL.md` 文件的路徑：

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

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

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

## 動態 Skill

如需根據 context 在 runtime 決定 Skill 路徑，請傳入函數：

```typescript
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，從而完全繞過優先規則。

```typescript
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 內容，以找出相關指示。

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

## 自訂 Skill 來源

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

`VersionedSkillSource` 從以內容定址的 blob store 提供已發佈的 Skill 版本，讓正式環境中的 Agent 使用指定的已發佈版本，而無需存取即時檔案系統：

```typescript
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](https://mastra.zisheng.pro/zh-HK/docs/agents/skills)。

## 相關內容

- [Agent Skills](https://mastra.zisheng.pro/zh-HK/docs/agents/skills)
- [Agent Skills 規範](https://agentskills.io)
- [Workspace 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)
- [搜尋及建立索引](https://mastra.zisheng.pro/zh-HK/docs/workspace/search)
- [`createSkill()` 參考](https://mastra.zisheng.pro/zh-HK/reference/agents/createSkill)