Claude CodeやCodexを使っていると、同じ指示を何度も繰り返す場面があります。

「変更後は必ずこのテストを実行する」「この種類の障害では先にログを確認する」「PRを作る前にこの項目を確認する」といった手順が安定してきたら、毎回プロンプトへ書くよりSkillとして残した方が再利用しやすくなります。

ただし、SKILL.mdへ知識を大量に詰め込めばよいわけではありません。ClaudeとCodexの公式ガイド、GitHubで広く参照されているSkill、Agent Skillsを評価した研究を見比べると、効果的なSkillにはかなり共通した設計があります。

この記事では先に、そのまま真似できる形を示します。理由や研究結果は後半で説明するので、まずSkillを作りたい場合は最初のテンプレートと10項目だけでも使えます。

まずはこの形から作ればよい

最初から複雑なSkillを作る必要はありません。迷ったら、次の骨格から始めると整理しやすくなります。

---
name: reviewing-api-changes
description: APIの変更をレビューし、互換性、入力検証、テストを確認する。APIエンドポイント、Route Handler、Controllerなどの変更をレビューするときに使う。
---

# Reviewing API Changes

## Preconditions

- 変更対象のAPIと利用側を確認する
- プロジェクトのテスト方法を確認する

## Steps

1. 変更された入力と出力を確認する
2. 既存クライアントとの互換性を確認する
3. エラー処理と入力検証を確認する
4. 関連するテストを確認・追加する
5. 実行可能な検証コマンドを実行する

## Common Failure Modes

- 型だけを見て実際のレスポンスを確認しない
- 正常系だけ確認してエラー系を見落とす
- 既存クライアントへの影響を確認しない

## If A Failure Happens

- 失敗したテストと変更箇所の関係を確認する
- 原因が不明な場合は変更範囲を狭めて再現する
- テストを削除・無効化して成功扱いにしない

## Verify

- 関連テストが成功する
- ビルドまたは型チェックが成功する
- 変更したAPIを実際に呼び出して期待する結果を確認する

この見出し名がAgent Skillsの必須仕様というわけではありません。基本となるのはnamedescriptionを持つSKILL.mdで、本文はSkillの目的に合わせて設計できます。

重要なのは、いつ使うか、何をするか、失敗しやすいところはどこか、最後に何をもって完了とするかが分かることです。

効果的なSkillを作る10のポイント

先に結論をまとめると、次の10項目を確認すれば十分に実用的なSkillを作り始められます。

  1. 一つのSkillに一つの仕事を持たせる
  2. descriptionに「何をするか」と「いつ使うか」を書く
  3. 誤発火しやすいSkillでは「使わない条件」も明確にする
  4. 知識集ではなく、実行できる手順を書く
  5. 必要な前提条件を先に確認する
  6. よくある失敗をSkillに残す
  7. 失敗したときの戻り方を書く
  8. 最後に検証方法を定義する
  9. 長い資料や決定論的な処理を別ファイルへ分ける
  10. 実際のタスクで試し、似たSkillを増やしすぎない

1. 一つのSkillに一つの仕事を持たせる

Skillを便利にしようとして、レビュー、実装、テスト、リリース、障害対応まで一つにまとめると、いつ使うSkillなのかが曖昧になります。

たとえば次のような名前は範囲が広すぎます。

software-development
project-helper
coding-tools

それよりも、実際の作業単位へ寄せます。

reviewing-api-changes
diagnosing-production-errors
preparing-release-notes
checking-database-migrations

Skillを小さくする目的はファイル数を増やすことではなく、「この状況ならこのSkillを使う」という境界を明確にすることです。

OpenAIのSkills解説でも、最初のSkillとして繰り返し行う具体的な仕事を選び、ワークフローとして残す考え方が示されています。

2. descriptionに「何をするか」と「いつ使うか」を書く

descriptionは単なる説明文ではありません。

Claudeでは、起動時にSkillのnamedescriptionが読み込まれ、関連すると判断されたときにSKILL.md本文が読み込まれます。OpenAIのSkillsでも、名前と説明はSkillが関連する場面を認識するための情報として扱われます。

そのため、次のようなdescriptionでは情報が足りません。

description: APIレビューを支援する。

何を確認し、どの場面で使うのかまで書きます。

description: APIの変更をレビューし、互換性、入力検証、エラー処理、テストを確認する。APIエンドポイント、Route Handler、Controllerの変更をレビューするときに使う。

Anthropicの公式ガイドでも、descriptionには「何をするSkillか」と「いつ使うか」の両方を書くことが明示されています。

3. 誤発火しやすいSkillでは「使わない条件」も明確にする

Skillの範囲が近い場合は、正しい用途を書くことだけでは境界が曖昧になることがあります。

たとえばパフォーマンス調査用Skillなら、次のように対象外を補足できます。

## Scope

Use this skill when:
- APIの応答時間が悪化している
- 特定処理のボトルネックを計測したい

Do not use this skill when:
- 障害の再現自体ができていない
- セキュリティインシデントの調査が主目的

すべてのSkillへDo not use節を追加する必要はありません。レビュー用Skillと実装用Skill、通常のデバッグとセキュリティ調査など、似たSkill同士が競合しそうな場合に有効です。

4. 知識集ではなく、実行できる手順を書く

Skillは参考知識を渡すためにも使えますが、実務では行動を再現する手順書として設計すると扱いやすくなります。

たとえば次の説明だけでは、Agentが何をすべきかは決まりません。

Reactでは不要なEffectを避けることが重要です。
依存配列にも注意してください。

レビュー手順へ変えると実行しやすくなります。

## Steps

1. 変更されたEffectを一覧にする
2. 外部システムとの同期に必要なEffectか確認する
3. 派生値をEffectで保持していないか確認する
4. cleanupが必要な副作用を確認する
5. lintと関連テストを実行する

OpenAIはSkillを「再利用可能なワークフロー」と説明しており、Anthropicも明確な手順と、必要に応じて追加資料やスクリプトへ分ける設計を推奨しています。

Skillの価値は、長い説明を読ませることよりも、毎回ばらついていた作業順序や判断を再利用できる形にすることにあります。

5. 必要な前提条件を先に確認する

手順が正しくても、開始条件が満たされていなければ失敗します。

たとえばデータベース移行なら、バックアップ、接続先、対象環境、利用可能なコマンドを確認せずに作業を始めるべきではありません。

## Preconditions

- 対象環境がdevelopment / staging / productionのどれか確認する
- 現在のmigration状態を確認する
- バックアップまたはrollback手段があることを確認する
- プロジェクトで指定されたmigrationコマンドを確認する

前提条件はすべてのSkillに必要な固定セクションではありません。ただし、環境や入力の違いで手順が変わる作業、失敗時の影響が大きい作業では、最初に確認させるだけで事故を減らしやすくなります。

6. よくある失敗をSkillに残す

Skillを一度作って終わりにするのではなく、実際に使ったときの失敗を戻していくと価値が上がります。

たとえばレビューSkillで何度も「型チェックが通ったため実行確認を省略する」という失敗が起きるなら、次のように明記できます。

## Common Failure Modes

- 型チェック成功だけで動作確認済みと判断しない
- 失敗したテストを削除して成功扱いにしない
- 正常系だけでなくエラー系も確認する

これは禁止事項を増やすこと自体が目的ではありません。Agentが実際に迷った場所、間違えた場所だけを残します。

GitHubで広く参照されているMatt Pocock氏のdiagnosing-bugsも、単なるデバッグ知識集ではありません。まず再現可能なフィードバックループを作り、再現・最小化、仮説、計測、修正、回帰テスト、cleanupへ進む具体的なフェーズを持っています。

7. 失敗したときの戻り方を書く

「この方法を使え」と書くだけでは、想定外の状態になったときにAgentが独自の迂回路を作り始めることがあります。

そこで、よく起きる失敗には復帰方法も用意します。

## If A Failure Happens

- テストが失敗したら、最初に失敗したテストを個別実行する
- 再現しない場合は、環境・入力・乱数・時刻依存を確認する
- 原因が特定できない状態で修正を重ねない
- 変更を増やす前に、再現条件を最小化する

重要なのは、あらゆるエラーを網羅することではありません。

「失敗したら別案を考える」ではなく、次に観測するもの、戻る地点、やってはいけない回避策を決めておくと、Skillが実務的なガードレールになります。

8. 最後に検証方法を定義する

Agentがファイルを変更したことと、作業が成功したことは別です。

## Verify

- `pnpm test`が成功する
- `pnpm build`が成功する
- 変更した機能を実際に実行する
- 変更前に再現した問題が再現しないことを確認する

ここで大切なのは、すべてのSkillへ同じtestbuildを書くことではありません。そのSkillが「完了した」と言える証拠を定義することです。

これはコードを扱うSkillだけの話でもありません。

たとえば「Webサイトを白黒2色刷りのようなモノトーン表現へ変更するSkill」を作るとします。「モノトーンにする」だけでは、単純なグレースケール、白黒2値化、デュオトーン、ディザリング、漫画のスクリーントーンのような網点表現など、実装方法が複数あります。

誰がSkillを実行しても同じ方向へ収束させたいなら、成果物の条件まで定義します。

## Output Requirements

- 使用する実色は白と黒の2色を基本とする
- グレーのベタ塗りで中間階調を表現しない
- 中間階調は網点・ハーフトーン・パターンで疑似表現する
- 写真も同じ表現規則へ変換する
- UIの情報階層は色ではなく、密度・線・余白・パターンで維持する

## Verify

- 意図しないカラーが残っていない
- 中間階調が指定した表現規則になっている
- テキストと背景の判読性が維持されている
- hover / focus / disabledを色なしでも識別できる
- 異なるページでも同じ表現規則が適用されている

この場合、pnpm buildが成功してもデザインSkillとして成功とは限りません。あるページだけグレーが残る、写真だけ普通のグレースケールになる、hover時だけ青くなる、といった状態なら再現性がありません。

つまり検証とは、コードが動くかだけではなく、Skillが意図した成果物を再現できたかを確認する工程です。

良いSkillを「誰が実行しても必ず同じピクセルになるもの」と考える必要はありません。ただし、同じ条件なら同程度の成果へ導けるよう、判断基準と成功条件を持たせることは重要です。

約27万Starsを持つobra/superpowersには、verification-before-completionという独立したSkillがあります。内容は、完了を宣言する前に「何が証拠になるかを特定する → 実行する → 出力を読む → 結果を確認する」というゲートを設けるものです。

StarsはSkillの品質を保証する指標ではありません。それでも、広く参照されている実装が「作業手順」だけでなく「完了前の検証」を独立したSkillとして扱っている点は参考になります。

9. 長い資料や決定論的な処理を別ファイルへ分ける

SKILL.mdへすべてを書き込む必要はありません。

Claudeでは、metadata、SKILL.md本文、追加リソースという段階的な読み込みが公式ドキュメントで説明されています。長い資料を本文へ詰め込むより、目的別に分離した方が扱いやすくなります。

reviewing-api-changes/
├── SKILL.md
├── references/
│   ├── api-conventions.md
│   └── error-response-rules.md
└── scripts/
    └── check-openapi.sh

分け方の目安は単純です。

  • 毎回守る作業手順SKILL.md
  • 必要なときだけ読む長い資料references/
  • 同じ入力なら同じ結果にしたい処理scripts/
  • テンプレートなど成果物の材料assets/

Anthropicの公式ガイドでは、スクリプトを決定論的な処理へ使うことや、追加資料を必要時だけ参照するprogressive disclosureが説明されています。

10. 実際のタスクで試し、似たSkillを増やしすぎない

SkillはMarkdownなので、書いた時点では正しそうに見えます。しかし本当に重要なのは、Agentが必要な場面で発火し、期待する作業を行い、不要な場面では邪魔をしないかです。

最低限、次のようなテストをすると改善しやすくなります。

発火してほしい例
- 「このAPI変更をレビューして」
- 「Route Handlerの互換性を確認して」

発火してほしくない例
- 「このUIの余白を調整して」
- 「READMEの文章を修正して」

実行品質
- 必要な確認項目を通るか
- Verifyまで実行するか
- 失敗時に勝手な回避策を取らないか

Anthropic公式のskill-creatorも、Skillを作成したあとにテストプロンプトを用意し、Skillありとベースラインを比較し、評価結果をもとに書き直す反復フローを採用しています。

つまりSkill作成は、「上手なMarkdownを書く作業」よりも小さなソフトウェア開発に近づいています。

また、Skillを細かく分けることと、似たSkillを大量に作ることは別です。

react-review
react-code-review
review-react-code
react-reviewing
frontend-react-review

のような重複を増やすより、それぞれの役割の境界を整理した方が、Agentにとっても人間にとっても扱いやすくなります。

ClaudeとOpenAIの公式ガイドはかなり同じ方向を向いている

ここまでの10項目は、特定の製品だけに合わせたものではありません。

OpenAIはSkillsを、繰り返し作業のための再利用可能なワークフローとして説明しています。SKILL.mdには、何をするか、必要な入力、手順、出力形式、完了前のチェックなどを持たせる形が紹介されています。

Anthropicも、namedescriptionでSkillを発見し、必要になったときだけ本文や追加リソースを読み込む構造を採っています。公式のauthoring guideでは、簡潔さ、明確なワークフロー、実利用によるテストが重視されています。

細部は異なりますが、共通しているのはSkillを巨大な知識ベースではなく、発火条件を持つ再利用可能なワークフローとして扱っていることです。

人気のSkillを見ると「手順」と「検証」が強い

公式ガイドだけでなく、GitHubで広く参照されているSkillも見てみます。

2026年8月17日時点では、obra/superpowersが約27.3万Stars、mattpocock/skillsが約22.0万Stars、Anthropic公式のanthropics/skillsが約17.0万Starsです。

Starsは性能比較ではありません。ここでは「多くの人から参照されている実装を観察する」ための目安として使います。

実際の中身を見ると、共通して目立つのは大量の一般知識ではなく、行動の流れです。

Matt Pocock氏のdiagnosing-bugsは、

フィードバックループを作る

再現・最小化

複数の仮説を作る

計測する

修正と回帰テスト

cleanup

というデバッグの進め方を固定します。

Superpowersも、brainstorming、計画、TDD、code review、verificationなどを別々のSkillとして持ち、それぞれの工程で何をするかを明確にしています。

Anthropic公式のskill-creatorはさらに、Skill自体を「作って終わり」にせず、テストケース、ベースライン比較、評価、書き直しという改善サイクルを持っています。

ここから分かるのは、広く参照されるSkillも、モデルへ百科事典を追加するより、作業の進め方とフィードバックループを与える方向に寄っていることです。

研究でも「Skillを書けば必ず良くなる」とは出ていない

ここで研究側を見ると、少し重要な注意点があります。

Agent Skillsを評価するSkillsBenchの2026年6月版では、87タスクを18のモデル・ハーネス構成で比較し、人間がキュレーションしたSkillによって平均pass rateが33.9%から50.5%へ、16.6ポイント上がったと報告しています。

一方で、効果は構成によって+4.1〜+25.7ポイントと幅があります。また、3モジュール以下のFocused Skillが、大きく網羅的なbundleより良い結果を出しています。

つまり、

Skillという形式を使えば自動的にAgentが賢くなる

という話ではありません。

重要なのはSkillの内容と、対象タスクに対して本当に必要な手順になっているかです。むしろ「全部書く」より、必要な手順を絞る方が良い可能性があります。

別の研究Counterfactual Trace Auditing of LLM Agent Skillsは、Skillあり・なしの実行軌跡を比較し、SkillがAgentの行動をどう変えたのかを分析しています。

49のソフトウェアエンジニアリングタスクでは、pass rateの平均差が+0.3ポイントにとどまる一方、同じpaired tracesから522件のSkill Influence Patternが検出されました。最終的な成功率だけでは見えにくい、literal template copying、off-task artifact creation、excess planning、task recoveryなどの行動変化が観測されています。

ここから分かるのは、Skillの評価を「テストが通ったか」だけで終わらせると、良い影響も悪い影響も見落とすことがある点です。

  • 必要な手順を補えたのか
  • 見落としやすい条件を拾えたのか
  • 逆にSkillの表現へ引っ張られたのか
  • 不要な探索やplanningを増やしていないか

といった実行過程まで見ると、Skillを改善しやすくなります。

これまでのSkill作成と研究で「同じ点」

公式ガイド、人気OSS、研究を並べると、同じ方向を向いている部分はかなり明確です。

Skillは知識量より手順が重要

公式は再利用可能なworkflowを重視し、人気Skillも実際の作業順序を強く規定しています。研究でも、Focused Skillが大きく網羅的なbundleを上回る結果が報告されています。

発火条件が重要

Skill本文が優れていても、必要なときに選ばれなければ使われません。ClaudeはdescriptionをSkill発見の重要な手掛かりとしており、実際のSkill作成でもdescriptionの精度は重要です。

検証とフィードバックループが重要

人気Skillにはテスト、再現、検証のgateが多く、公式のauthoring guideも実利用でのテストを勧めています。研究でも、Skillあり・なしをpaired evaluationで比較しています。

ここは「研究によって突然新しい作り方が発見された」というより、現場で蓄積されてきた設計が、研究でも評価対象として整理され始めたと見る方が自然です。

研究を見ると、これまでより明確になる点

一方で、研究を読むことで実務の経験則より一歩進めて考えやすくなる部分もあります。

「Skillあり」と「Skillなし」を比べる

Skillを作った本人が出力を見ると、書いた内容が反映されているだけで良くなったように感じやすくなります。

しかし必要なのは、

同じタスク
├─ Skillなし
└─ Skillあり

を比べることです。

SkillsBenchもこのpaired evaluationを中心に置いています。Anthropic公式skill-creatorでも、Skillありとbaselineを比較する流れが採用されています。

成功率だけでなく、どこで行動が変わったかを見る

テストが通ったかだけでは、Skillが役立った理由は分かりません。

探索が減ったのか
手順の抜けが減ったのか
edge caseを拾えたのか
逆に余計な探索が増えたのか

まで見ると、次の改善点が見えます。

Counterfactual Trace Auditingは、最終pass rateがほぼ変わらなくても、Agentの行動が大きく変化するケースがあることを示しています。

失敗した実行もSkill改善の材料になる

成功例だけをテンプレート化するより、実際に起きた失敗から、

Common Failure Modes
If A Failure Happens
Verify

を更新する方が、次回の実行で同じ失敗を防ぎやすくなります。

ただし、失敗事例を無制限に追記するとSkillが巨大化します。何度も起きる失敗、影響の大きい失敗、Agentが自力では避けにくい失敗に絞るのが実用的です。

最後に使えるSKILL.mdテンプレート

ここまでの内容を一つにまとめると、次の形から始められます。

---
name: your-skill-name
description: 何をするSkillか。どんなタスク・言葉・状況で使うか。
---

# Your Skill Name

## Goal

このSkillで達成することを1〜3文で書く。

## Preconditions

- 実行前に確認すべき入力
- 必要な権限・環境・依存関係
- 既存ルールや関連ファイル

## Steps

1. 最初に何を確認するか
2. 何を実行するか
3. どの結果を見て次へ進むか
4. 最後に何を検証するか

## Common Failure Modes

- よくある誤り
- やってはいけない回避策
- 見落としやすいedge case

## If A Failure Happens

- 最初に確認するもの
- どこまで戻るか
- 再現できない場合の対応

## Verify

- 成功を証明するコマンド
- 成功を証明する出力・状態
- 成果物が満たすべき条件
- 実際の機能・見た目・操作の確認

必要になったら、次のように拡張します。

your-skill-name/
├── SKILL.md
├── references/
│   └── detailed-rules.md
├── scripts/
│   └── verify.sh
└── assets/
    └── template.md

最初からこのすべてを用意する必要はありません。

まずSKILL.mdだけで実際の作業に使い、同じ説明が長くなったらreferences/へ、毎回同じ処理を確実に行いたくなったらscripts/へ分ければ十分です。

まとめ

効果的なSkillを作るうえで、最初に考えるべきことは「AIへどれだけ知識を追加できるか」ではありません。

重要なのは、繰り返したい仕事を小さく切り出し、発火条件を明確にし、実行手順と検証方法を再利用可能にすることです。

迷ったら、まず次の4つだけでも書けます。

いつ使う?

何をする?

失敗したらどう戻る?

何を確認したら完了?

ここでいう「完了」は、テストが通ったという意味だけではありません。デザインSkillなら意図した見た目が再現されているか、文章生成Skillなら必要な構成や表記ルールを満たしているかなど、その仕事に合った成功条件をSkill自身に持たせることが重要です。

そこから実際に使い、失敗した場所だけをCommon Failure Modesへ戻し、必要になった資料や処理を別ファイルへ分けていけば、Skillは少しずつ自分の開発フローに合っていきます。

Skillは長い知識集ではなく、Agentが繰り返し実行し、結果を検証できる小さな作業手順として作る。

最初の一つは、それくらい単純に考えて問題ありません。