スキル

スキルは、特定の種類の作業に特化した指示と補助ファイルを Pi に提供します。Pi は利用可能な各スキルの名前と説明を提示し、タスクで必要になった場合にのみ完全な指示を読み込みます。

ワークフローにプロンプトテンプレートより多くのコンテキストが必要で、新しい実行可能な統合ポイントまでは必要ない場合に、スキルを使用します。スキルには、指示とともにスクリプト、リファレンス、アセットを含められます。

Pi は Agent Skills 仕様を実装しています。ほとんどの無効なフィールドは、起動を停止させるのではなく警告を生成します。

スキルを作成する#

スキルは、SKILL.md を含むディレクトリです。

pdf-tools/
├── SKILL.md
├── scripts/
│   └── extract.sh
├── references/
│   └── formats.md
└── assets/
    └── template.json

SKILL.md は、フロントマターの後に直接的な指示を記述する形式で作成します。

---
name: pdf-tools
description: Extract text and tables from PDF files. Use when reading, converting, or inspecting PDFs.
---

# PDF tools

Read `references/formats.md` before converting a document. Run scripts relative to this skill directory.

モデルがスキルの読み込みを検討するタイミングは、説明によって決まります。スキルが何をするかと、どのような場合に適用されるかの両方を明記してください。十分なルーティング情報を提供しない「PDF の処理を支援します」のような説明は避けてください。

同梱ファイルを参照する場合は、スキルディレクトリからの相対パスを使用してください。Pi はスキルの場所をモデルに伝えるため、モデルはそれらのパスを解決できます。

スキルの読み込み方法を理解する#

起動時に、Pi は設定済みのスキル配置場所をスキャンし、各スキルの名前、説明、パスをシステムプロンプトに追加します。完全な指示は追加しません。

タスクが一致すると、モデルは SKILL.md を読み、その指示に従います。これにより、必要になるまで詳細なガイダンスがコンテキストに含まれません。モデルが関連するスキルを読み込まない場合があるため、強制的に読み込ませる必要がある場合は /skill:name を使用してください。

/skill:name の後の引数は、ユーザーリクエストとして読み込まれた指示に追加されます。

/skill:pdf-tools extract report.pdf

スキルを明示的なコマンドからのみ利用可能にする場合は、フロントマターに disable-model-invocation: true を設定します。enableSkillCommands 設定は、対話形式のコマンド検出にスキルコマンドを表示するかどうかを制御します。手動で入力した /skill:name コマンドは引き続き機能します。

Pi に追加する#

スキルをユーザーまたはプロジェクトのスキルディレクトリに配置します。SKILL.md を含むディレクトリは再帰的に検出されます。

Pi は Agent Skills の配置場所である ~/.agents/skills/ と .agents/skills/ にも対応しています。プロジェクトの .agents/skills/ ディレクトリは、作業ディレクトリから祖先ディレクトリをたどって検出され、リポジトリルートが存在する場合はそこで停止します。

Pi は一部の単独の Markdown スキルにも対応していますが、SKILL.md を含むディレクトリが移植可能な形式であり、こちらを優先してください。その他の配置場所については、設定および Pi パッケージを参照してください。

プロジェクトスキルは、スクリプトの実行やファイルの変更をモデルに指示できます。プロジェクトを信頼する前に、不明なスキルとその補助ファイルを確認してください。

移植可能なフロントマターを記述する#

Agent Skills 仕様では、次のフィールドが定義されています。

名前には、小文字、数字、ハイフンを使用します。先頭、末尾、または連続するハイフンは使用できません。名前は最大 64 文字、説明は最大 1024 文字です。

宣言された名前が親ディレクトリと異なっていても、Pi は必須要件とはせず、警告も出しません。他の Agent Skills 実装ではこの要件が適用される場合があるため、名前を一致させることが移植性の高い選択肢です。

形式が不正な SKILL.md ファイルと、説明なしで宣言されたスキルは読み込まれません。名前が重複した場合は、最初に検出されたスキルが保持され、警告が生成されます。

スキルを検証して共有する#

スキルを検出できる場所から Pi を実行し、起動時の診断と /skill:name コマンドを確認します。アクティブなセッション中にスキルを編集した後は、/reload を実行してください。

npm または git を通じて 1 つ以上のスキルを配布するには、Pi パッケージを使用します。環境設定はスキル内に保持し、必要なランタイム依存関係はパッケージ内で宣言してください。

例については、Anthropic のスキルコレクションおよび Pi のスキルコレクションを参照してください。