Claude Code Skillsの書き方 — 使える5つのパターン集

要点

Skillsは .claude/skills/<名前>/SKILL.md にMarkdownを置くだけで、Claude Codeが呼び出せる専門知識パックになります。ただし書き方を間違えると、Skillがあるのに呼ばれない、あるいは呼ばれても効果が出ない状態に陥りがちです。ここでは5つのパターンを、適用条件・実例・アンチパターンの3点セットで紹介します。

パターンごとに「どのfrontmatterを足すと挙動が変わるか」も添えます。型を選ぶ前に、SKILL.mdに書ける項目を押さえておくと選びやすくなります。

型を選ぶ前に知っておきたいSKILL.mdの仕組み

SKILL.mdは、先頭の --- で囲んだYAMLのfrontmatterと、その後ろのMarkdown本文でできています。すべての項目は任意で、推奨されるのは description だけです。name を省くとディレクトリ名がコマンド名になります。

この仕組みの中で、パターン選びに効くのは次の3点です。

• 常にコンテキストに載るのは、基本的にdescriptionだけ。本文は呼び出されたときに初めて読み込まれます。長い参考資料を置いても、使われるまでコストはほぼ発生しません
• 一度読み込まれた本文は会話の中に残り続ける。ファイルは次のターンで読み直されないので、毎回効かせたい指針は「手順」ではなく「常時の指示」として書きます
• frontmatterの項目名は表のとおりに綴る必要がある。allowed-tools を allowed_tools と書くように、認識されない項目は、エラーも出さずに無視されます

呼び出しの主導権は2つの項目で切り替えます。

どちらも指定しなければ、人もClaudeも呼べます。

パターン1: 手順書型(Procedure Skill)

適用条件

• 複数ステップを毎回同じ順序で踏む作業(コードレビュー/議事録の要約/PRの説明文作成/リリース手順等)
• Claudeが "やり方そのもの" を忘れがちな作業

例

---
name: release-notes-writer
description: 新しいバージョンのリリースノートを書くための完全手順
disable-model-invocation: true
---
 
# release-notes-writer
 
## ステップ1: changelog から利用者向けの変更を抜き出す
...
 
## ステップ2: 変更点を種類ごとに分類する
...
 
## ステップ3: 影響範囲を利用形態別に書く
...

デプロイやコミットのように副作用のある手順書は、disable-model-invocation: true を付けて自分で起動する形にします。コードが整って見えただけでClaudeがデプロイを始める事態を避けられます。Claudeがこの種のSkillを自動で呼ぼうとすると、Claude Code側が呼び出しを止め、手順を別の方法で再現しないよう指示します。実行を促すのは /名前 です。

引数を渡したい手順書は、本文に $ARGUMENTS と書けます。/deploy staging のように打てば、staging が本文の該当箇所に入ります。

アンチパターン

• "READMEを書くスキル" のような範囲が広すぎるもの。手順が増えすぎて破綻する
• 分岐が多い作業を1つの手順書に押し込む

パターン2: チェックリスト型(Checklist Skill)

適用条件

• 毎回同じ観点で "評価" したい作業(レビュー・QA・品質判定)
• 漏れを防ぎたい運用作業

例

---
name: pre-commit-check
description: コミット前に必ず確認するチェックリスト
allowed-tools: Read Grep
---
 
## 必須チェック
- [ ] 秘密情報が含まれていない(.env 等)
- [ ] テストが通っている(npm run test)
- [ ] 型エラーゼロ(npm run typecheck)
- [ ] 不要なログ出力が残っていない
- [ ] 1コミット1目的になっている
 
## 推奨チェック
- [ ] コミットメッセージが日本語・プレフィックス準拠
- [ ] 関連 Issue 番号が含まれる

読み取り専用の確認作業なら、allowed-tools で Read や Grep を事前許可しておくと、確認のたびに許可を求められません。この許可は、Skillを呼んだターンの間だけ有効です。次のメッセージを送ると消えます。

アンチパターン

• チェック項目が30を超える(優先度が埋もれる)
• "推奨" と "必須" を区別しない(優先度が伝わらない)

パターン3: 判断基準型(Decision Rubric Skill)

適用条件

• 採点・スコアリング・Go/No-Go判定が必要な作業
• 人によって評価が分かれやすい作業の基準を揃えたい

例

---
name: code-reviewer
description: コードの正確性・可読性・保守性・テスト容易性を 4 観点で採点する
context: fork
agent: Explore
---
 
## 正確性(30点満点)
- 25〜30: 仕様どおりに動き、境界値や異常系も扱えている
- 18〜24: 主要な経路は正しいが、異常系の扱いに抜けがある
- 10〜17: 動くが、仕様との食い違いが複数ある
- 0〜9:  仕様を満たしていない
 
## 可読性(30点満点)
...

採点役は、書いた本人の文脈に引きずられない方が評価がぶれません。context: fork を付けると、Skillの本文を指示として受け取る新しいサブエージェントで実行できます。agent でサブエージェントの種類を選びます。

ただしforkしたサブエージェントは、ここまでの会話履歴を見ません。採点基準は本文だけで完結させます。「さっきの修正をレビューして」のように履歴に頼る書き方は、成立しません。

アンチパターン

• スコアのレンジを書かない("高い/低い" だけ)→ 採点のぶれが消えない
• 失格ライン(これ未満なら即リジェクト)を定めない
• 「このAPI規約に従うこと」のような指針だけを書いて context: fork を付ける。サブエージェントには、実行すべき作業が渡りません

パターン4: パターンカタログ型(Pattern Catalog Skill)

適用条件

• 複数の定型解が選択可能で、"どれを使うか" の判断が必要な作業
• デザインパターン / リファクタパターン / プロンプトパターン等

例

---
name: refactor-patterns
description: よく使うリファクタリングパターン集
---
 
## パターン A: Extract Function
- **適用条件**: 同じ処理が2箇所以上で繰り返されている
- **例**: ユーザー名の正規化処理が auth.ts と profile.ts に重複
- **アンチパターン**: 一箇所しか使われないのに関数化する(YAGNI違反)
 
## パターン B: Parameter Object
- **適用条件**: 関数引数が 4 個以上になった、または関連する引数セット
- **例**: fetchUsers(limit, offset, filter, sortBy) → fetchUsers(options)
- **アンチパターン**: 引数 2 個で object 化する(過剰な抽象化)

カタログは項目が増えやすい型です。500行に近づいたら、詳細を別ファイルに逃がします。Skillのディレクトリには複数のファイルを置けます。

refactor-patterns/
├── SKILL.md       (概要と各ファイルへの案内)
├── patterns-a.md  (必要になったときだけ読まれる)
└── scripts/
    └── check.py   (読み込まれず、実行される)

SKILL.mdには「どのファイルに何があり、いつ読むか」を書いておきます。Claudeはその案内を見て、必要なファイルだけを開きます。

アンチパターン

• 各パターンに名前を付けない(呼び出しづらい)
• アンチパターンを書かない(過剰適用を防げない)

パターン5: 禁則事項型(Guardrail Skill)

適用条件

• 頻繁に間違えるルール / やってはいけない操作 / 規約違反を防ぎたい
• セキュリティ・コンプライアンス観点

例

---
name: database-safety
description: 本番 DB への操作で絶対に守る規則
---
 
## 絶対禁止
- [ ] 本番 DB への直接 SQL(必ずマイグレーション経由)
- [ ] DELETE / UPDATE 文で WHERE 句なし
- [ ] TRUNCATE TABLE
- [ ] DROP TABLE / DROP DATABASE
 
## 警告(ユーザー確認必須)
- [ ] マイグレーション適用前のバックアップ未取得
- [ ] インデックス削除
- [ ] カラム型変更
 
## 推奨
- トランザクション内で動作確認してからコミット

アンチパターン

• 曖昧な表現("注意してください")→ 守られない
• 理由を書かない → 判断に迷った時に外れがち
• 毎回必ず守らせたい規則をSkillの文章だけに頼る

最後の点は、禁則事項型に固有の限界です。Skillの本文は指針としてClaudeに読まれるだけで、規則が毎回効く保証はありません。「WHERE句のないDELETEは1回でも通したくない」という規則は、フックに移す対象です。フックはイベントが起きるたびにClaude Codeが実行するので、Claudeがその時点でSkillに従っているかどうかに左右されません。

規則をSkillの隣に置いておきたいなら、Skillのfrontmatterの hooks にフックを定義できます。そのフックは、Skillが呼ばれてからセッションの終わりまで有効です。設定方法はHooksの入門記事にまとまっています。

使い分け早見表

呼ばれないときの切り分け

Skillを書いたのに使われないときは、原因が3つに分かれます。上から順に潰すと、無駄が出ません。

3つ目まで進んでも直らないなら、frontmatterのYAMLが壊れている可能性があります。壊れていると、本文だけが読み込まれ、メタデータは空になります。/名前 では動くのに、descriptionでの自動選択だけが効かない症状になります。

frontmatterの壊れを機械で見つける

claude plugin validate に skills ディレクトリを渡すと、中のSKILL.mdのfrontmatterがパースできるかを検査できます(v2.1.233以降)。個別のSkillディレクトリを渡すと、No manifest found in directory で失敗します。Claude Code v2.1.287で、閉じ忘れの引用符を含むSKILL.mdを作って試しました。出力は抜粋です。

$ claude plugin validate .claude/skills
 
Validating skill: .claude/skills/bad/SKILL.md
 
✘ Found 1 error:
 
  ❯ frontmatter: YAML frontmatter failed to parse: YAML Parse error: Unexpected character. At runtime this skill loads with empty metadata (all frontmatter fields silently dropped).
 
✘ Validation failed

「実行時にはメタデータが空で読み込まれる」ことが、エラー文に明記されます。壊れていないSKILL.mdでは ✔ Validation passed が返ります。個人用のSkillなら claude plugin validate ~/.claude/skills で同じ検査ができます。同じコマンドに --strict を付けると、警告もエラー扱いになるので、終了コードでCIの合否を決められます。公式のCLIリファレンスには、認識されない項目も失敗扱いになると書かれています。一方、v2.1.287で allowed_tools のような綴り違いの項目を含むSKILL.mdを検査しました。--strict を付けても ✔ Validation passed で終わりました。v2.1.287では、項目名の綴り違いは --strict でも検出されません。表と突き合わせて確かめます。

共通の落とし穴

落とし穴1: descriptionが曖昧で呼ばれない

Claude CodeがSkillを選ぶ手がかりはdescriptionです。

descriptionには長さの上限があります。description と、補足用の when_to_use を合わせたテキストは、Skill一覧の中で1,536文字に切り詰められます。最も重要な使いどころを先頭に置くのはこのためです。

Skillの数が増えると、一覧全体の文字予算も効いてきます。予算はモデルのコンテキストウィンドウの1%で、あふれると、使用頻度の低いSkillから説明文が削られます。名前だけ残った状態になり、Claudeが選ぶための言葉が消えます。/doctor で一覧のコスト見積もりが出ます。

落とし穴2: ファイルが長すぎる

SKILL.mdは500行以下に保つのが目安です。詳細な参考資料は別ファイルに移します(パターン4の構成を参照)。複数の責務が混ざっていたら分割を検討します。

もう1つ見落としやすいのが、会話の圧縮(コンパクション)です。圧縮されると、Claude Codeは呼び出し済みのSkillを、各Skillの冒頭5,000トークンだけ再添付します。再添付されるSkill全体の予算は25,000トークンで、新しく呼んだものから順に埋まります。重要な指示はSKILL.mdの先頭に寄せるのが、この仕様への現実的な備えです。圧縮の後で効きが落ちたら、もう一度Skillを呼べば全文が戻ります。

落とし穴3: プロジェクト特化の情報が不足

汎用的すぎるSkillは既定のClaudeと変わりません。プロジェクト固有の規約・用語・禁則を1つ以上含めると、既定の振る舞いとの差が出ます。

落とし穴4: 更新されない

半年前に書いたSkillを放置すると、現実の規約とずれた指示を出し続けます。

棚卸しには /skill-doctor(v2.1.252以降)が使えます。使われていないSkillを洗い出す機能で、一覧のコストを押し上げているSkillの特定にも役立ちます。機能フラグの取得を省略するセッションでは使えません。

落とし穴5: 同じ名前のSkillが複数ある

同名のSkillがあるときは、置き場所の優先順位で実行されるものが決まります。個人用(~/.claude/skills/)とプロジェクト用(.claude/skills/)に同じ deploy があれば、/deploy は個人用が動きます。エンタープライズ設定のSkillは、個人用よりさらに優先されます。

code-review のような同梱コマンドと同名のSkillを置くと、Skillが同梱コマンドを置き換えます(エイリアスは残ります)。チームで共有するSkillに、よくあるコマンド名を付けると、意図せず上書きが起きます。

まとめ

Skillsは「専門知識の永続化」です。まず、自分のプロジェクトで最も摩擦が大きい箇所に対応するパターンを1〜2個選び、対話で不満が出た箇所を足していくのが現実的な運用です。

Skillsの前段にはプロジェクト全体の規約を書くCLAUDE.md、後段には自動化レイヤのHooksを置くと、設定レイヤが「プロジェクト憲法 → 知識パック → 実行時フック」の3層で整います。