初めに

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を作るポイントです。