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

# Workspace Skills

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

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

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

- `SKILL.md`：提供給 Agent 的指示與中繼資料
- `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 模式可讓你探索巢狀目錄中的 Skill：

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

## 動態 Skill

若 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，讓 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，完全略過優先規則。

```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 來源

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

`VersionedSkillSource` 會從內容定址的 Blob 儲存區提供已發布的 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 項目的資訊清單（`{ 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](https://mastra.zisheng.pro/zh-TW/docs/agents/skills)。

## 相關資源

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