Claude Codeのカスタムスキル構築：完全チュートリアル

3回連続のセッションで、同じセキュリティチェックリストをClaude Codeに貼り付けていました。そのチェックリストには、チームのAPIデザイン固有のIDORチェック、認証フローのセッション処理ルール、PIIフィールドのデータ露出ルールなど、チーム特有の脆弱性パターンが含まれていました。毎回、Claudeは完璧にそれらを適用しました。毎回、私はそれを貼り付けることを覚えていなければなりませんでした。

同じコンテキストを何度も説明し直している自分に気づいた瞬間——それがスキルを構築すべきタイミングです。

TL;DR

スキルはモデル起動型の拡張機能です。Claudeがコンテキストに基づいて自動的に発見・適用するもので、明示的に呼び出す必要はありません¹。信頼性の高いスキルの鍵はdescriptionフィールドにあります。Claudeはキーワードマッチングではなく、LLM推論を使って各スキルをいつアクティベートするかを判断します¹。セッションをまたいで適用されるドメイン専門知識（セキュリティパターン、コードスタイル、ビジネスルール）のためにスキルを構築しましょう。一回限りのタスクにはスキルではなく、スラッシュコマンドを使ってください。

前提条件： Claude Codeの拡張システムに精通していること。スキル、コマンド、サブエージェントの比較については、ガイドのスキルセクションをご覧ください。

スキルを構築すべきタイミング

繰り返しのプロンプトすべてがスキルに値するわけではありません。判断のフレームワークは以下の通りです：

スキルはClaudeが常に利用可能な知識のためのものです。スラッシュコマンドは明示的にトリガーするアクションのためのものです。どちらにするか迷った場合は、こう自問してください：「Claudeが自動的に適用すべきか、それとも実行タイミングは自分で決めるべきか？」

よくある間違い： 週に1回しか使わないものにスキルを構築してしまうことです。私はgit関連のプロンプトすべて（リベース、マージ、チェリーピック、git statusまで）でアクティベートするgit-rebase-helperスキルを構築しました。説明文が広すぎたため、不要な80%のセッションでコンテキストを汚染し、2%のコンテキスト予算¹をめぐって他のスキルと競合しました。解決策は、そのスキルを削除し、実際に必要なときに/rebaseというスラッシュコマンドを使うことでした。スキルは安定したドメイン専門知識をエンコードすべきであり、たまにしか使わないワークフローのためのものではありません。

チュートリアル：コードレビュースキルを構築する

ステップ1：ディレクトリを作成する

スキルは、最も広いスコープから最も狭いスコープまで、4つの場所に配置できます¹：

このチュートリアルでは、パーソナルスキルを作成します：

mkdir -p ~/.claude/skills/code-reviewer

ステップ2：フロントマター付きのSKILL.mdを作成する

すべてのスキルには、2つの部分から成るSKILL.mdファイルが必要です：Claudeにスキルをいつ使うかを伝えるYAMLフロントマター（---マーカーの間）と、スキルが起動されたときにClaudeが従う指示を含むMarkdownコンテンツです¹。

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

### Data Exposure
- PII masked in log output and error messages
- API responses don't leak internal IDs or stack traces
- Sensitive fields excluded from serialization defaults

allowed-tools: Read, Grep, Globに注目してください。 これはスキルを読み取り専用の操作に制限します。コードレビュアーはファイルを検査できますが、変更はできません。ツール制限により、スキルが意図しない副作用を持つことを防ぎます。

name、description、allowed-tools以外にも便利なフロントマターフィールドがあります¹：

公式ドキュメントからの注意点：context: forkは「分離の恩恵を受ける明示的な指示を持つスキルにのみ意味があります」¹。分析スキル（コードレビュー、セキュリティ監査）でクリーンなコンテキストが必要な場合に使用し、メインの会話に溶け込むべき知識スキルには使用しないでください。

ステップ3：サポートリソースを追加する

スキルは同じディレクトリ内の追加ファイルを参照できます¹：

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

SKILL.mdから相対リンクで参照します：

See [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) for OWASP Top 10 checks.
See [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) for query optimization.

Claudeはスキルがアクティベートされたときに、標準のファイル読み取りツールを使ってこれらのファイルをオンデマンドで読み込みます¹。SKILL.mdは500行以下に抑え、詳細なリファレンス資料はサポートファイルに移動しましょう³。スキルファイルを短くすることで、コンテキスト注入のオーバーヘッドが減り、Claudeが現在のタスクに集中できるようになります。

ステップ4：アクティベーションをテストする

次にClaude Codeセッションを開始したときにスキルがアクティベートされます。テストしてみましょう：

# Ask Claude to review code — should trigger the skill automatically
claude "Review the authentication middleware in app/security/"

以下の2つの方法でスキルが読み込まれたことを確認できます¹：

# In an interactive session, ask Claude directly:
> What skills are available?

# Or check the context budget for excluded skills:
> /context

スキルがアクティベートされない場合、問題はほぼ確実にdescriptionフィールドにあります。ステップ5をご覧ください。

ステップ5：最も重要なステップ——説明文の作成

descriptionフィールドはスキルの中で最も重要な1行です。内部の動作を説明します：セッション開始時に、Claude Codeはすべてのスキルのnameとdescriptionを抽出し、Claudeのコンテキストに注入します。メッセージを送信すると、Claudeは正規表現でもキーワードマッチングでも埋め込み類似度でもなく、言語モデルの推論を使ってスキルが関連するかどうかを判断します。公式ドキュメントには次のように記載されています：「Claudeはタスクをスキルの説明文と照合し、どれが関連するかを判断します。説明文が曖昧だったり重複していると、Claudeは間違ったスキルを読み込んだり、役立つはずのスキルを見逃す可能性があります」¹。

Claude Codeのソースコードの独立した分析でもこのメカニズムが確認されています：スキルの説明文はシステムプロンプトのavailable_skillsセクションに注入され、モデルは起動時に標準的な言語理解を使って関連するスキルを選択します⁴。LLMベースのマッチングは、説明文の書き方に重要な影響を与えます。

悪い説明文：

description: Helps with code

Claudeはいつアクティベートすべきか分かりません。「Helps with code」はすべてに一致し、同時に何にも一致しません。マッチングがLLM推論であるため、曖昧な説明文は予測不可能なアクティベーションを引き起こします。

少し良い説明文：

description: Review code for bugs and issues

まだ曖昧すぎます。どんな種類のバグですか？どんな種類の問題ですか？Claudeの組み込み分析の代わりにこのスキルを使うべきなのはいつですか？

効果的な説明文：

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

効果的な説明文が機能する理由は以下を含んでいるからです： - 何をするか： 特定の問題タイプに対してコードをレビューする - いつ使うか： 変更の検査、PR、品質分析 - トリガーフレーズ： review、audit、check——ユーザーが自然に入力する言葉

知っておくべき制約： すべてのスキルの説明文は「コンテキストウィンドウの2%で動的にスケーリングし、フォールバックとして16,000文字」のコンテキスト予算を共有します¹。多くのスキルがある場合、各説明文は簡潔に保ちましょう。冗長な説明文は、限られたスペースをめぐって他のスキルと競合します。SLASH_COMMAND_TOOL_CHAR_BUDGET環境変数で予算をオーバーライドできます²が、より良い解決策は、より短く正確な説明文を書くことです。

さまざまな説明文をテストしましょう。 新しいセッションを開始し、Claudeにコードレビューを依頼し、スキルがアクティベートされるか確認してください。されない場合は、トリガーフレーズを追加します。すべきでないときにアクティベートされる場合は、説明文をより具体的にしてください。

ステップ6：使用状況に基づいてイテレーションする

1週間使用した後、以下のことに気づくでしょう： - スキルがチェックすべきだがしていないパターン——SKILL.mdに追加する - 無関係なタスクでの誤ったアクティベーション——説明文を厳密にするか、disable-model-invocation: trueを追加して明示的な/code-reviewer呼び出しを必須にする - 不足しているコンテキスト——サポートリソースファイルを追加する - 厳しすぎるまたは緩すぎるツール制限——allowed-toolsを調整する

スキルは生きたドキュメントです。最初のバージョンが最終バージョンになることはありません。

上級編：プロンプトライブラリとしてのスキル

単一目的のスキルを超えて、ディレクトリ構造は整理されたプロンプトライブラリとして機能します：

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

各スキルはチームの専門知識の異なる側面をエンコードします。まとめると、Claudeがコンテキストに基づいて自動的に参照するナレッジベースを形成します。ジュニア開発者が、わざわざ尋ねなくてもシニアレベルのガイダンスを受けられるようになります。

スキル数に関する注意： スキルが多いほど、コンテキスト予算をめぐって競合する説明文が増えます¹。スキルがアクティベートされないことに気づいたら、/contextを実行して除外されているスキルがないか確認してください。曖昧なスキルを多数作るよりも、説明文が適切な少数のスキルを優先しましょう。

チームとのスキル共有

パーソナルスキル（~/.claude/skills/）は自分だけのものです。個人的な好み、実験的なパターン、自分のワークフローに特化した専門知識に使用します。

プロジェクトスキル（リポジトリルートの.claude/skills/）はgitを通じて共有されます¹：

# Create project-level skill
mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...

# Commit and push
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

チームメイトがプルすると、自動的にスキルが取得されます。インストールも設定も不要です。gitによる配布は、チーム全体で専門知識を標準化する最も効果的な方法です。

共有スキルのガイドライン： - プロジェクトスキルはドメイン専門知識（ビジネスルール、アーキテクチャパターン）に集中させる - パーソナルスキルはワークフローの好み（フォーマット、コミットスタイル）に使う - SKILL.mdの冒頭にコメントでスキルの存在理由を記載する - スキルの変更は他のコードと同様にPRでレビューする

重要なポイント

• 同じコンテキストを繰り返し説明していることに気づいたら、スキルを構築しましょう。 同じチェックリストを3回貼り付けたなら、それはスキルにすべきです。
• 説明文フィールドがすべてを決定します。 Claudeはリクエストと説明文を照合するためにLLM推論を使用します¹。スキルの内容よりも説明文に多くの時間を投資してください。
• allowed-toolsで副作用を制限しましょう。 読み取り専用のスキルはRead、Grep、Globに制限すべきです。
• プロジェクトスキルはgitで共有しましょう。 設定不要でチームの知識を配布できます¹。
• 過度な抽象化は避けましょう。 すべてのマイクロパターンにスキルを作ると、メンテナンスの負担が増え、さらにコンテキスト予算をめぐって競合します。安定し、再利用可能で、メンテナンスする価値のある専門知識のためにスキルを構築しましょう。

参考文献