Claude CodeのSkillsとCLAUDE.mdを使いこなすベストプラクティス

この記事では、Claude Code の「Skillsシステム」と「CLAUDE.md」の設計ベストプラクティスを解説します。Skillsの内部動作（Progressive Disclosure、制御フラグ）から、CLAUDE.mdのサイズ管理、`.claude/rules/` を使ったルールの細分化まで、具体的なコード例を交えながら説明します。

はじめに

Claude Codeを使い始めると、最初は「自然言語で指示を出すだけ」という体験に驚きます。しかし、プロジェクトが大きくなるにつれて「毎回同じ説明をする手間」「AIが意図しない動作をする」という問題が出てきます。

その解決策が Skillsシステム と CLAUDE.md です。この2つを正しく設計することで、Claude Codeは「毎回説明が必要なアシスタント」から「プロジェクトを深く理解した自律パートナー」に変わります。

本記事では、仕組みの詳細と実際に使えるベストプラクティスを解説します。

Skillsシステムの仕組みを理解する

SKILL.mdとは何か

Skillsは、SKILL.md ファイルを含むディレクトリのことです。プロジェクト内では .claude/skills/{スキル名}/ に配置します。

.claude/
└── skills/
    ├── write-article/
    │   └── SKILL.md
    └── generate-image/
        ├── SKILL.md
        └── generate-illust.py   ← 参照ファイル（オンデマンドロード）

SKILL.md はYAMLフロントマターとMarkdown本文で構成されます。

---
name: write-article
description: テーマを受け取り記事と画像を生成する。「記事を書いて」「記事を作って」で自動トリガー。
allowed-tools:
  - Write
  - Read
  - Edit
  - Bash
---

## STEP 1 — テーマの解釈
...

呼び出し方は2種類あります。/write-article のように /スキル名 で直接呼び出す方法と、descriptionに書いたキーワードに一致したときに自動で呼び出される方法です。

Progressive Disclosure（段階的読み込み）

Skillsシステムの最も重要な設計原則が Progressive Disclosure（段階的読み込み）です。

タイミング	ロードされる内容
セッション起動時	name と description のみ（軽量）
スキル呼び出し時	SKILL.md の本文全体
本文が参照しているファイル	オンデマンドでロード

この設計のおかげで、スキルが100個あってもセッション起動時のコンテキスト消費は最小限に抑えられます。

この仕組みを理解すると「なぜdescriptionを丁寧に書くべきか」がわかります。descriptionは常時メモリに存在する唯一の情報であり、自動トリガーの判断基準もここから行われます。

配置場所と優先順位

スキルは4つのスコープに配置でき、優先順位があります。

Enterprise（組織管理者が設定・全員に強制適用）
  > Personal（~/.claude/skills/）
    > Project（./.claude/skills/）
      > Plugin（拡張機能が提供）

同じ名前のスキルが複数スコープに存在する場合、より上位のスコープが優先されます。チームで共有すべきスキルはProjectスコープ（.claude/skills/）に、個人的なワークフローはPersonalスコープ（~/.claude/skills/）に置くのが基本的な使い分けです。

良いSkillを書くためのベストプラクティス

descriptionを正しく書く

descriptionは「常時メモリに存在する検索インデックス」です。ここに何を書くかがスキルの使いやすさを決めます。

効果的なdescriptionは2つの要素を含みます。

何をするスキルか（1〜2文で端的に）
どんな指示で自動トリガーされるか（具体的なキーワード）

良い例：

description: kakubase記事のX（Twitter）告知投稿文を生成する。「X投稿を作って」「ツイート文を書いて」「記事をXで告知したい」のような指示で自動トリガー。記事の内容を受け取り、読まれやすい投稿文を3パターン生成する。

**アンチパターン：descriptionの典型的な失敗例**

- 「作業する」「処理する」など動詞が曖昧で、何をするスキルか伝わらない
- トリガーキーワードが書かれていないため自動呼び出しされない
- 「このスキルはXXXをしてYYYをしてZZZをして...」と長すぎる（descriptionは本文ではない）

制御フラグを使い分ける

SKILL.mdのフロントマターには、スキルの動作を制御する重要なフラグがあります。

disable-model-invocation: true

ファイルの書き込みや外部API呼び出しなど副作用のある処理を持つスキルに使います。このフラグを設定すると、ユーザーが明示的に /スキル名 と入力するまで実行されません。誤ってトリガーされるリスクを防ぎます。

---
name: deploy-to-production
description: 本番環境へのデプロイを実行する。必ず /deploy-to-production で明示的に呼び出すこと。
disable-model-invocation: true
allowed-tools:
  - Bash
---

user-invocable: false

背景知識やコーディング規約など、AIが参照するが人間が直接呼び出す必要のないスキルに使います。自動選択はされますが /呼び出し はできません。

---
name: project-coding-standards
description: このプロジェクトのコーディング規約。TypeScriptの型定義、命名規則、テスト方針を含む。
user-invocable: false
---

allowed-tools

使用するツールを最小権限で制限します。読み取り専用のスキルには Read だけを指定する、という発想が重要です。

# 読み取りのみのスキル（ファイル生成なし）
allowed-tools:
  - Read

# ファイル生成を伴うスキル
allowed-tools:
  - Write
  - Read
  - Edit
  - Bash

ステップ設計のコツ

効果的なスキルのSTEP構成は「判断→実行→確認→次へ」の単位で細分化されています。

エラーリカバリーを明記する

「最大N回まで再試行する」「失敗した場合はXを試みる」といった具体的な指示があると、AIが自律的に対処できます。

## STEP 3 — 画像生成

Gemini API で画像を生成する。
生成した画像を Read で確認し、テーマと合っていない場合はプロンプトを修正して
再生成する（最大2回まで）。

完了報告フォーマットを統一する

スキルの最後に統一した完了報告を書くと、実行結果を一目で確認できます。

## STEP 5 — 完了報告

✅ 記事を作成しました

📄 articles/{slug}/index.md
🖼  articles/{slug}/cover.png

次のステップ：
1. npx kakubase-cli preview でプレビュー確認
2. 問題なければ published: true に変更
3. git push で公開

アンチパターン

以下のパターンはスキルの品質を下げます。

**過度な冗長性**：1スキルに15以上のSTEPを詰め込むと、Claude Codeが全体を把握しにくくなります。1スキル = 1つの明確なゴールを守ってください。

**参照の深すぎるネスト**：スキルがスキルを呼び出すような構造は避けます。スキル間の依存は管理が難しくなります。

**選択肢が多すぎる確認**：ユーザーへの確認事項は最小限にします。5択以上の選択肢は認知負荷を上げるだけです。

引数の渡し方

スキルには引数を渡せます。SKILL.md内では $ARGUMENTS としてプレースホルダーが展開されます。

# $ARGUMENTS で全引数を文字列として受け取る
/generate-image my-article-slug

# $ARGUMENTS[0], $ARGUMENTS[1] で位置引数
/write-article "Claude Codeの使い方" intro

# 名前付き引数（frontmatterで定義）
/generate-image --slug my-article --style dark

名前付き引数を使う場合は、SKILL.mdのフロントマターで事前に定義します。

---
name: write-article
arguments: [theme, style]
---

テーマ「$theme」、スタイル「$style」で記事を書く。

CLAUDE.mdの設計原則

読み込みタイミングとスコープ

CLAUDE.mdはセッション開始時に全文がコンテキストウィンドウに読み込まれます。Skillsとは異なり、常時コンテキストを占有します。

スコープと優先順位は以下の通りです。複数のCLAUDE.mdが存在する場合、すべてがマージされて適用されます。

Managed（組織管理者が設定・全員に強制）
  > Project（./CLAUDE.md）        ← チーム共有ルール
    > User（~/.claude/CLAUDE.md） ← 個人の好み
      > Local（./CLAUDE.local.md）← 個人×プロジェクト設定（.gitignore推奨）

CLAUDE.local.md は .gitignore に追加することで、個人設定とチーム共有設定を明確に分離できます。

何を書くか、何を書かないか

書くべき内容	書かないべき内容
よく使うコマンド（dev/build/test）	APIリファレンス全体
リポジトリのディレクトリ構造	複数ステップの手順（→ Skill化する）
命名規則・コーディング規約	シークレット・APIキー
禁止事項（やってはいけないこと）	めったに参照しない情報
「確認不要な操作」の明示	ライブラリの全メソッド解説

**「複数ステップの手順」はCLAUDE.mdに書かない**

「新機能を追加するときは①ブランチを切って②実装して③テストを書いて④PRを出す」のような手順は、CLAUDE.mdではなくSkillとして定義するべきです。CLAUDE.mdはコンテキスト（前提知識）であり、ワークフロー（手順書）ではありません。

サイズ制限（200行未満の根拠）

CLAUDE.mdが大きくなるほど、コンテキストウィンドウの消費が増え、関係のない情報がノイズとして応答精度を下げます。200行未満を目安にしてください。

200行を超えてきたら、以下のアクションを検討します。

「めったに参照しない情報」を削除する
「特定ファイルにしか関係しないルール」を .claude/rules/ に移動する
「複数ステップの手順」をSkillに変換する

このkakubase-contentリポジトリのCLAUDE.mdは約190行です。コマンド集・フォーマットルール・禁止事項・利用可能スキルの一覧が簡潔にまとめられています。参考にしてみてください。

ルールの細分化：.claude/rules/の活用

path-scoped rules

.claude/rules/ ディレクトリに配置したMarkdownファイルは、対象のファイルパターンに一致したときだけ自動ロードされます。これを path-scoped rules と呼びます。

.claude/
└── rules/
    ├── articles.md    ← articles/**/*.md を編集するときのみロード
    ├── typescript.md  ← src/**/*.ts を編集するときのみロード
    └── api.md         ← api/**/* を編集するときのみロード

各ファイルのフロントマターで対象パターンを指定します。

---
glob: "articles/**/*.md"
---

## 記事ファイルを編集するときのルール

- frontmatter の published は必ず false のまま（下書き保存）
- H1（#）は使わない
- コードブロックには必ず言語指定を付ける

CLAUDE.mdに全ルールを詰め込む代わりに、関係するファイルを編集するときだけ必要なルールが注入される仕組みです。

Import構文（@記法）

CLAUDE.mdから別ファイルを参照する @記法 を使うと、大規模プロジェクトでルールを分離しながら管理できます。

# CLAUDE.md

## ルール

@rules/coding-standards.md
@rules/git-conventions.md

CLAUDE.md自体はインデックスとして薄く保ち、詳細は参照先ファイルに書く設計です。

CLAUDE.local.mdの使いどころ

CLAUDE.local.md は個人の開発環境固有の設定を書く場所です。必ず .gitignore に追加してください。

# CLAUDE.local.md（.gitignoreに追加済み）

## 個人設定

- このマシンのPlaywrightパス: /Users/kentaro/.../node_modules
- ローカルでは articles/ 配下のファイル生成は確認不要
- 返答スタイル: 簡潔に。説明は求めたときだけ

実践的な構成例

小規模：個人ブログ・コンテンツリポジトリ

このkakubase-contentリポジトリがまさにこのパターンの好例です。

CLAUDE.md（〜200行）
  ├── コマンド集
  ├── 記事フォーマットルール
  ├── 禁止事項
  └── 利用可能スキル一覧

.claude/
└── skills/
    ├── write-article/SKILL.md
    ├── generate-image/SKILL.md
    ├── write-x-post/SKILL.md
    └── design-thumbnail/SKILL.md

CLAUDE.mdに「何ができるか」のメタ情報（スキル一覧）を書いておくと、Claude Codeがスキルを選択しやすくなります。

中規模：チーム開発（フロントエンド+API）

CLAUDE.md（100〜200行）
  ├── コマンド集
  └── 全体ルール

.claude/
├── rules/
│   ├── frontend.md（glob: src/components/**）
│   └── api.md（glob: api/**/*.ts）
└── skills/
    ├── add-feature/SKILL.md
    ├── run-tests/SKILL.md
    └── create-pr/SKILL.md

CLAUDE.local.md（個人設定、.gitignore済み）

フロントエンドとAPIのルールをpath-scoped rulesで分離することで、CLAUDE.mdをシンプルに保てます。

大規模：モノレポ

CLAUDE.md（グローバルルールのみ、50行以内）

packages/
├── web/
│   └── CLAUDE.md（フロントエンド固有ルール）
└── api/
    └── CLAUDE.md（バックエンド固有ルール）

.claude/
├── rules/（横断的ルール）
└── skills/（共通スキル）

~/.claude/
└── CLAUDE.md（個人設定）

モノレポではルートのCLAUDE.mdを薄くして、各パッケージ固有のCLAUDE.mdに詳細を委ねます。Claude Codeはカレントディレクトリから上位を辿って全CLAUDE.mdを読み込むため、この階層構造が有効に機能します。

まとめ

設定	役割	目安
`CLAUDE.md`	セッション全体を通じた前提知識	200行未満
`.claude/skills/`	再利用可能なワークフロー	1スキル = 1ゴール
`.claude/rules/`	ファイル種別ごとの補足ルール	CLAUDE.mdが大きくなったら移動
`CLAUDE.local.md`	個人×プロジェクトの環境設定	.gitignoreに追加

Skillsシステムの肝は Progressive Disclosure です。descriptionを丁寧に書き、SKILL.md本文は「呼ばれたときだけ読まれる」ことを意識して設計してください。

CLAUDE.mdの肝は 「常時コンテキストを占有する」 という性質の理解です。情報を詰め込むのではなく、「AIが毎回必要とする前提知識」だけを厳選して書きましょう。

まずは1つのスキルを作るところから始めてみてください。よく繰り返す作業（記事生成、画像作成、PR作成など）を1つSkillとして定義するだけで、Claude Codeの生産性は大きく変わります。