初めに
Skillに「社内資料を検索する」と書くだけでは、検索ツールは使えるようになりません。
必要なのは、作業手順、ツールへの接続、実行条件の検証です。
今回は、Agent Skillsの仕様とPiの実装を参考に、SkillとMCPを組み合わせる設計を整理します。
1. Skillには「何ができるか」と「いつ使うか」を書く
Skillは、エージェントに専門的な作業手順を渡す仕組みです。
descriptionには、機能だけでなく、ユーザーのどんな依頼に適用するかを書きます。Agent Skillsの仕様でも、両方を記述することが推奨されています。
---
name: doc-answer
description: >
社内資料を検索・取得し、根拠と出典URL付きで回答する。
社内の仕様、手順、設計、決定事項について質問された場合や、
社内ドキュメントの検索・確認を依頼された場合に使う。
compatibility: 社内資料検索用のMCP接続が必要。
metadata:
owner: "情シス 運用課"
---
## 手順
1. 質問から検索語を作る。
2. 接続済みの社内検索ツールの定義を確認する。
3. 定義に合う引数で検索する。
4. 空結果なら、検索語を変えて1回だけ再検索する。
5. 根拠が得られたら、回答と出典URLを返す。
6. 接続失敗・権限不足なら、その旨を伝えて終了する。
保守責任者は、標準の拡張用フィールドであるmetadataに記載できます。compatibilityは環境要件の説明に使えますが、接続や権限を設定する機能ではありません。
2. 必要な道具は、依存関係として明示する
「このSkillには、どのツールが必要か」を明示すると、不足を実行前に検出しやすくなります。
ただし、mcp_requirementsはAgent Skillsの標準フィールドではありません。機械的に検証したい場合は、ホストが解釈する独自の依存定義として設計します。
たとえば、別ファイルreferences/mcp-tools.jsonに書きます。
{
"required": {
"rag": ["knowledge_base_search"]
}
}
これは独自形式です。ホスト側に、このファイルを読み、接続先とツールの存在を確認する実装が必要です。
また、資料検索Skillにチケット作成ツールまで要求する必要はありません。その作業に必要な道具を絞ることで、依存関係を管理しやすくなります。
3. Piは、Skillとツールを段階的に読み込む
Piは起動時にSkillの名前・説明・パスをモデルへ提示し、必要になったときに本文を読み込みます。
MCPツールにも、公開方法を選ぶ仕組みがあります。
| 方法 | 使い方 |
|---|---|
direct |
小さく、頻繁に使うツール群を直接公開 |
deferred |
必要なツールを検索して定義を読み込む |
codemode |
コード内でツールを探索・呼び出す |
Piの標準はcodemodeです。Skill本文もツール定義も、必要に応じて読み込む構成が参考になります。
なお、先ほどの独自依存ファイルの自動処理は、Piの標準機能として確認できたものではありません。採用する場合はExtensionなどで追加します。
4. 宣言と実行制御を組み合わせる
依存定義にツールが書かれていても、それだけで実行を許可しません。
ホストとサーバーで、引数・アクセス権・実行結果を検証します。PiでもMCP呼び出しは共通のツール実行経路を通り、Extensionの確認処理を適用できます。
実装では、次の分担を明確にすると保守しやすくなります。
- Skill：適用条件、作業手順、結果の扱い
- 依存定義：作業に必要なツール
- ホスト／サーバー：接続、権限、検証、実行制御
標準フィールドを使いつつ、独自の依存管理には実行側の実装を用意する。この組み合わせが、再利用しやすいSkillを作るポイントです。