Skills は Claude に 特定の専門知識・手順 を後付けで教える仕組み。 プラグイン的に追加でき、必要なときだけ自動でロードされます。

構造

~/.claude/skills/
└── pdf-extraction/
    ├── SKILL.md            # 概要 (Claude がまず読むファイル)
    ├── reference.md        # 詳細リファレンス (必要時に参照)
    ├── examples.md
    └── scripts/
        └── extract.py

SKILL.md の例

```markdown

name: pdf-extraction description: PDF からテキスト・表を抽出する手順

PDF 抽出スキル

ユーザーが「PDF を要約」「PDF から表を抜く」などを依頼したとき。

1. pip install pdfplumber
2. scripts/extract.py <path> を実行
3. 出力 JSON を要約

• スキャン PDF は OCR が必要。Tesseract を案内すること。 ```

Skill を作るコツ

• 小さく分割: 1 スキル 1 目的。
• YAML フロントマター必須: name, description。
• 段階的開示: SKILL.md は短く、詳細は別ファイルに。SKILL.md は最初に必ず読まれるので、ここを長くするとコンテキストを浪費する。
• 発火条件を明記: いつ Claude がこのスキルを呼ぶべきか書く。

Skills vs Slash Commands vs CLAUDE.md

公式系スキルの例

• claude-api: Anthropic SDK を使うコードを書くときのガイド
• simplify: コードのリファクタリング案を出す
• review: PR レビュー
• security-review: セキュリティ観点レビュー
• fewer-permission-prompts: 権限プロンプトを減らす設定提案

これらは新規プロジェクトでも自動的に呼び出されることがあります。

Skill の発火を観察する

Claude Code は内部で次のようなロジックで動作します: 1. ユーザー入力を受信 2. 利用可能なスキルの description を見て、関連性を判断 3. 関連スキルがあれば SKILL.md をコンテキストに追加 4. 必要なら scripts/ や reference.md も読む

つまり SKILL.md の description が呼び出し精度を決める ので、 具体的なトリガー (「ユーザーが Z をしたいとき」) を書くのが効果的。

試す: スキルアイデアを Claude に出させる

Skill 1: api-versioning — REST API のバージョニング規約

~/.claude/skills/api-versioning/SKILL.md:

```markdown

name: api-versioning description: REST API のバージョニング規約を提供。ユーザーが「API のバージョン」「v2 endpoint」「後方互換」「deprecate」などについて質問したり、新しいエンドポイントを追加するときに自動発火。

REST API バージョニング・スキル

• 新しい API エンドポイントを追加する依頼
• 既存エンドポイントの破壊的変更
• 「v2 にしたい」「deprecate」などの言葉が出たとき

• URL パスベース (/api/v1/..., /api/v2/...)
• ヘッダ: Accept: application/vnd.our-app.v2+json (二重サポート時のみ)

1. 新しい version の endpoint を 追加 (旧版は残す)
2. 旧版に Deprecation: true ヘッダ + Sunset: <日付> を付与
3. レスポンスに _deprecated: true フィールドを追加 (JSON の場合)
4. 6 ヶ月の移行期間を経て旧版を削除

• 既存の v1 のレスポンス形を変える (新フィールド追加は OK)
• 既存の HTTP ステータスコードを変える
• 旧版を予告なく削除

詳細な手順は @reference.md ```

~/.claude/skills/api-versioning/reference.md に書き分け方を詳細に書く (省略)。

Skill 2: pii-redaction — 個人情報マスキング

~/.claude/skills/pii-redaction/SKILL.md:

```markdown

name: pii-redaction description: ログや顧客データを Claude に貼る前に PII (個人情報) をマスキングする手順。ユーザーが「ログを分析」「顧客データを見せる」「PII」「マスキング」と言ったとき発火。

PII マスキング・スキル

ユーザーが顧客データ・ログ・スクショを Claude に渡そうとするとき。

• 氏名 → 「ユーザー A」「ユーザー B」
• メール → [email_1], [email_2]
• 電話 → [phone_1]
• 住所 → 「[住所_1]」(都道府県以下を削除)
• クレジットカード → [card_xxxx]
• IP アドレス → [ip_1] (デバッグ目的なら下位 octet だけ残す)
• 社内 URL → [internal_url_1]

1. 元データをコピー
2. scripts/redact.py を実行 (下記参照)
3. 出力を確認
4. 確認 OK なら Claude に渡す

@scripts/redact.py を参照。

• 同一顧客は同じ ID にマッピング (関係性が保たれるよう)
• マスキング後の文字数が大幅に変わると統計が崩れるので注意 ```

これは Anthropic 公式の公開スキルにも類似のものがあり、研修先で重宝されます。

Skill 3: commit-message-jp — 日本語コミットメッセージ規約

<repo>/.claude/skills/commit-message-jp/SKILL.md:

```markdown

name: commit-message-jp description: 日本語のコミットメッセージ規約。git commit を依頼されたときに自動発火。Conventional Commits を日本語で運用するチーム向け。

日本語コミットメッセージ規約

git commit を Claude が打とうとするとき。

``` <種別>: <概要 (50 字以内)>

<詳細 (任意。何を/なぜ。72 字で改行)> ```

• feat: 新機能
• fix: バグ修正
• refactor: リファクタ (挙動変更なし)
• docs: ドキュメント
• test: テスト
• chore: ビルド・設定・依存
• perf: パフォーマンス改善
• style: フォーマット (挙動変更なし)

``` feat: ログイン画面に Google OAuth を追加

ユーザーが Google アカウントでログインできるようにする。 authlib を使い OAuth 2.0 フローを実装。テスト 3 件追加。 ```

``` update ← 種別なし、概要なし fix: バグ修正 ← 何のバグかわからない すごい機能を追加した！ ← 種別なし、感情的 ```

• 概要に絵文字 (Slack 通知が崩れる現場用)
• 概要に末尾ピリオド・句点
• 「ちょっと」「とりあえず」などの曖昧表現
• 「Co-authored-by: Claude」などの追記 (人がコミットする想定) ```

これをリポジトリ単位で置けば、Claude が git commit する際にこの規約に従います。

Skill 設計の鉄則

1. description にトリガーキーワードを散りばめる — 自動発火の精度はここで決まる
2. SKILL.md は短く (200〜300 行以内、長くなったら別ファイルに分割)
3. 「してはいけないこと」を明記 — 暴走防止
4. 更新日を意識 — 規約が古くなる前に保守

次の構造で ~/.claude/skills/changelog-helper/ を作ってください。

changelog-helper/
├── SKILL.md
└── template.md

SKILL.md の役割: ユーザーが「変更履歴」「CHANGELOG」と言ったときに自動発火し、git log の最近 20 件から CHANGELOG エントリを生成する手順を提示する。 template.md にはエントリ形式の雛形を書く。