Skills

ファイルベース Agent は、skills/ ディレクトリから Skill を検出し、ビルド時にバンドルします。Skill は再利用可能な手順や参考資料です。すべての詳細を常時有効なプロンプトに含める代わりに、必要に応じて Agent が読み込めます。

ファイルベースの規約については、このページを参照してください。コードで定義する Skill については、Agent skillsを参照してください。SKILL.md のパッケージ形式については、Workspace skillsを参照してください。

クイックスタート

最も簡単な Skill は、skills/ 配下に置く1つの Markdown ファイルです。ファイル名が Skill 名になり、description はその Skill をいつ読み込むかを Agent に示します。

src/mastra/agents/weather/skills/temperature-units.md

---
description: Use when reporting temperatures or comparing forecast units.
---

Always report temperatures in Celsius and Fahrenheit. Include the user's preferred unit first when known.

Skill、Tool、instruction の違い

目的	使用するもの	理由
常に適用するアイデンティティ、トーン、ルール	instructions.md	モデルが毎回その指示を参照する必要があるため。
入出力を伴う呼び出し可能なアクション	tools/	モデルがコードを実行する、API を呼び出す、または副作用を発生させる必要があるため。
必要なときに読み込む詳細な参考資料や手順	skills/	モデルが特定のタスクでのみ完全な指示を必要とするため。

Skill の形式

Mastra は、ファイルベースの Skill で次の3つの形式をサポートしています。

形式	使用する場面
TypeScript/JavaScript モジュール	コードから createSkill() の結果をデフォルトエクスポートする場合。
パッケージ化された SKILL.md ディレクトリ	Skill に指示と references/ 配下の補助ファイルが含まれる場合。
単一の Markdown ファイル	Skill が frontmatter と指示を含む1つの Markdown ファイルである場合。

パッケージ化された Skill では、SKILL.md の frontmatter に description が必要です。単一の Markdown Skill でも、frontmatter に description が必要です。Skill に何が含まれているかだけでなく、いつ使用するかを記述してください。

読み込まれる内容

ファイルベース Agent の Skill はビルド時に生成されたバンドルへ追加されるため、デプロイ後の Agent がディスクから読み込むことはありません。

パッケージ化された Skill の場合、Mastra は次の内容を読み込みます。

• メタデータと指示を格納した SKILL.md。
• 補助的な参考コンテンツとして、references/ 直下のファイル。

参考ファイルはファイル名をキーとして管理されます。references/ 配下にあるシンボリックリンクされたファイルとディレクトリは、検出時にスキップされます。

config との優先順位

検出された Skill は、config.ts 内の skills とマージされます。同じ名前が競合した場合は config.skills が優先され、警告がログに記録されます。

config.skills が関数の場合、関数値の Skill は静的にマージできないため、検出された Skill は警告とともに無視されます。