working-with-skills

PostHog スキルの使用

このスキルでは、エージェントが skill-* MCP ツールをうまく使う方法を説明します。コンテキスト、往復回数、ミスを最小限に抑えます。ツールの種類についてまだ詳しくない場合は、まずカタログが掲載されている skills-store スキルを読んでください。このドキュメントでは、_ツールの選び方_と、スキルが大きくなったときに_ワークフローを拡張する方法_について説明します。

運用の原則

1. 段階的な情報開示は必須です。 リストで説明を取得し、get で本文とマニフェストを取得し、file-get でファイルを1つ取得します。念のためにバンドルファイルを事前に読み込むのは避けてください。事前に読み込んだスクリプトはすべて、実際のタスクに使えるコンテキストを無駄にします。
2. 目的を達成できる最小の書き込み方法を選んでください。 対象を絞った edits または file_edits は、本文全体やバンドル全体の置き換えよりも低コストで、安全性が高く、バージョン履歴も明確になります。
3. 読み取りは低コストですが、同時に上書きするのは低コストではありません。 書き込みツールを呼び出す前に、必ず skill-get の新しい version（または直前の書き込みの応答に含まれる version）を取得し、base_version に渡してください。
4. スキルの作成では Agent Skills 仕様 に従ってください。 name はケバブケースにし、説明にはトリガーとなる表現を十分に含め、本文は短く保ち、大きな資料はバンドルファイルにまとめてください。

判断フロー：どのツールを呼び出すべきか？

Need to know what's available?
  └─► skill-list                    (names + descriptions only)

Need to use / inspect a specific skill?
  └─► skill-get                     (body + file manifest, NO file contents)
        └─► skill-file-get          (one file, on demand, only as referenced)

Authoring a brand new skill?
  └─► skill-create                  (body + all initial files in one call)

Editing an existing skill?
  ├─ Body change?
  │    ├─ Substantial rewrite ............. update(body=...)
  │    └─ Surgical tweak .................. update(edits=[{old, new}, ...])
  ├─ Bundled file content change?
  │    └─ update(file_edits=[{path, edits:[...]}, ...])
  ├─ Add / remove / rename a file?
  │    ├─ Add ............................. skill-file-create
  │    ├─ Delete .......................... skill-file-delete
  │    └─ Rename .......................... skill-file-rename
  └─ Wholesale bundle reset (rare!) ....... update(files=[...])  # replaces ALL files

Renaming the skill itself?
  └─► skill-rename                  (keeps versions, files, and owners)

Want a fork as the starting point?
  └─► skill-duplicate               (then update the copy)

Done with a skill entirely?
  └─► skill-archive                 (hides ALL versions; cannot be undone)

1つの段落と1つのスクリプトを変更するために update(body=...) と大規模な files=[...] を使おうとしている場合は、いったん止めてください。これは、より対象を絞った2回の呼び出し（update(edits=[...]) と update(file_edits=[...])）、または edits と file_edits の両方を含む1回の update で対応できます。

取得する前に見つける

posthog:skill-list
{ "search": "fractal" }

「スキルを見つける」には skill-list が適しています。名前と説明だけが返されます。説明を読むことが重要です。本文を取得する前に、適切なスキルを選んでください。search で十分に絞り込めない場合は、検索語を指定せずに一覧を取得して確認します。ただし、候補の本文を手当たり次第に取得しないでください。

skill-get は質問ごとではなく、タスクごとに各スキルにつき1回だけ呼び出してください。本文を作業メモリに保持し、スキルが変更された可能性がある場合（たとえば書き込み時に 409 が発生した場合。「同時実行」の項を参照してください）に限り、再取得してください。

大きなスキルを効率よく読む

本文が長く、バンドルファイルが多い大きなスキルでは、遅延読み込みが特に重要です。

1. skill-get(skill_name=...) を呼び出して、body と files[] マニフェストを読みます。
2. 本文の目次や見出しを確認します。どのファイルがどのタスクに対応するかは、本文に記載されているはずです。そのため、本文は短く保ち、ファイルはパスで参照します。
3. 本文で_現在のタスク_に明示的に指定されている各ファイルについて、skill-file-get(file_path=...) を呼び出します。それ以外はスキップしてください。
4. 本文に「まれなケース Y については scripts/X を参照」とあっても、ケース Y に該当しない場合は scripts/X を取得しないでください。

迷ったときは、取得するファイルを減らしてください。次のターンでいつでも追加のファイルを取得できます。

新しいスキルの作成

本文と初期ファイルを含めて、skill-create を1回だけ呼び出してください。スキルは完成した状態で version: 1 として作成されます。スキルを空の状態で作成してから、skill-file-create を N 回追加で呼び出すのは避けてください。利点がないまま、余分なバージョンと往復が N 回増えることになります。

posthog:skill-create
{
  "name": "my-skill",
  "description": "What it does AND when to use it. Include trigger keywords.",
  "body": "# my-skill\n\n## When to use\n...\n## Workflow\n...",
  "license": "MIT",
  "compatibility": "Requires Python 3.10+",
  "allowed_tools": ["Bash", "Write"],
  "metadata": { "author": "me", "category": "..." },
  "files": [
    { "path": "scripts/foo.py", "content": "...", "content_type": "text/x-python" },
    { "path": "references/primer.md", "content": "...", "content_type": "text/markdown" }
  ]
}

作成時の基本ルール

• description は発見のための入口です。 skill-list が返すのはこれだけです。ユーザーが言いそうなことを含めてトリガーされやすくし、スキルが実行することと実行しないことを正直に示してください。
• name — ケバブケースで、最大 64 文字です。先頭・末尾・連続するハイフンは使えません。仕様バリデーターは、それ以外の形式を拒否します。
• 本文は約 500 行以下にします。 長い前置き、網羅的な SQL、完全なサンプルペイロード、実行可能なコードは、references/、assets/、または scripts/ に置いてください。本文にはそれらをインラインで記載せず、参照先へ案内する役割を持たせます。
• ファイルレイアウトの慣例 — 実行可能なコードは scripts/、説明文やサンプルは references/、テンプレートやデータは assets/ に置きます。マニフェストしか参照できない場合でも、エージェントはこれを手がかりに内容を把握できます。
• allowed_tools には、スキルが使用を求めるツールを列挙します。これは許可ではなく要求です。ファイルからスキルを読み込むハーネスでは、このリストを事前承認済みとして扱います。一方、MCP 経由でスキルを読み込むハーネスは、ユーザーがその許可を承認するまでリストを無視します。 実際に使うツールだけを列挙してください。不要なツールを加えると、要求の範囲が広がります。 宣言されていないツールは事前承認されていません。次にどうするかはハーネスが決定し、ユーザーに確認する、呼び出しを拒否する、またはツールをまったく公開しない場合があります。 リストを独自に適用する製品もあり、その場合はツールを省略すると呼び出しに失敗します。
• 関連するスキルがある場合は、末尾に ## Related skills を付けます。短い箇条書きで `skill-name` を列挙し、それぞれに次へ移る理由を一行で添えてください。そうすることで、あるスキルの呼び出しから次のスキルを見つけやすくなります。 スキルは名前だけで参照してください（パスは記載しません。関連スキルは別の製品に含まれていることがよくあります）。製品内のスキルをすべて列挙するのではなく、実際に次の手順となるものだけを記載してください。

既存のスキルを更新する

最もよくある間違いは、小さな変更に update(body=..., files=[...]) を使うことです。この方法でも機能しますが、スキル全体を往復させるため、バージョン履歴の差分が読みにくくなり、files が不完全だとファイルが失われるおそれがあります。代わりに、変更に必要な最小の操作を使ってください。

必ず最初に読み込み、version を取得する

posthog:skill-get
{ "skill_name": "my-skill" }

返された version を控え、書き込みのたびに base_version として渡します。書き込みが成功すると、レスポンスに新しい version が含まれます。以降の書き込みには、その値を引き継いでください。

本文：全置換と差分編集

本文を再構成する場合は、全置換を使います。

posthog:skill-update
{ "skill_name": "my-skill", "body": "# my-skill\n\nNew body...", "base_version": 7 }

数行を調整する場合は、差分編集を使います（小さな変更ではこちらを推奨します。レビューしやすく、エラーの発生範囲も小さくなります）。

posthog:skill-update
{
  "skill_name": "my-skill",
  "edits": [
    { "old": "Use Pillow for rendering.", "new": "Use Pillow ≥10.0 for rendering." },
    { "old": "## Old section title", "new": "## New section title" }
  ],
  "base_version": 7
}

各 edits[].old は、現在の本文内に完全一致で一度だけ含まれている必要があります。また、1 回の呼び出しで body と edits を同時に指定することはできません。

バンドルファイルの内容を編集する

file_edits は、既存のファイルを 1 つ以上その場で修正します。対象外のファイルは変更せずに引き継がれます。スクリプトのロジックを調整したり、リファレンスドキュメントの誤字を修正したりする場合は、これが適切な操作です。

posthog:skill-update
{
  "skill_name": "my-skill",
  "file_edits": [
    {
      "path": "scripts/foo.py",
      "edits": [{ "old": "ITERATIONS = 100", "new": "ITERATIONS = 250" }]
    },
    {
      "path": "references/primer.md",
      "edits": [{ "old": "## Outdated header", "new": "## Updated header" }]
    }
  ],
  "base_version": 7
}

file_edits でできるのは既存ファイルの修正だけです。ファイルの追加、削除、名前変更はできません。構造を変更する場合は、ファイルごとのツールを使ってください。

1 回の呼び出しで編集を組み合わせる

変更が本文と既存ファイルの両方にまたがる場合は、1 回の skill-update 呼び出しで edits（本文）と file_edits（既存ファイル）を組み合わせて、まとまった 1 つのバージョンとして公開できます。

posthog:skill-update
{
  "skill_name": "my-skill",
  "edits": [{ "old": "## Configuration", "new": "## Setup" }],
  "file_edits": [
    { "path": "scripts/run.py", "edits": [{ "old": "DEBUG = False", "new": "DEBUG = True" }] }
  ],
  "base_version": 7
}

ファイルパスのパラメーター名（推測する前にお読みください）

同じ概念である「バンドル内のファイルのパス」も、リクエスト内でどこを通るかによって名前が異なります。この違いは、記憶を頼りに作業するエージェントがつまずきやすい点です。ルールは次のとおりです。

• file_path — パスがURLの一部である場合（skill-file-get、skill-file-delete）。これらは、パスで指定した1つのファイルを読み取る／削除します。どちらもpathも受け付け、file_pathに正規化するため、マニフェストのキーをそのまま使用できます。
• path — パスが本文フィールドである場合：skill-file-create、files=[{path, content, content_type}]配列、file_edits=[{path, edits}]。
• old_path / new_path — skill-file-renameの本文フィールドです。

覚え方：pathはファイル_オブジェクト_のフィールド名（contentの隣にあります）なので、ファイルオブジェクトを含むものではpathを使います。URLでファイルを指定する2つのツールではfile_pathを使います。迷ったときは推測せず、ツールの入力スキーマを確認してください。

ファイルの追加、削除、名前変更

それぞれ個別の呼び出しで行い、毎回新しいバージョンが公開されます。

posthog:skill-file-create
{ "skill_name": "my-skill", "path": "scripts/julia.py", "content": "...", "base_version": 7 }

posthog:skill-file-delete
{ "skill_name": "my-skill", "file_path": "scripts/old.py", "base_version": 8 }

posthog:skill-file-rename
{ "skill_name": "my-skill", "old_path": "scripts/julia.py", "new_path": "scripts/julia_set.py", "base_version": 9 }

skill-file-renameは実際の移動です。既存の内容を再送信せずに引き継ぎます。内容が変わらない場合は、削除してから作成するのではなく、必ずこちらを優先してください。

update(files=[...])を使う場合（まれ）

filesをskill-updateに渡すと、バンドル全体が置き換えられます。配列に含まれないものはすべて削除されます。この方法が適切なのは、バンドルを意図的に一掃して再登録する場合（たとえば、新しいローカルのSKILL.mdツリーをインポートする場合）に限られます。それ以外のほとんどのケースでは、ファイルごとのCRUDとfile_editsを優先してください。

複数ファイルで構成される大規模なスキルの操作

ファイル数の多いスキル（10個以上）では、より慎重な対応が必要です。

• マニフェストをインデックスとして扱ってください。 skill-getのfiles[]がファイル一覧です。各タスクの手順を1つのファイルに対応付け、そのファイルだけを取得してください。
• 構造の変更は分岐させず、順番に行ってください。 3つのファイル名を変更する場合は、rename → rename → renameのように順番に実行し、各操作を直前の応答のversionにつなげてください。そうすれば、巨大なupdate(files=[...])の塊ではなく、確認しやすい小さなバージョンを3つ作成できます。
• 編集範囲を限定してください。 5つのファイルを対象とするfile_editsを使った単一のskill-updateは問題ありません。10個のファイル本文をすべて含む単一のupdate(files=[...])は、ほぼ間違いなくfile_editsを使うべきケースです。
• まず本文自体をリファクタリングしてください。 本文が約500行を超えている場合は、通常、内容を新しいバンドルファイルに分割してから、さらに情報を追加するのが適切です。

同時実行：base_version

すべての書き込みツールはbase_versionを受け付けます。必ず渡してください。

• サーバーはbase_versionを最新バージョンと比較します。一致すれば書き込みは成功し、新しいバージョンはbase_version + 1になります。
• 一致しない場合、書き込みは拒否されます（別のユーザーがスキルを更新しました）。skill-getを再実行し、新しい本文に対して変更を調整したうえで、最新のversionを指定して再試行してください。
• 書き込みが成功すると、応答に新しいversionが含まれます。それを次の編集につなげてください。自分で連続して行う書き込みの間に、再度getする必要はありません。

base_versionを省略しても処理が速くなるわけではありません。単に「別のユーザーが更新した」という明確なエラーが、その人の変更を気付かないまま上書きする事態に変わるだけです。

よくある落とし穴

• 検索せずに skill-list を呼び出し、その後すべての本文を取得する — 段階的な開示の意味がなくなります。まず説明を読んでください。
• skill-get の後に同梱ファイルをすべて事前取得する — 内側の階層でも同じ間違いです。本文の指示に従い、必要に応じて取得してください。
• 1 行の修正に update(body=..., files=[...]) を使う — スキル全体を往復させるため、差分が読みにくくなり、ファイルを削除してしまうリスクもあります。edits / file_edits を使ってください。
• ファイルを 1 つ追加するつもりで update(files=[...]) を使う — 指定しなかったファイルがすべて削除されます。代わりに skill-file-create を使ってください。
• 名前の変更ではなく、削除して作成する — コンテンツの履歴が失われ、余分なバージョン更新も発生します。
• 連続した書き込みの後に古い base_version を使う — 最初の get ではなく、直前の書き込みに対するレスポンスから version を読み取ってください。
• base_version を省略する — 気づかないまま上書きされます。get を実行した後は、必ず指定してください。
• description が空、または曖昧 — skill-list の検索で実質的に見つけられなくなります。説明はトリガーの契約として扱ってください。
• 長い本文に同梱ファイルがない — 本文が約 500 行を超えたら、そのまま長くするのではなく、references/ と scripts/ に分割してください。
• 1 回の update 呼び出しで body と edits を混在させる — これらは相互に排他的です。どちらか一方を選んでください。
• path と file_path を推測する — file-get と file-delete は file_path（URL 内にあります）を受け取ります。create、rename（old_path/new_path）、files、file_edits は path（本文フィールド）を受け取ります。上記の「ファイルパスのパラメーター名」を参照してください。

スキルのアーカイブ

skill-archive は、名前が一致するスキルのすべての有効なバージョンを非表示にします。バージョン単位ではなく、元に戻すことはできません。チーム全体の skill-list と skill-get からスキルが表示されなくなります。

posthog:skill-archive
{ "skill_name": "my-skill" }

アーカイブする前に、内容を確認またはコピーする必要がある場合は、skill-get でスキルを取得してください。スキル全体を廃止する場合はアーカイブが適切です。同梱ファイルを 1 つ削除するには skill-file-delete を使い、コンテンツをロールバックするにはアーカイブではなく、新しいバージョンを公開してください。

ローカルの SKILL.md ツリーを PostHog に移行する

ローカルのスキルフォルダー（例：my-skill/SKILL.md と scripts/、references/、assets/）を移行する場合：

1. ローカルの SKILL.md を読みます。フロントマターは name、description、 license、compatibility、allowed_tools、metadata に対応します。フロントマター以降の本文は body になります。
2. 同梱サブディレクトリを走査し、すべてのファイルを { path, content, content_type } として収集します。
3. すべてをまとめて posthog:skill-create を 1 回呼び出します。スキルは 完成した version: 1 として作成されます。create と N 回の file-create 呼び出しに分割しないでください。

作成後、スキルは skill-get を通じて全員が利用できます。

パターン：スキルの用途

ストア内のスキルは、書き込み権限のあるエージェントが更新できる、共有のバージョン管理されたメモリです。 そのため、手順書以外にもさまざまな用途があります。セッションをまたいでエージェントが保守するプロジェクトハブ、チームが所有する PostHog オブジェクトのカタログ、調査のたびに充実するランブック、毎日の「自分が対応すべきこと」キュー、あるいはチームメイトのエージェントが直接読み込める引き継ぎ資料などに活用できます。

references/skill-patterns.md には、ファイル構成、保守の契約、各パターンの出発点とともに、こうした形の例がまとめられています。 ユーザーからスキルの用途を尋ねられたときや、エージェントが長期にわたって保守するスキルを作成する前に読んでください。

スキルが適切でない場合

永続化したいプロンプトがすべてスキルストアに適しているわけではありません。

• 1 回限りのタスク指示はスキルではなく、会話内に記載します。
• 個人的なメモは、エージェントのメモリまたはローカルファイルに保存します。
• コードはスキルではありません。サービスが実行するものであれば、リポジトリに置きます。

優れたスキルとは、再利用可能で、説明から見つけられ、正確な状態を保ち続けるコストに見合うものです。