Pi Agent Skills スキルシステム

Skills(スキル)は自己完結型の能力パッケージであり、AIが必要に応じて専門分野のワークフロー手順やツールスクリプトを読み込めるようにします。

Pi Agentは以下を実装しています:Agent Skills標準。


Skillとは

1つのSkillは、以下を含むSKILL.mdファイルのディレクトリです。

SKILL.mdにはスキルの名前、説明、詳細な使用手順が含まれており、AIは必要なときに自動的に読み取って実行します。

SkillはAIの「専門トレーニングマニュアル」と考えることができます。通常はコンテキスト領域を占有せず、必要なときにのみ読み込まれます。


Skillの動作原理

読み込みプロセス全体は4つのステップに分かれており、中心となる考え方は「まず目次を見て、次に全文を読む」です。

  1. Pi Agentは起動時にすべてのSkillの場所をスキャンし、名前と説明を抽出します。
  2. 利用可能なすべてのSkillの説明はXML形式でシステムプロンプトに埋め込まれます。
  3. ユーザーのタスクが特定のSkillの説明に一致する場合、AIは自動的にreadツールを使用して完全なSKILL.mdを読み込みます。
  4. 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コマンドの登録を無効化できます:

例

// ファイルパス:~/.pi/agent/settings.json
{
  "enableSkillCommands": false
}

また、設定のdisable-model-invocationを使用すると、特定のSkillを手動でのみ呼び出し可能にし、システムプロンプトに自動的に表示されないようにできます。


他のツールからSkillをインポート

Pi AgentはClaude CodeまたはOpenAI CodexのSkillsを読み込むことができます:

以下の2つの設定をそれぞれグローバルとプロジェクトのsettings.jsonに書き込みます。パスは実際のディレクトリに合わせて調整してください。

例

// ファイルパス:~/.pi/agent/settings.json(グローバルインポート)
{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

プロジェクトレベルのClaude Code Skillsの場合:

例

// ファイルパス:.pi/settings.json(プロジェクトレベルインポート)
{
  "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 SkillsWeb検索、ブラウザ自動化、Google API、音声文字起こしネットワークからのデータ取得、自動化操作、マルチメディアの文字起こしが必要なタスク
その他の拡張