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

要点

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

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

適用条件

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

例

---
name: release-notes-writer
description: 新しいバージョンのリリースノートを書くための完全手順
---
 
# release-notes-writer
 
## ステップ1: changelog の該当バージョンを読む
...
 
## ステップ2: 変更点を3つの観点に分類する
...
 
## ステップ3: 独自視点セクションを加える
...

アンチパターン

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

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

適用条件

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

例

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

アンチパターン

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

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

適用条件

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

例

---
name: article-quality-judge
description: 記事の独自性・正確性・読みやすさ・SEO を 4 観点で採点する
---
 
## 独自性(30点満点)
- 25〜30: 空白領域を中心に据え、独自フレームワークが含まれる
- 18〜24: 独自の切り口はあるが既存記事と重なる部分が過半
- 10〜17: 公式情報の要約 + 簡単な補足程度
- 0〜9:  翻訳に近い
 
## 正確性(30点満点)
...

アンチパターン

• スコアのレンジを書かない("高い/低い" だけ)→ 採点のぶれが消えない
• 失格ライン(これ未満なら即リジェクト)を定めない

パターン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 化する(過剰な抽象化)

アンチパターン

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

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

適用条件

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

例

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

アンチパターン

• 曖昧な表現("注意してください")→ 守られない
• 理由を書かない → 判断に迷った時に外れがち

使い分け早見表

共通の落とし穴

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

Skillsはdescriptionの内容でClaude Codeに認識されます。抽象的なdescriptionは呼ばれにくい傾向があります。

• BAD: "コードをレビューする"
• GOOD: "変更差分をmust(修正必須) / want(推奨) / 事業観点の3つに分類して構造化Markdownで返す"

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

1 Skill 500行を超えると、後半のルールが軽視されやすい傾向があります。複数の責務が混ざっていたら分割を検討します。

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

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

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

半年前に書いたSkillを放置すると、現実の規約とずれてClaudeが混乱します。月1回の棚卸しを推奨。

まとめ

Skillsは「専門知識の永続化」です。5つのパターンのうち、自分のプロジェクトで最も摩擦が大きい箇所に対応する1〜2パターンから始め、対話で不満が出た箇所を追加していくのが現実的な運用です。

Skillsの前段にはプロジェクト全体の規約を書くCLAUDE.md、後段には自動化レイヤのHooksを置くと、設定レイヤが「プロジェクト憲法 → 知識パック → 実行時フック」の3層で整います。Sub-agentsと組み合わせると、より複雑な作業フローを安定実行できるようになります。