スキルの書き方

スキルは、アシスタントが毎回手順を一から組み立て直す代わりに呼び出せる、名前付きの手順です。メモリは何が事実かをアシスタントに伝えます。ルールはやってはいけないことを伝えます。スキルは、特定の作業をどう進めるかを一歩ずつ伝えます。

このページでは、スキルを書くべき場面、スキルに含める内容、そしてスキルの保存方法と配置方法を説明します。

スキルを書くべき場面

同じパターンが繰り返されていると気づいたら、スキルを使いましょう。目安は「アシスタントが毎回同じ手順をたどり、ときどきどれかを抜かしてしまう」状態です。

• 運用手順。 「StripeのWebhookをローカルで再送する」「シード用フィクスチャを再生成する」「リリース前チェックリストを実行する」
• 独自のワークフロー。 「適切なラベルとレビュアーを付けてドラフトPRを作成する」「バージョンを上げ、タグを付けてプッシュする」
• ドメイン固有の手引き。 「新しい分析イベントを一通り作成する：カラム、型、ダッシュボード」

パターンが1〜2行で済むならメモリで十分です。手順が3ステップを超える場合や、「この順番で行う」という要件がある場合はスキルにします。

ソース

スキルのレコードにはソースの値があり、本文がどこにあるかをPathruleに伝えます。

• manual。 本文はPathrule上で直接作成され、そのまま保存されます。これがデフォルトです。手順をワークスペースで完全に管理したい場合に使います。
• template。 Pathruleが提供するスターター用スキルです。ワークスペースにコピーされ、そこで編集できます。
• github_ref。 外部のGitHub URLを参照するスキルです。信頼できるスキルエコシステムで公開されているスキルに使います。

github_refスキルの場合、ワークスペースにはそのソースから取得した本文のスナップショットが保存され、ワークスペース上では読み取り専用になります。VS Codeでは、代わりにソース側を編集するよう案内されます。

SKILL.mdの構成

スキルは、フロントマターと手順の本文からなる小さなMarkdownファイルです。

---
name: replay-stripe-webhook
description: Replay a Stripe webhook against the local server with the right signing secret and the right idempotency key handling.
---

# Replay a Stripe webhook

Use this when a payment event from production needs to be reproduced locally.

## When to invoke

- A customer reports a missing receipt and you have the event id.
- You are debugging a webhook handler change.

## Procedure

1. Find the event in Stripe Dashboard. Copy its id.
2. Run `stripe events resend evt_xxx --webhook-endpoint we_local`.
3. Watch the local handler. It must accept and process the event without double charging.
4. If the handler returns 5xx, the customer support page is the next stop, not a retry.

## What NOT to do

- Do not replay against production webhooks.
- Do not skip the idempotency key check.

フロントマターにはnameとdescriptionが必須です。その下はすべて、アシスタントが従う本文です。本文は必要に応じて短くも長くもできます。

配置

スキルは、ルールと同じようにワークスペースの1つのパスに置かれます。手順が最も関係するパスに配置してください。Webhook再送のスキルはservices/billing/webhooksに置きます。リリース用のスキルはワークスペースのルートに置きます。ワークスペース内の既存スキルと同じ名前の新しいスキルは拒否されるため、2つ目のコピーを追加するのではなく既存のスキルを更新してください。

アシスタントは、Pathruleがパスごとに提供するコンテキストを通じて（メモリやルールと同じ方法で）、pathrule_get_context経由でスキルを見つけ、pathrule_read_skillで1つのスキルを全文読み込みます。同期時には、スキルを読み込むクライアントのスキルフォルダにもPathruleがスキルを書き出します。たとえばClaude Codeなら.claude/skills、Codexなら.agents/skillsです。

::skill-nameでスキルを明示的に呼び出す

通常は、アシスタントが適切なスキルを自分で選びます。特定のスキルを強制的に使わせたい場合は、プロンプト内の任意の位置に::に続けてスキル名を入力します。たとえば::release-checkや::replay-stripe-webhookです。そのターンでは、アシスタントは指定されたスキルを必ず従うべきワークフローとして扱うため、長い指示を書く必要はありません。Claude CodeとCodexでは、エージェントが動く前にプロンプトフックがこのマーカーを拾います。その他のクライアントでは、アシスタントがMCP経由でコンテキストを要求したときに同じ指示を受け取ります。

この仕組みは安全側に倒れるよう設計されています。

• 名前が複数のスキルに一致する場合は、推測で選ぶことはせず、どのスキルも呼び出しません。
• 名前がどのスキルにも一致しない場合、アシスタントは作業を止め、何かを編集する前にあなたと一緒に解決するよう指示されます。公開されている候補を提案することはできますが、ワークスペースに追加する前にあなたの承認を待ちます。
• button::beforeやstd::vectorのようなコード的な::の使い方は無視されるため、普段のプロンプトが誤って解釈されることはありません。

そのため::skill-nameは、パスに関係なく、チームで決まった手順を現在のターンに手早く取り込む方法になります。

作成の流れ

2つの流れがあり、どちらも同じ結果になります。

• 手動での作成。 VS Codeでは、適切なパスでNew Skill… を使い、SKILL.mdの本文を書きます。ターミナルからはpathrule skill add --path /services/billing/webhooks --name replay-stripe-webhook --description "Replay a Stripe webhook locally"を実行します。--bodyを指定しない場合、CLIがエディタを開きます。
• アシスタントによる作成。 Claude Code（または任意のMCPクライアント）で、ユーザーがアシスタントに「これをスキルにして」と依頼します。アシスタントは小さなスキル作成パターンに従います。意図を把握し、ユーザーにヒアリングし、SKILL.mdの下書きを作り、本文全体を渡してpathrule_write_skillを呼び出します。

確定度の低い場面では、アシスタントは会話の中でスキルの下書きを作り、pathrule_write_skillを呼び出す前に承認を待ちます。そのため保存されるレコードはレビュー済みの下書きであり、バックグラウンドで黙って書き込まれたものではありません。

バージョン管理と同時編集

スキルは、メモリやルールと同様にバージョントークンを持ちます。2人のチームメンバーが同じスキルを編集した場合、互いに上書きするのではなく、きちんと競合として扱われます。VS Codeでの競合時の選択肢はメモリと同じです。

アンチパターン

• 実はメモリであるスキル。 本文が「私たちの仕事の進め方についての事実」であれば、メモリにしてください。
• 実はルールであるスキル。 本文が「Xは絶対にしない」であれば、ルールにしてください。
• 1つで多くをこなしすぎるスキル。 手順に異なる入口が2つあるなら、名前の付いた2つのスキルに分けてください。
• 信頼できない外部スキルの取り込み。 github_refスキルは、アシスタントの指示の中で実行されるコードです。依存関係と同じように扱ってください。

ローカルとCloudでの作成

このページにあるターミナルでのaddの例は、Cloudワークスペース向けです。ローカルモードでは、Local Console、VS Code、またはローカルのMCP経由でエントリを作成・編集します。CLIのナレッジコマンドでは、エントリの一覧表示、読み込み、検索ができます。

次に読むもの

• 事実や決定事項についてはメモリの書き方。
• 制約についてはルールの書き方。
• アシスタントがスキルの書き込みに使うツールについてはMCPツールリファレンス。