Claude Code スキル: 自動起動するカスタム拡張機能を作る

Claude Code のカスタムスキルはどう作るのでしょうか。 ~/.claude/skills/<name>/（個人用）または .claude/skills/<name>/（プロジェクト単位）に SKILL.md ファイルを作り、name、description、allowed-tools の各フィールドを含む YAML frontmatter に続けて、markdown で専門知識を書きます。Claude は description に対する LLM の推論を使い、タスクが一致したときにスキルを自動起動します。git で共有したプロジェクトスキルなら、チームメンバー側の設定は一切不要です。

3セッション続けて、同じセキュリティチェックリストを Claude Code に貼り付けていました。そこにはチーム固有の脆弱性パターンが並んでいます。自分たちの API 設計に固有の IDOR チェック、認証フローに合わせたセッション処理の規則、PII フィールドのデータ露出の規則。毎回、Claude はそれを完璧に適用してくれました。そして毎回、貼り付けること自体を自分で覚えておく必要があったのです。

同じコンテキストを説明し直している自分に気づいた瞬間こそが、スキルを作るべきタイミングです。

TL;DR

スキルはモデルが呼び出す拡張機能です。明示的に呼び出さなくても、Claude がコンテキストに応じて自動的に見つけて適用します ¹。信頼できるスキルの鍵は description フィールドにあります。Claude はキーワード一致ではなく LLM の推論で、それぞれのスキルをいつ起動するかを判断するからです ¹。セッションをまたいで通用するドメイン知識（セキュリティのパターン、コードスタイル、業務ルール）はスキルにしましょう。一度きりのタスクにスキルは作らず、代わりにスラッシュコマンドを使ってください。

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

スキルを作るべきとき

繰り返し使うプロンプトのすべてがスキルに値するわけではありません。判断の枠組みは次のとおりです。

スキルは Claude が常に手元に持っておく知識 のためのもの、スラッシュコマンドは 自分で明示的に起動するアクション のためのものです。どちらにするか迷ったら、「これは Claude が自動で適用すべきか、それとも実行するタイミングを自分で決めたいか」と問いかけてみてください。

よくある失敗: 週に一度しかしない作業のためにスキルを作ってしまうことです。私は git-rebase-helper というスキルを作りましたが、これが git 関連のプロンプトなら何にでも反応しました。rebase も merge も cherry-pick も、git status にまでです。description が広すぎたせいで、必要のない8割のセッションでコンテキストを汚し、2% のコンテキスト予算を他のスキルと奪い合っていました ¹。解決策は、そのスキルを削除してスラッシュコマンドに置き換えることでした。本当に必要になったときだけ /rebase を打てばよいのです。スキルに込めるべきは 安定したドメイン知識 であって、たまにしか出番のない作業手順 ではありません。

チュートリアル: コードレビュースキルを作る

ステップ 1: ディレクトリを作る

スキルは4か所のいずれかに置けます。スコープの広い順に並べると次のようになります ¹。

このチュートリアルでは個人スキルを作ります。

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

ステップ 2: frontmatter 付きの SKILL.md を書く

どのスキルにも SKILL.md ファイルが必要で、その中身は2つの部分に分かれます。スキルを いつ 使うかを Claude に伝える YAML frontmatter（--- で挟まれた部分）と、スキルが呼び出された ときに 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 以外にも、役に立つ frontmatter フィールドがあります ¹。

公式ドキュメントには注意書きが1つあります。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 を書く

description フィールドは、スキルの中で最も重要な一行です。内部では次のことが起きています。セッション開始時に、Claude Code はすべてのスキルの name と description を抜き出し、Claude のコンテキストへ注入します。そしてメッセージを送ると、Claude は 言語モデルの推論 によって——正規表現でもキーワード一致でも埋め込みの類似度でもなく——関連するスキルがあるかどうかを判断します。公式ドキュメントにはこうあります。「Claude は、どのスキルが関連するかを決めるために、あなたのタスクをスキルの description と照合します。description が曖昧だったり重なり合っていたりすると、Claude は誤ったスキルを読み込んだり、役立つはずのスキルを見落としたりすることがあります」 ¹。

Claude Code のソースコードを独立に解析した結果も、この仕組みを裏づけています。スキルの description はシステムプロンプトの available_skills セクションに注入され、モデルは通常の言語理解によって呼び出し時に関連するスキルを選びます ⁴。LLM ベースのマッチングであることは、description の書き方に大きく影響してきます。

悪い description:

description: Helps with code

これでは Claude はいつ起動すべきか分かりません。「Helps with code」はすべてに当てはまり、同時に何にも当てはまらないのです。しかもマッチングは LLM の推論なので、曖昧な description は予測できない起動を招きます。

もう少しましな description:

description: Review code for bugs and issues

まだ曖昧です。どんなバグでしょうか。どんな問題でしょうか。Claude が組み込みの分析ではなくこのスキルを使うべきなのは、どんなときでしょうか。

効果的な description:

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.

この description がうまく働くのは、次の要素を含んでいるからです。 - 何をするか: 具体的な問題の種類 についてコードをレビューする - いつ使うか: 変更の確認、PR、品質の分析 - トリガーとなる言葉: review、audit、check ——ユーザーが自然に打ち込む語

知っておきたい制約が1つあります。 すべてのスキルの description は共通のコンテキスト予算を分け合っており、その予算は「コンテキストウィンドウの 2% として動的にスケールし、フォールバックは16,000文字」です ¹。スキルの数が多いなら、それぞれの description を簡潔に保ちましょう。冗長な description は、限られた領域を他のスキルと奪い合うことになります。予算は SLASH_COMMAND_TOOL_CHAR_BUDGET 環境変数で上書きできますが ²、より良い対処は description を短く、より正確にすることです。

いろいろな description を試しましょう。 新しいセッションを開始し、コードのレビューを頼んで、スキルが起動するか確かめます。起動しなければ、トリガーとなる語句を増やします。起動してほしくない場面で起動するなら、description をもっと具体的にします。

ステップ 6: 使いながら改善する

1週間ほど使うと、次のようなことが見えてきます。 - スキルがチェックすべきなのにできていないパターン ——SKILL.md に追加しましょう - 無関係なタスクでの誤起動 ——description を絞り込むか、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 がコンテキストに応じて自動的に参照する知識ベースとなります。ジュニア開発者は、頼まなくてもシニアレベルの助言を受けられるのです。

スキルの数について一言: スキルが増えるほど、コンテキスト予算を奪い合う description も増えます ¹。起動しないスキルに気づいたら、/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

チームメンバーが pull すれば、スキルは自動的に手元に入ります。インストールも設定も要りません。git による配布は、チーム全体で専門知識を標準化する最も効果的な方法です。

共有スキルの指針: - プロジェクトスキルはドメイン知識（業務ルール、アーキテクチャのパターン）に絞る - 個人スキルはワークフローの好み（フォーマット、コミットのスタイル）にとどめる - そのスキルが存在する理由を SKILL.md の冒頭にコメントとして書く - スキルの変更も、他のコードと同じように PR でレビューする

要点

• コンテキストを説明し直している自分に気づいたら、スキルを作りましょう。 同じチェックリストを3回貼り付けたなら、それはスキルにすべきです。
• すべては description フィールドで決まります。 Claude は LLM の推論で、リクエストと description を照合します ¹。スキルの本文よりも description に時間をかけてください。
• allowed-tools で副作用を制限しましょう。 読み取り専用のスキルは Read、Grep、Glob に絞るべきです。
• プロジェクトスキルは git で共有しましょう。 設定ゼロで、チームに知識が行き渡ります ¹。
• 抽象化しすぎないこと。 細かなパターンごとにスキルを作ると、保守の負担が増える うえに コンテキスト予算の奪い合いも起きます。安定していて、再利用でき、維持する価値があるだけの知識にこそスキルを作りましょう。

よくある質問

Claude Code のスキルとは何ですか

スキルは markdown ファイルとして保存される、モデルが呼び出す拡張機能です。Claude がコンテキストに応じて自動的に見つけ、適用します。自分で明示的に起動するスラッシュコマンドとは違い、スキルは「今のタスクはこのスキルの description に合う」と Claude の LLM 推論が判断したときに起動します。セキュリティのパターン、コードスタイルの規則、業務ロジックといったドメイン知識をスキルに閉じ込めておけば、セッションをまたいで残り、毎回コンテキストを説明し直す必要がなくなります。

Claude Code のカスタムスキルはどう作りますか

個人用なら ~/.claude/skills/<name>/、プロジェクト単位なら .claude/skills/<name>/ の下にディレクトリを作ります。その中に SKILL.md ファイルを置き、YAML frontmatter（name、description、必要に応じて allowed-tools を含む）に続けて、Claude に適用してほしい専門知識を markdown で書きます。決定的に重要なのは description フィールドです。Claude はこのフィールドに対する LLM の推論で、スキルをいつ起動するかを判断します。手順を追った解説は上のチュートリアル全体をご覧ください。

Claude Code のスキルとスラッシュコマンドの違いは何ですか

スキルはコンテキストに応じて自動起動します。スキルの description に対する LLM の推論で、Claude が関連するかどうかを判断するからです。スラッシュコマンドは /command-name と入力して明示的に起動する、ユーザー主導のアクションです。Claude が常に持っておくべき知識（ドメイン知識、品質基準）ならスキルを、実行するタイミングを自分で決めたい場合（デプロイスクリプト、一度きりの作業手順）ならスラッシュコマンドを作りましょう。

Claude Code のスキルから他のツールを呼び出せますか

呼び出せます。ただし、どのツールを使えるかは allowed-tools frontmatter フィールドで制御します。コードレビュアーのような読み取り専用のスキルは、意図しない副作用を防ぐために Read, Grep, Glob へ制限すべきです。allowed-tools を省略すると、そのスキルは Claude が使えるあらゆるツールを使えてしまいます。また、スキルは frontmatter の中に独自のフックを定義でき、そのフックはスキルが動いているあいだだけ有効になります。

Claude Code のスキルが起動しないのはなぜですか

最もよくある原因は、description フィールドが曖昧すぎる、あるいは広すぎることです。Claude はキーワード一致ではなく LLM の推論で、そのスキルが今のタスクに関連するかを判断します。description が「helps with code」では、他のあらゆるコーディング作業と区別がつきません。description は具体的に書きましょう。対象となる問題の種類、起動してほしい場面、ユーザーが自然に打ち込む動詞を明示します。あわせてセッション中に /context を確認し、2% のコンテキスト予算の上限でスキルが除外されていないかを調べてください。多くのスキルが領域を奪い合うと、いくつかは落とされてしまいます。

Claude Code のスキルはどこに保存され、どう共有されますか

スキルはスコープの広がりに応じて4か所に置かれます。個人（~/.claude/skills/<name>/SKILL.md）、プロジェクト（.claude/skills/<name>/SKILL.md）、プラグイン、そして Enterprise（管理された設定）です。個人スキルは自分のすべてのプロジェクトに適用されます。プロジェクトスキルは git で共有され、チームメンバーが pull すれば設定ゼロで自動的に使えるようになります。すべてのスキルの description はコンテキストウィンドウの 2% という共通の予算を分け合うため、スキルが多いなら description は簡潔に保ちましょう。

参考文献