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

# Workspace の Skill

**追加バージョン:** `@mastra/core@1.1.0`

Skill は、特定のタスクを実行する方法を Agent に教える再利用可能な指示です。Agent の機能をパッケージ化するためのオープン標準である [Agent Skills 仕様](https://agentskills.io)に準拠しています。

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 を把握し、必要に応じて任意の Skill を読み込めます。

Agent には、次の3つの Skill Tool があります。

- **`skill`**: Skill の指示全文を読み込み、Tool の実行結果として返します。Agent は Skill のガイダンスが必要になるたびに、この Tool を呼び出します。
- **`skill_read`**: Skill の `references/`、`scripts/`、または `assets/` ディレクトリからファイルを読み取ります。
- **`skill_search`**: すべての Skill コンテンツを横断して検索します。設定されている場合は BM25 またはベクトル検索を使用し、それ以外の場合は基本的なテキストマッチングにフォールバックします。

この設計はステートレスであり、追跡する有効化状態はありません。コンテキストウィンドウの制限や圧縮によって Skill の指示が会話コンテキストから外れた場合、Agent は `skill` を再度呼び出して指示を読み込み直せます。

## 同名の Skill

複数の Skill ディレクトリに同じ名前の Skill が含まれている場合、そのすべてが検出され、一覧表示されます。Agent のシステムメッセージには、各 Skill のパスとソースタイプも表示されるため、それらを区別できます。

Agent が名前を指定して Skill を有効化すると、次の優先順位で返される Skill が決まります。

1. **ソースタイプの優先順位**: ローカル Skill は managed Skill（`.mastra/`）より優先され、managed Skill は external Skill（`node_modules/`）より優先されます。
2. **解決できない競合はエラー**: 同じ名前と同じソースタイプを持つ Skill が2つある場合（たとえば、ローカル 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` は、次の3つのパラメーターを受け取ります。

- **`versionTree`**（`SkillVersionTree`）: 相対ファイルパスを blob エントリに対応付けるマニフェスト（`{ entries: Record<string, { blobHash, size, mimeType?, encoding? }> }`）。
- **`blobStore`**（`BlobStore`）: ハッシュから参照される実際のファイル内容を保持する、コンテンツアドレス指定可能な blob ストアのインスタンス。
- **`versionCreatedAt`**（`Date`）: この Skill バージョンが公開された日時。バージョン内のすべてのファイルの更新日時として使用されます。

`skillSource` を指定すると、Skill の検出には Workspace のファイルシステムの代わりにこれが使用されます。

## Agent レベルの Skill

`createSkill()` と Agent の `skills` 設定を使用すると、Workspace を使わずに Skill を Agent に直接割り当てることもできます。Agent レベルと Workspace レベルの Skill が両方存在する場合、それらは統合され、名前が競合するときは Agent レベルの Skill が優先されます。

詳しくは、[Agent の Skill](https://mastra.zisheng.pro/ja/docs/agents/skills)を参照してください。

## 関連項目

- [Agent の Skill](https://mastra.zisheng.pro/ja/docs/agents/skills)
- [Agent Skills 仕様](https://agentskills.io)
- [Workspace の概要](https://mastra.zisheng.pro/ja/docs/workspace/overview)
- [検索とインデックス作成](https://mastra.zisheng.pro/ja/docs/workspace/search)
- [`createSkill()` リファレンス](https://mastra.zisheng.pro/ja/reference/agents/createSkill)