08-03. Skills で「特定の場面で起動するスペシャリスト」を作る
この回のゴール
- Skill が CLAUDE.md と何が違うか(常時 vs 場面別、eager vs lazy)を理解する
.claude/skills/<name>/SKILL.mdの構造と発火条件を書けるようになる- 自分のリポジトリで Skill を 2 つ以上作って動作確認する
1. 動機: CLAUDE.md だけでは "詰まる" シーン
CLAUDE.md は 毎セッションの先頭で読まれる = 常駐コンテキスト。 だが業務には 特定の状況でだけ呼びたい知識 がたくさんある:
- コミットメッセージを書く時 → コミット規約 (Conventional Commits 準拠など)
- リリースノートを書く時 → リリースノート用の見出し構成・絵文字
- 新規ライブラリを追加する時 → ライセンス確認とサイズチェック手順
- DB マイグレーションを書く時 → 後方互換性・ロールバックチェックリスト
これら全部を CLAUDE.md に書くと 冗長で読みにくく、効果が薄れる(2 章 6 節のアンチパターン)。
→ Skills = 「特定の意図のときだけ Claude が読みに行く知識・手順」
2. Skill の構造
<repo>/.claude/skills/<skill-name>/
├── SKILL.md # メイン定義 (必須)
├── templates/ # 任意: 補助テンプレ
└── scripts/ # 任意: 実行可能スクリプト
SKILL.md の最低限の中身:
---
name: git-commit-message
description: コミットメッセージを書く / 提案する時に使う Skill。Conventional Commits 規約に従う
---
# コミットメッセージの書き方
## 形式
`<type>(<scope>): <subject>`
## type 一覧
- feat: 新機能
- fix: バグ修正
- ...
## ルール
- 50 字以内
- 動詞の原形で始める
- 末尾にピリオド不要
重要: description フィールド
- Claude は
descriptionを読んで「今、この Skill を発動すべきか」を判断する - 動詞ベース・状況ベースで書く: 「...する時に使う」
- 抽象的すぎる説明だと発火しない / 過剰発火する
3. CLAUDE.md vs Skills vs Hooks
| CLAUDE.md | Skills | Hooks | |
|---|---|---|---|
| いつ読まれる | 毎セッション開始時 | Claude が「使うべき」と判断した時 | 特定イベント時(ToolUse 前後など) |
| Claude の判断 | 常に参照 | description 見て判断 | 関係なく強制実行 |
| 失敗時の影響 | コンテキスト汚染 | 該当タスク質低下 | セッション継続/中断 |
| 用途 | 普遍的なプロジェクトルール | 場面別のノウハウ | 機械的な強制(テスト実行など) |
→ 階層: CLAUDE.md (常駐) ≪ Skills (lazy) ≪ Hooks (強制)
4. ハンズオン: 2 つの Skill を作る
Skill 1: コミットメッセージ
mkdir -p .claude/skills/git-commit-message
.claude/skills/git-commit-message/SKILL.md:
---
name: git-commit-message
description: ステージにある変更からコミットメッセージを書く / 提案する時。Conventional Commits 規約。
---
# Conventional Commits
形式: `<type>(<scope>): <subject>`
type:
- feat: 新機能
- fix: バグ修正
- refactor: 動作を変えない内部改善
- docs: ドキュメントのみ
- test: テストのみ
- chore: その他
ルール:
- subject は 50 字以内、動詞の原形で始める
- breaking change は `feat!:` / `fix!:` で示す
- body には "なぜ" を書く(何をしたかは diff から自明)
Skill 2: PR レビューチェックリスト
mkdir -p .claude/skills/pr-review-checklist
.claude/skills/pr-review-checklist/SKILL.md:
---
name: pr-review-checklist
description: PR をレビューする / レビュー観点を整理する時に使う。
---
# PR レビュー チェックリスト
## セキュリティ
- [ ] ユーザー入力が SQL/シェルコマンドに直接入っていないか
- [ ] 認証チェックが新エンドポイントに入っているか
- [ ] 秘密情報がコードや環境変数依存以外で扱われていないか
## パフォーマンス
- [ ] N+1 クエリになっていないか
- [ ] 大きいループ内で同期 I/O していないか
- [ ] キャッシュ層を通すべき箇所が通っているか
## テスト
- [ ] 新規ロジックに単体テストがある
- [ ] エッジケース(空・null・最大値)が網羅されている
- [ ] 既存テストが壊れていない
## 可読性
- [ ] 命名が意図を表しているか
- [ ] 重要な不変条件にコメントがあるか
- [ ] 複雑な関数は分割すべきか
動作確認
claude
> ステージにある変更でコミットメッセージを書いて
# → git-commit-message Skill が読まれる挙動を観察 (画面に "skill loaded" 的表示)
> 直近の PR #123 をレビューして
# → pr-review-checklist Skill が読まれる
5. アンチパターン
| 症状 | 原因 | 対策 |
|---|---|---|
| 関係ない場面で Skill が発火 | description が広すぎる | 状況を絞る:「コミットメッセージを書く時」 |
| 必要な場面で Skill が呼ばれない | description に該当キーワードが無い | 動詞・名詞両方含める |
| Skill 同士が矛盾 | 似た目的を別 Skill で書いた | 1 つに統合、もしくは明確にスコープ分離 |
| Skill が肥大化 | 全部入りで書いた | サブファイル(templates/, scripts/)に分割し、SKILL.md からは概要のみ |
6. 今回の限界 (notes に書く内容)
- Skills は Claude が判断する 仕組み = 100% の発火保証はない
- 「絶対にこの処理を Edit の前に走らせたい」(例: lint, test) には不向き
- → 次回 (08-04) で Hooks を導入し、強制力のある自動化を学ぶ