Pi Agent Skills スキルシステム
Skills(スキル)は自己完結型の能力パッケージであり、AIが必要に応じて専門分野のワークフロー手順やツールスクリプトを読み込めるようにします。
Pi Agentは以下を実装しています:Agent Skills標準。
Skillとは
1つのSkillは、以下を含むSKILL.mdファイルのディレクトリです。
SKILL.mdにはスキルの名前、説明、詳細な使用手順が含まれており、AIは必要なときに自動的に読み取って実行します。
SkillはAIの「専門トレーニングマニュアル」と考えることができます。通常はコンテキスト領域を占有せず、必要なときにのみ読み込まれます。
Skillの動作原理
読み込みプロセス全体は4つのステップに分かれており、中心となる考え方は「まず目次を見て、次に全文を読む」です。
- Pi Agentは起動時にすべてのSkillの場所をスキャンし、名前と説明を抽出します。
- 利用可能なすべてのSkillの説明はXML形式でシステムプロンプトに埋め込まれます。
- ユーザーのタスクが特定のSkillの説明に一致する場合、AIは自動的にreadツールを使用して完全なSKILL.mdを読み込みます。
- AIはSKILL.md内の指示に従って動作し、相対パスを使用してスキルディレクトリ内のスクリプトやリソースを参照します。
注意点として、モデルは必ずしも自発的に読み取るとは限らないため、必要に応じてプロンプトで明確に要求するか、または/skill:名前を強制的に読み込みます。
この設計は「プログレッシブ・ディスクロージャー(漸次的開示)」と呼ばれ、説明のみが常にコンテキスト内にあり、完全な指示が必要に応じて読み込まれます。
Skillのディレクトリ構造
必須なのはSKILL.mdのみで、その他のディレクトリは必要に応じて作成します。
my-skill/
├── SKILL.md # 必需:Frontmatter + 指令
├── scripts/ # 辅助脚本
│ └── process.sh
├── references/ # 详细参考文档(按需加载)
│ └── api-reference.md
└── assets/
└── template.json
SKILL.mdの形式
SKILL.mdはYAML Frontmatterを使用してメタ情報を定義し、その後にMarkdown形式の指示本文が続きます:
例
name: my-skill
description: このスキルが何をするのか、そしていつ使用するのか。説明は具体的かつ明確にしてください。
---
# My Skill
## インストール
初回使用前に実行:
```bash
cd ~/projects/brave-search-skill && npm install
```
## 使用
```bash
bash scripts/process.sh <input>
```
## 参考
[参考ガイド](references/api-reference.md) を参照してください。
スキルディレクトリ内のファイルを参照する場合は、相対パスを使用します。。
Frontmatterフィールド
nameとdescriptionのみ必須で、その他のフィールドは必要に応じて追加します。
| フィールド | 必須 | 説明 |
|---|---|---|
| name | である | 最大64文字、小文字の英字/数字/ハイフンのみ。Pi Agentは名前が親ディレクトリと一致することを要求しません。 |
| description | である | 最大1024文字。スキルの機能と使用タイミングを説明します。これはAIがそのスキルを読み込むかどうかを判断する根拠です。 |
| license | 否 | ライセンス名 |
| compatibility | 否 | 最大500文字、環境要件 |
| metadata | 否 | カスタムキーと値のペア |
| allowed-tools | 否 | 事前承認されたツールのリスト(実験的) |
| disable-model-invocation | 否 | trueに設定すると、Skillはシステムプロンプトから非表示になり、/skill:name でのみ手動で呼び出せます。 |
descriptionはAIがあなたのSkillを読み込むかどうかを決定する重要な根拠です。必ず具体的かつ明確に記述してください。
曖昧なdescriptionは、Skillが不適切なシナリオでトリガーされたり、必要なシナリオで無視されたりする原因になります。
Skillの読み込み場所
Pi Agentはグローバルとプロジェクトの2つのレベルでSkillをスキャンします。場所によって検出ルールが若干異なります。
| 場所 | 適用範囲 | 読み込みルール |
|---|---|---|
| ~/.pi/agent/skills/ | グローバル | ルートディレクトリの.mdファイルとSKILL.mdを含むディレクトリが再帰的に検出されます。 |
| ~/.agents/skills/ | グローバル | SKILL.mdを含むディレクトリのみが再帰的に検出され、ルートディレクトリの.mdファイルは無視されます。 |
| .pi/skills/ | プロジェクト | ルートディレクトリの.mdファイルとSKILL.mdを含むディレクトリが再帰的に検出されます。 |
| .agents/skills/ | プロジェクト | SKILL.mdを含むディレクトリのみが再帰的に検出されます。 |
| Pi Packages | グローバルまたはプロジェクト | skills/ディレクトリまたはpackage.jsonのpi.skillsエントリ |
| CLI | 現在の実行 | --skill パス で明示的に読み込み、繰り返し指定できます。 |
補足:~/.agents/skills/ とプロジェクトの .agents/skills/ では、グループ化されたサブディレクトリ内の有効なFrontmatterを宣言したネストされた.mdファイルも認識されますが、トップレベルでFrontmatterのない.mdは無視されます。
CLIパラメータ--no-skillsスキルの自動検出を無効化できますが、明示的に指定された--skill パスは引き続き読み込まれます。
検証と命名の衝突
Pi AgentはAgent Skills標準に従ってSkillを検証します。ほとんどの問題は警告のみで、Skillは引き続き読み込まれます。
descriptionが欠けているSKILL.mdは読み込まれません。不正な形式のファイルも同様に警告のみで読み込まれません。
同じ名前のSkillが異なる場所から見つかった場合は警告が発行され、最初に検出されたものが保持されます。
Skillコマンド
各Skillは自動的に次のコマンドとして登録されます:/skill:名前コマンド:
/skill:brave-search /skill:pdf-tools extract
コマンド後の引数は、次の形式でUser: 引数Skillの内容に追加されます。
/skill:pdf-tools extract report.pdf を例にとると、展開後の内容はおおよそ次のようになります:
/skill:pdf-tools extract report.pdf User: extract report.pdf
AIはこの内容を受け取ると、SKILL.md内の指示に従ってscripts/ディレクトリ内のスクリプトを探して実行します。
設定によりSkillコマンドの登録を無効化できます:
例
{
"enableSkillCommands": false
}
また、設定のdisable-model-invocationを使用すると、特定のSkillを手動でのみ呼び出し可能にし、システムプロンプトに自動的に表示されないようにできます。
他のツールからSkillをインポート
Pi AgentはClaude CodeまたはOpenAI CodexのSkillsを読み込むことができます:
以下の2つの設定をそれぞれグローバルとプロジェクトのsettings.jsonに書き込みます。パスは実際のディレクトリに合わせて調整してください。
例
{
"skills": [
"~/.claude/skills",
"~/.codex/skills"
]
}
プロジェクトレベルのClaude Code Skillsの場合:
例
{
"skills": ["../.claude/skills"]
}
Skills内の指示は、実行可能ファイルの実行を含む任意の操作をAIに要求できます。
第三者のSkillを使用する前に、その内容を確認することをお勧めします。
完全なSkillの例
以下はWeb検索Skillの完全な例です:
例
name: brave-search
description: Brave Search APIを使用してWeb検索とコンテンツ抽出を行います。ドキュメントの検索、事実の照会、その他あらゆるWebコンテンツの検索に適しています。
---
# Brave Search
## インストール
初回使用前に依存関係をインストール:
```bash
cd ~/projects/brave-search-skill && npm install
```
## 検索
```bash
# nodeで実行、実行権限は不要
node scripts/search.js "検索キーワード" # 基本検索
node scripts/search.js "検索キーワード" --content # ページ内容を含む
# すでに実行権限を付与している場合(chmod +x scripts/search.js)、直接実行することもできます
./scripts/search.js "検索キーワード"
```
## ページ内容の抽出
```bash
node scripts/content.js https://example.com
```
Skillリポジトリのおすすめ
この2つのリポジトリにはすぐに使える Skill が豊富に用意されていますが、インストール前に内容を一読することをお勧めします。
| リポジトリ | 内容の方向性 | 適用シーン |
|---|---|---|
| Anthropic Skills | ドキュメント処理(docx、pdf、pptx、xlsx)、Web開発 | 日常のオフィス文書の一括処理、フロントエンドページ構築 |
| Pi Skills | Web検索、ブラウザ自動化、Google API、音声文字起こし | ネットワークからのデータ取得、自動化操作、マルチメディアの文字起こしが必要なタスク |