Claude Code Skills とは何か

claude-code skills 101

Ryo Nakagami

2026年04月28日

Skill の基礎

  • Skill の基礎

  • 他のカスタマイズ手段との比較

  • まとめ

Skill とは何か

同じ説明を毎回繰り返さず，Claudeに「やり方」を一度だけ教え込む仕組み

  • Skillとは，Claude Codeが特定タスクを正確にこなすための指示・リソースをまとめたフォルダ
  • 各Skillは SKILL.md 一枚を中核とし，frontmatterの name / description でClaudeに自身の役割を共有する
  • ユーザーの依頼内容と description がマッチすると，Claudeが自動的に該当Skillを読み込んで適用する
  • コミットメッセージ・PRレビュー・コーディング規約など，毎回説明していた内容を一度書けば永続化できる

Skillなしの世界 = 同じ指示を毎セッション再入力

  1. PRレビュー時に毎回フォーマットを再説明
  2. コミットメッセージのスタイルを毎回注意
  3. コーディング規約を毎回伝える
  4. 同じ説明をチームメンバーが個別に反復
  5. ナレッジが個人セッションに閉じ込められる

Skillありの世界 = 自動マッチ＆オンデマンド適用

起動の仕組み

  • Claudeがdescriptionを見て自動判定
  • 関連タスク発生時のみ読み込まれる

運用上のメリット

  • 個人 / プロジェクト単位で切り替え可能
  • Git管理できチーム横断で共有できる

Skill の構造

SKILL.md の frontmatter が “看板”，本文が “中身”

  • Skillはフォルダ単位で構成され，SKILL.md をエントリーポイントとする
  • frontmatterの description はClaudeが「このSkillを使うか」を判断する唯一のキー．具体的に書くほど誤発火が減る
  • frontmatter以下の本文に，チェックリスト・整形ルール・出力テンプレートなど Claude に知って欲しい中身を記述する

SKILL.md の最小例

---
name: pr-review
description: Reviews pull requests for code
  quality. Use when reviewing PRs or
  checking code changes.
---

# PR Review Checklist

1. Type safety: 型推論・narrowing が
   壊れていないか
2. Error handling: 例外パスが網羅されているか
3. Test coverage: テストが追加されているか
4. ...

フィールドの役割

フィールド 役割 書き方のコツ
name 識別子 kebab-case，ユニーク
description マッチング用 “Use when …” を含める
本文 指示の中身 チェックリスト形式が読みやすい

REMARKS

  • 初期ロードはname + descriptionのみ．本文はマッチ後に遅延ロードされる
  • そのため大量のSkillを置いてもコンテキストを圧迫しない

実例: Skill が自動で読み込まれる様子

description にマッチした瞬間，Claude Code が該当Skillを識別しターミナルに表示

Claude Code が pr-review Skill を自動でロードする様子

読み込みまでの3ステップ

  1. ユーザーが自然言語で依頼を入力
    • 例: Can you review the pull request on branch sg-221?
  2. Claude Code が登録されたSkillの description と照合 → pr-review を自動選定
  3. ターミナルに Skill(pr-review) とロードログが可視化され，本文がコンテキストに展開される

ここがSkillsの本質

  • ユーザーは /pr-review を明示的に呼んでいないのに自動マッチ
  • ロードが視覚的に確認できるので「期待した Skill が起動したか」をその場でデバッグ可能
  • 不発火なら description の文言を見直すサイン

Skill の保管場所

個人用は ~/.claude/skills，プロジェクト用は .claude/skills

Personal skills = 個人の作法を全プロジェクトに

  • 配置先: ~/.claude/skills/<skill-name>/
  • Windows: C:/Users/<user>/.claude/skills
  • 自分のあらゆるClaude Code実行で自動的に有効
  • ユースケース:
    • コミットメッセージの個人的な好み
    • 文書スタイル
    • コードの説明レベルの調整

Project skills = チーム標準をリポジトリと同梱

  • 配置先: <repo>/.claude/skills/<skill-name>/
  • リポジトリにcommitすればclone した全員に同じSkillが配布
  • ユースケース:
    • チームのコードレビュー基準
    • PRテンプレート / ブランチ命名規則
    • 会社のブランドガイドライン
    • 特定フレームワーク向けデバッグチェックリスト

Skill の優先順位と4階層

名前衝突時は Enterprise > Personal > Project，Plugin は名前空間で隔離

  • Skillの配置先はEnterprise / Personal / Project / Plugin の4階層に分かれており，それぞれ適用範囲が異なる
  • 同名 Skill が複数レベルに存在する場合，上位レベルが下位を上書きする（IT管理の Enterprise 設定が個人や Project の設定より優先される）
  • Plugin Skill のみ <plugin>:<skill> の名前空間を持つため他レベルと衝突しない
レベル 配置パス 適用範囲
Enterprise managed settings 参照（IT管理） 組織内の全ユーザーに適用
Personal ~/.claude/skills/<name>/SKILL.md 自分の全プロジェクトに適用
Project .claude/skills/<name>/SKILL.md そのリポジトリ内のみに適用
Plugin <plugin>/skills/<name>/SKILL.md plugin が有効な場所すべてに適用

使い分けの指針

  • Personal: コミット文体・説明レベルなど自分の作法
  • Project: チームのレビュー基準・ブランドガイド（repo に commit して配布）
  • Enterprise: 全社統一ルール（IT 部門が managed settings で配布）
  • Plugin: skilltool や OSS 経由で配布する再利用 Skill

他のカスタマイズ手段との比較

  • Skill の基礎

  • 他のカスタマイズ手段との比較

  • まとめ

Skills vs CLAUDE.md vs Slash Commands

「いつロードされるか」と「誰が起動するか」が3者の本質的な違い

仕組み ロードのタイミング 起動者 主なユースケース
CLAUDE.md 全会話の冒頭で常時ロード 自動（不可避） プロジェクト全体に必ず守って欲しい絶対ルール（例: strict モード必須）
Skill descriptionがマッチした時だけオンデマンド Claudeが自動判定 特定タスクで必要な専門知識（PRレビュー基準・ブランドガイド等）
Slash command ユーザーが /cmd と打った時のみ ユーザーが明示起動 確定的に呼び出したい定型ワークフロー（/review /security-review等）

使い分けの原則

  • 必ず守らせたい → CLAUDE.md
  • 状況依存で適用したい → Skill
  • 明示的に呼び出したい → Slash command

コンテキスト消費の観点

  • CLAUDE.md は全会話で消費 → 肥大化に注意
  • Skillはマッチ時のみ消費 → 大量に置けるのが強み
  • Slash commandも呼び出し時のみ

いつ Skill にすべきか

「同じ説明を2回以上した」が Skill 化のシグナル

  • Skill化の判断基準はシンプル: 「自分が同じ説明をClaudeに繰り返している」と気づいた瞬間が，それは Skill になるべき知識
  • 一般のCLAUDE.mdに入れるには特定的すぎるが，毎回手で説明するには汎用的すぎる → そのスイートスポットがSkill
  • チームで共有したいか，個人だけで使うかで保管場所を切り替える

Skill化に向いているもの

  • チームのコードレビュー基準
  • 好みのコミットメッセージ書式
  • 組織のブランドガイドライン
  • 特定文書タイプのテンプレート
  • フレームワーク固有のデバッグ手順
  • リリースノート整形ルール

Skill化に向かないもの

  • プロジェクト全体で常に守って欲しい掟 → CLAUDE.md
  • 一回限りのタスク → 直接プロンプト
  • 確定的に毎回呼び出したい処理 → Slash command
  • コード本体に書くべきロジック

まとめ

  • Skill の基礎

  • 他のカスタマイズ手段との比較

  • まとめ

Skill 導入の3ステップ

「気づく → 書く → 置く」のサイクルを回せば，Claude Codeの再現性が劇的に上がる

気づく

  • 同じ説明の繰り返しを検知
  • 「またこれ書いてる」を捉える

書く

  • SKILL.md を作成
  • description を具体的に

置く

  • 個人なら ~/.claude/skills
  • チームなら .claude/skills

改善

  • 誤発火・空振りを観察
  • description を磨き続ける

Key Takeaways

  • Skillとは「Claudeに一度だけやり方を教えるmarkdownファイル」．以降は自動適用
  • frontmatterの description がマッチング鍵 — 具体的に書くこと
  • 個人用は ~/.claude/skills，チーム用は repo の .claude/skills
  • CLAUDE.md（常時） / Slash command（明示起動）と違い，状況に応じて自動ロードされる
  • 同じ説明を繰り返している自分に気づいたら，それは新しいSkillの種