役に立つAgent Skillと「マークダウンのエッセイ」を分ける9つの原則【日本語訳・解説】

本記事は Jack Rusher 氏（The Generative Programmer）が 2026年5月10日に公開した記事 9 Principles That Separate Useful Skills from Markdown Essays を、著者の主張を踏まえて日本語で要約・解説したものです。原文の引用・要点を尊重しつつ、訳者の補足を加えています。詳細な引用・最新情報は原文をご確認ください。

はじめに

Claude Code をはじめとするエージェント型コーディングツールには、Agent Skill（エージェントスキル）という仕組みがあります。「特定のタスクのときだけ追加で読み込まれる、モデルへの指示書き」のような存在です。

ところが実際にスキルを書いてみると、多くの場合は「ただの長いマークダウン文書」になりがちで、肝心な場面で発動しなかったり、ルールが破られたり、運用するうちに陳腐化してしまいます。

Jack Rusher 氏の元記事では、こうした「スキルもどき」と「本当に役に立つスキル」を分ける9つの原則を、3幕構成で整理しています。それぞれの原則を順に見ていきましょう。

全体像：3幕構成の9原則

9つの原則は、スキルが辿るライフサイクルに沿って3つのグループに分けられます。

幕	フェーズ	含まれる原則
第1幕	選ばれる（Getting Selected）	①メタデータがゲート ②段階的に開示する ③散文より「手順」
第2幕	確実に動く（Running Reliably）	④「なぜ」を説明する ⑤言い訳を先回りする ⑥推論よりコード ⑦スコープに留まる
第3幕	現実に晒される（Surviving Contact with Reality）	⑧スキルは劣化する ⑨出荷前に走らせる

「選ばれなければ品質は無意味、選ばれてもプロセスでなければ守られない、出荷前に走らせなければ想像で書いたバグが残る」——著者は最後にこの3つを基礎原則と位置付けています。

第1幕：まず「選ばれる」ためのスキル設計

スキルがどれだけ良い内容でも、起動しなければ何の意味もありません。第1幕の3つはすべて「セッション開始時にClaudeに見つけてもらう」ための原則です。

原則① メタデータがゲート（Metadata is the Gate）

セッション開始時にClaudeが見ているのは、スキルの本文ではなく name と description だけです。つまり、説明文がそのままトリガーになります。

弱い例：「ドキュメント作成を手伝います」
強い例：トリガーとなるキーワード、ドメイン語、そして「ブログ記事には使わないこと」のような除外句まで書き込む

Anthropic の Agent Skills では description の上限が1024文字。発見性と予算のトレードオフがそのまま現れる箇所です。

訳者補足： Claude Code で ~/.claude/skills/ 以下にスキルを置いていると、フロントマターの description がそのまま「いつ呼ばれるか」を決定します。「何をするか」より「いつ呼ぶか」を書く、と覚えると外しません。

原則② 段階的に開示する（Disclose Progressively）

コンテキスト（文脈窓）は有限です。スキルがすでにモデルが知っていることまで毎回ロードしていると、それだけでトークン予算を食い潰します。

著者は3段ロケットのような段階を推奨しています。

起動時 — メタデータだけ
発動時 — スキル本体（手順）
必要時のみ — 参照ファイル・補助スクリプト

「いま要るものだけを、要るときだけロードする」

スクリプトは特に効きます。ソースコードは決してコンテキストに入らず、実行結果だけが入るため、極めて経済的です。

原則③ 散文より「手順」（Process Over Prose）

スキルは「ワークフロー」であって、参考書ではありません。

ジュニアエンジニアが読んで「次に何をやればいいか分からない」なら、それはスキルではなくエッセイです。

良いスキルには次の要素が含まれます。

✅ 実行可能なステップ
✅ チェックポイント（中断・確認の節目）
✅ 終了条件（done の定義）
✅ テンプレ・ひな型

逆に「背景知識の解説」「概念の網羅」を中心に据えたスキルは、結局は守られません。

第2幕：「確実に動く」ための4原則

選ばれた後、スキルがその場で正しく動くために必要な4つの原則です。

原則④ 「なぜ」を説明する（Explain the Why）

ルールには必ず理由を添えるべきです。

理由なしのルール → 機械的に従う or 微妙に外れた場面で誤適用する
理由ありのルール → 未知のケースに対しても「同じ精神で」判断できる

著者は「コンストラクタ・インジェクションを使え」というルールに対し、「テスタビリティのため」と一言添えるだけで、モデルが類似の設計判断にも応用できるようになる例を挙げています。

「ルールはルブリック（採点基準）になる。基準があれば未知の問題にも対応できる」

原則⑤ 言い訳を先回りする（Anticipate the Excuse）

LLM は、「特定の状況ではこのルールを破ってよい」と自分を説得する能力に長けています。

「このマイグレーションは小さいから例外でいい」
「手元で確認したから大丈夫」
「いま急いでいるから次回まとめてやる」

著者の提案は秀逸で、ルールを増やす代わりに「言い訳に対する反論」を表形式でスキル内に書き込むというものです。

「言い訳を先回りせよ。反論はルールの隣に、スキルの中に書け」

しかも、その反論は想像で書かないのが鉄則です。過去の実行ログやインシデント・ポストモーテムから、実際に出た言い訳を吸い上げる方が遥かに効きます。

原則⑥ 推論よりコード（Code Over Inference）

検証・変換・抽出のような決定論的に書ける処理は、推論ではなくスクリプトに任せるべきです。

	推論ベース	スクリプトベース
再現性	揺れる	常に同じ
速度	遅い	速い
コンテキスト消費	大きい	結果だけ
監査性	難しい	コードを読めば分かる

「ステップが決定論的なプログラムに置き換えられるなら、必ずそうすべきだ」

実装は Bash 経由で事前に書かれたスクリプトを叩くだけ。ソースはコンテキストに入らず、stdout だけが流れ込みます。

原則⑦ スコープに留まる（Stay in Scope）

エージェントはタスクが求めた箇所だけを触るべきです。

隣接する命名規則を「ついでに」直す
関係ない依存関係をアップデートする
「目に付いたバグ」を勝手に修正する

これらは一見「親切」に見えますが、レビュアーから見ると「信用できない差分」になります。

「スキルが触れと言った場所だけを触れ」

訳者補足：日本のチーム開発でもこの問題は深刻で、AIに任せたPRが肥大化するとレビュー時間が逆に伸びるという報告は数多くあります。

第3幕：「現実に晒され続ける」ための2原則

書いた直後は完璧でも、時間と環境が経つと壊れていきます。それを前提に設計するのが第3幕です。

原則⑧ スキルは劣化する（Skills Decay）

ライブラリのバージョンが上がる
API の仕様が変わる
チームの規約が変わる

数ヶ月放置されたスキルは、「自信たっぷりに古い情報を引用するエージェント」を生み出します。これは何も書かないより悪い状態です。

著者は次のように対処することを推奨しています。

スキルにオーナーを付ける
現在のタスクで定期的に発動させる（＝使い続ける）
価値を生まなくなったら引退させる

「スキルは凍ったドキュメントではなく、生きた成果物（living artefact）だ」

原則⑨ 出荷前に走らせる（Run Before You Ship）

著者が最も強調するのがこの原則です。

「想像で書いたスキルは、想像で動く」——筆者の目から見て理想的なフロー（言い訳の表、補助スクリプトの一覧、ガード条件）を全部書き込んでも、それが実際のエージェントが遭遇する現実に当たっていない限り、ほとんど無意味です。

良いスキルは観察された実行ログから derive されるべきです。

何度も繰り返される言い訳のパターン
エージェントが独自に書き始める補助スクリプト
毎回ハマる地雷ポイント

これらを観察し、スキル本体に昇格させていくのが、Rusher 氏の言う「現実から derive する」設計です。

「スキルはオーサリング時の想像力ではなく、観察された実行からデバッグせよ」

9原則のシンセシス：3つの土台

著者は最後に、9つを並列に扱うのではなく「3つの土台＋6つの修正パッチ」として位置付けます。

graph TD
    A["土台3原則"] --> A1["① メタデータがゲート"]
    A --> A2["③ 散文より手順"]
    A --> A3["⑨ 出荷前に走らせる"]

    B["修正6原則"] --> B1["② 段階的開示"]
    B --> B2["④ なぜを説明"]
    B --> B3["⑤ 言い訳に先回り"]
    B --> B4["⑥ 推論よりコード"]
    B --> B5["⑦ スコープに留まる"]
    B --> B6["⑧ スキルは劣化する"]

土台が崩れているスキルには、いくら細部のチューニング（修正6原則）を当てても効きません。

① が崩れていれば → そもそも発動しない
③ が崩れていれば → 内容が「読み物」なので守られない
⑨ が崩れていれば → 想像のバグが本番に流れ込む

逆にこの3つさえ押さえていれば、残り6つは「典型的な失敗モードへのパッチ」として後から足すことができます。

訳者所感：日本のClaude Codeユーザーにとっての示唆

Claude Code の日本コミュニティでも、スキル設計のベストプラクティスは急速に整理されつつあります。実際にいくつかスキルを書いた感覚として、Rusher 氏の9原則の中で特に効いたのは以下の3つでした。

③ 散文より手順：箇条書きとチェックポイントに書き直しただけで、エージェントの「途中で諦める率」が体感で半減した
⑤ 言い訳に先回り：実際にエージェントが出してきた「すみません、これは特殊ケースなので…」をそのまま反論として転記すると、次回以降ほとんど発生しなくなった
⑥ 推論よりコード：JSON 整形やコミットメッセージ整形はすべてシェルスクリプトに逃がすのが正解。LLM に整形を頼むと、長期的にトークンと再現性の両方を失う

逆に最初は軽く見ていた⑨ 出荷前に走らせるは、運用してみるとボディーブローのように効いてくる原則です。「これでいけるはず」と書いたスキルが、本番では3割の確率で発動しなかった、という経験が複数回あります。

まとめ

スキルは「メタデータで選ばれ、ワークフローで動き、観察ログで磨かれる」ものとして設計する
3つの土台（①メタデータ ③手順 ⑨実走）を外すと、他の6原則を完璧に守っても救えない
「言い訳の反論」と「決定論的スクリプト」を持ち込むだけで、スキルの寿命は大きく伸びる

Agent Skill は SOLID や KISS のような共通語彙がまだ未成熟な領域ですが、Rusher 氏の9原則は、その共通語彙の最初の有力な候補と言えるでしょう。

原文：9 Principles That Separate Useful Skills from Markdown Essays — The Generative Programmer（Jack Rusher, 2026-05-10）