Workspace の Skill

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

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

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 を把握し、必要に応じて任意の 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 を有効化できます。

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 は、次の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を参照してください。

関連項目

• Agent の Skill
• Agent Skills 仕様
• Workspace の概要
• 検索とインデックス作成
• createSkill() リファレンス