Claude Code のカスタムスキルの作り方（実際に動く実例つき）

この記事は Claude Code CLI にもとづいています。スキルは進化の速い機能であり、細部は変わる可能性があります。出典は末尾に記載します。

Claude Code のカスタムスキルとは？（かんたんな定義）

カスタムスキルとは、命令をまとめたパッケージ、つまりフォルダと SKILL.md ファイルのことで、繰り返し行うワークフローをあなたの望むとおりに Claude Code に実行させるものです。「このブログ記事を標準 X に整形して、目次を追加して、メタを書いて…」という長いプロンプトを毎回入力し直す代わりに、そのレシピを一度スキルとしてパッケージ化します。それ以降、Claude Code はいつ使うべきかを認識し、あなたの手順に従います。

初心者はスキルを別の2つのものと混同しがちなので、手早く区別しておきましょう。

• スキル - コンテキストがあなたの description に一致したときに Claude Code が自動的に呼び出す知識またはワークフローです。コマンドは一切入力しません。
• スラッシュコマンド - あなたが意図的に入力するショートカットです（たとえば /commit）。詳しくは Claude Code のスラッシュコマンドをご覧ください。
• サブエージェント - 重いタスクを独自の別コンテキストで実行する「サブアシスタント」です。サブエージェントガイドをご覧ください。

4つの概念がまだ混ざってしまう場合は、skills vs subagents vs hooks vs MCP の記事でより丁寧に整理しています。そもそもスキルが何なのかがまだはっきりしないなら、まず Claude Code のスキルとは何かを読み、それからここに戻って実際に作ってみてください。この記事は、Claude Code CLI で実際にスキルを動かすことだけに100%集中しています。

スキルはどう動くのか？（プログレッシブ・ディスクロージャー）

この仕組みを理解すれば、最初から正しくスキルを書けます。Claude Code は、すべてのスキルの全内容をコンテキストに詰め込むことはしません。それではトークンを浪費し、ノイズが増えるからです。代わりにプログレッシブ・ディスクロージャー（必要に応じた読み込み）を、3つの層にわたって使います。

• 第1層 - 常駐: Claude Code は各スキルの name と description だけをコンテキストに保持します。これは、どんなスキルが存在し、何のためのものかを示す「道しるべ」です。
• 第2層 - 一致時に読み込み: 会話のコンテキストが description に一致したときにのみ、SKILL.md の本文がコンテキストに読み込まれます。
• 第3層 - 必要時に読み込み: reference.md や scripts/ のような補助ファイルは、Claude が実際に必要としたときにだけ開かれます。

もっとも重要な帰結はこうです。description こそが自動呼び出しのスイッチです。 description に、ユーザーが実際に口にするコンテキストのキーワードが含まれていなければ、本文がどれほどよく書けていても、Claude Code はスキル本文を開いて読むことは決してありません。「動かない」スキルの多くが、内容ではなく description の行で失敗するのはこのためです。

セットアップ：スキルの置き場所（個人用 vs プロジェクト用）

ここは、多くの英語のチュートリアルが飛ばしてしまう部分です。なぜなら、それらは claude.ai の Web アプリの話をしているからです。Claude Code CLI では、スキルはファイルシステム上に存在し、目的に応じて置き場所が2か所あります。

シンプルなルールはこうです。自分自身のワークフローは ~/.claude/skills/ へ、チームやプロジェクト全体の規約はリポジトリ内の .claude/skills/ へ置き、それを git にコミットして全員に行き渡らせます。

唯一の前提条件は、Claude Code がインストールされていることです（まだなら Claude Code インストールガイドをご覧ください）。既存のスキルは、Claude Code のセッション内で直接たずねる（たとえば「今持っているスキルを一覧にして」というプロンプト）か、~/.claude/skills/ フォルダを開くことで確認できます。新しいスキルを作ったら、スキャンさせるために再起動を忘れないでください。

カスタム Claude Code スキルを5ステップで作る方法

これが全体のワークフローです。全体を通して1つの実例、つまり生の Markdown ブログ記事を整える blog-formatter スキルを使うので、イメージしやすいはずです。ただしこのやり方はどんなワークフローにも応用できます。

ステップ1 - 繰り返せるワークフローを1つ選ぶ

まだ手作業でやったことのないもののためにスキルを書こうと急がないでください。実践的なコツ：まずは Claude Code と手作業で数回やってみて、望むとおりの結果が出るようになってから、そのプロンプト／ワークフローをスキルに結晶化させましょう。良いスキルとは、証明済みのプロセスの結晶であって、当て推量ではありません。

始めるのに良い候補をいくつか挙げます。ブログ記事を自分の標準に整形する、プロジェクトの規約に沿ったコミットメッセージを生成する、既存のテンプレートからユニットテストを書く、API ドキュメントをレビューする、などです。少なくとも週に1回はやることを選びましょう。そこにこそ ROI が現れます。

ステップ2 - フォルダツリー + SKILL.md ファイルを作る

最小限のスキルに必要なのは、フォルダと SKILL.md ファイルだけです。補助ファイルは必要になったときに追加します。完全なフォルダツリーは次のようになります。

~/.claude/skills/
 blog-formatter/
 SKILL.md # required - the main instructions
 reference.md # optional - long details, loaded on demand
 scripts/
 format.py # optional - a bundled script

ターミナルからフォルダを作成します。

mkdir -p ~/.claude/skills/blog-formatter
cd ~/.claude/skills/blog-formatter

フォルダには、スキルが何をするかを短く的確に表す kebab-case の名前を付けます（blog-formatter、commit-msg）。小さなスキルなら SKILL.md 1つで十分です。本文が長くなってきて初めて、reference.md や scripts/ に分割しましょう。

ステップ3 - YAML フロントマターを書く（name + description）

SKILL.md を開きます。いちばん上に、2本の --- 行にはさまれた YAML フロントマターのブロックがあり、必須フィールドが2つ、name と description が入ります。ここはスキルが自動呼び出しされるかどうかを決める部分なので、慎重に書きましょう。

良い description の公式：何をするか + いつ使うか + トリガーとなるキーワードで、ユーザーが実際に口にする言葉を入れます。比べてみましょう。

左側はあいまいで、コンテキストがなく、Claude はいつ呼べばよいのか見当もつきません。右側は、何を・いつ・そしてユーザーが入力しがちな具体的なフレーズまで明示しています。description は、新しい同僚に「こういうときに自分のところに来て」と伝えるつもりで書きましょう。

ステップ4 - 命令の本文を書く

フロントマターのすぐ下が Markdown 本文で、これはスキルが呼び出されたときに Claude Code が読んで従うワークフローです。良い本文には次を含めるとよいでしょう。

• 目的 - このスキルがどんな問題を解決するか。
• いつ使うか - コンテキストを再掲する（description を補強します）。
• たずねるべき入力 - 情報が足りないとき、ユーザーに何を聞くか。
• 手順 - 明確で番号付きの手続き。
• 出力の基準 - 正しい結果がどんなものか。
• 避けるべき間違い + 入力／出力の例。

黄金律：簡潔さが肝心です。ふくれ上がった本文はコンテキストを浪費し、Claude の気を散らします。命令が長くなったら（参照テーブルや多数の例など）、reference.md に分割して本文から参照させましょう。プログレッシブ・ディスクロージャーのおかげで、補助ファイルは必要なときだけ読み込まれます。

ステップ5 - スキルを再読み込み & テストする

Claude Code は起動時にスキルフォルダをスキャンします。そのため SKILL.md を作成・編集したら再起動が必要です。/exit と入力して Claude Code のセッションを開き直します。それから description に合った自然なプロンプトでテストします。たとえば 「draft.md のブログ記事を整形して」のように。うまく書けていれば、Claude Code はそれを認識して blog-formatter スキルを呼び出します。正しいスキルが使われたことを確認し（Claude はどのスキルが呼ばれたか通常報告します）、次にその結果がステップ4で定めた基準を満たしているか確かめます。

完全なカスタムスキルの例（コピペして実行）

これは私が実際に書いて使っている完全な SKILL.md です。そのまま ~/.claude/skills/commit-msg/SKILL.md にコピーし、再起動して、すぐ試してみてください。

---
name: commit-msg
description: Generate a Conventional Commits message from the currently staged changes. Use when the user says "write a commit", "commit message", "make a commit message", or right before committing code.
---

# Generate a Conventional Commits message

## Purpose
Read the staged diff and write a short, standards-compliant commit message.

## When to use
When the user is about to commit or asks for a commit message.

## Inputs to ask for
If nothing is staged, run `git diff --staged` to see the changes.
If it's still empty, ask the user: "Have you run `git add` yet?"

## Steps
1. Run `git diff --staged` to read the changes.
2. Determine the type: feat / fix / docs / refactor / test / chore.
3. Determine the scope (the main module/folder changed).
4. Write the subject line: `type(scope): short description` - max 72 chars, present tense.
5. If the change is complex, add 1-3 bullet points in the body explaining "why".

## Output standard
- Subject ≤ 72 chars, no trailing period.
- Description is clear and matches what was actually done.
- Do NOT invent changes that aren't in the diff.

## Mistakes to avoid
- Don't use the wrong type (adding a feature but labeling it `fix`).
- Don't write vague messages like "update code", "misc fixes".

## Example
Input diff: add an email validation function in `src/auth/`.
Output:
feat(auth): add email format validation on signup

実際の結果：読み込まれてしまえば、あとは「write a commit」と入力するだけで、Claude Code は git diff --staged を実行し、正しく分類し、規約に準拠したメッセージを返してくれます。毎回この規約を言い直す必要はありません。

観察された制約が1つ（正直に）：差分が巨大だったり、複数種類の変更が混ざっていたりすると、まとめられたメッセージが最適とは言えない type を選ぶことがあります。そのときはやはり、コミットを分割するか手作業で直すべきです。このスキルは9割のケースを仕留めますが、あなたの判断をすっかり置き換えるものではありません。

スキルが発火しないときのテスト & デバッグ

完成したスキルを Claude Code が「無視する」のはよくあることです。スキルが発火しないとき、私が順番に確認するチェックリストがこれです。

1. YAML の構文エラー。 --- の欠落、インデントの誤り、フロントマター内の余計な文字があると、スキル全体が黙ってスキップされます。まずはフロントマターのブロックを確認しましょう。
2. あいまいな description／コンテキストのキーワード不足。 これが第一の原因です。プロンプトに description と重なるフレーズがまったくなければ、スキルは呼ばれません。実際のユーザーが言うであろう正確な言葉を加えましょう。
3. Claude Code を再起動していない。 スキルフォルダは起動時にしかスキャンされません。編集後は /exit して開き直す必要があります。
4. 名前の重複、またはパスの誤り。 name が同じスキルが2つあったり、SKILL.md が間違ったフォルダにあったり（大文字小文字の不一致、階層の誤り）すると読み込まれません。
5. 本文が長すぎてノイズになる。 ふくれ上がった本文は、Claude が手順に従うのを難しくします。削り込んで、あふれた分は reference.md に移しましょう。

手早い切り分けのコツ：手動で強制的に呼び出して問題を切り分けます。直接こうプロンプトします。「blog-formatter スキルを使ってこれをやって」。強制呼び出しが問題なく動くなら、バグは description にあります（自動呼び出しできない）。強制呼び出しでも失敗するなら、バグは YAML かパスにあります。

スキルを共有 & 公開する

良いスキルを書いたら共有すべきです。そしてこれは、英語のチュートリアルがほとんど扱わない部分です。シンプルなものから少し丁寧なものまで、3つの方法があります。

1. チーム全体のためにリポジトリへコミットする。 スキルをプロジェクト内の .claude/skills/ に置いて git commit します。リポジトリをクローンした人は誰でもすぐそのスキルを手に入れます。チームでプロセスを標準化する最速の方法です。
2. コミュニティのために GitHub へプッシュする。 スキルのリポジトリを作れば、ほかの人がそれをクローンしたり、スキルフォルダを自分の ~/.claude/skills/ にコピーしたりできます。各スキルが何をするかを説明する README を付けましょう。
3. プラグインとしてパッケージ化する。 関連するスキルが複数あるなら、それらをまとめてプラグインにすると配布がすっきりします（Claude Code プラグインについて別の記事があります）。

おまけ：スキルはオープンな標準（Markdown + YAML フロントマター）を使っているので、Claude Code 向けに書いた SKILL.md は、Cursor や Copilot のような他のツールでもそのまま使えたり、簡単に変換できたりすることがよくあります。一度書けば、多くの場所で使えます。

自分で書きたくない？ 108以上のビルド済みスキルを使う

自分でスキルを書くこと自体、学ぶ価値のあるスキルです。自分のワークフローにぴったり合わせられる完全なコントロールが手に入りますし、Claude Code を本気で使うすべての人にお勧めします。とはいえ、一つひとつ自分で作らずに、今すぐ本番で使えるスキルセットが欲しいなら、Engineer Kit は60以上のビルド済みスキルを提供します（フロントエンド、バックエンド、データベース、DevOps、コードレビュー）。検討する価値のある近道です。

近道を選ぶ： AgentKit のビルド済みスキルバンドル — 現在 $149（元 $198）は、Claude Code 向けの108以上のスキルをまとめており、ファイルを一つひとつ書く代わりにすぐ使えます。正直に言うと：専門的な部分をカスタマイズするために、（この記事のように）スキルの書き方はやはり知っておくべきです。キットは繰り返しの下地仕事を引き受けてくれます。

よくある質問（FAQ）

スキルとサブエージェントは何が違いますか？

スキルは、コンテキストが一致したときに Claude Code が現在のコンテキストに読み込む命令のパッケージで、同じセッション内で動きます。サブエージェントは、重いタスクを独自の別コンテキストで独立して実行するサブアシスタントです。軽く繰り返す作業はスキルへ、隔離が必要な大きな作業はサブエージェントへ回します。

SKILL.md はどこに置きますか？

すべてのプロジェクトで使いたい（個人用）なら ~/.claude/skills/<name>/SKILL.md に、コミットしてチームと共有したい（プロジェクト用）ならリポジトリ内の .claude/skills/<name>/SKILL.md に置きます。各スキルは、SKILL.md ファイルを含むそれぞれのフォルダになっています。

なぜ自分のスキルが自動的に動かないのですか？

たいていは description があいまいで、プロンプトで実際に口にするキーワードが欠けているからです。あわせて確認しましょう。YAML フロントマターに構文エラーがないか、Claude Code を再起動したか、フォルダのパスは正しいか。

スキルを作成・編集したあと、再起動は必要ですか？

はい。Claude Code はスキルフォルダを起動時にしかスキャンしないので、SKILL.md を作成・編集したあとは、スキルを読み込ませるために /exit してセッションを開き直す必要があります。

Claude Code 向けに書いたスキルは claude.ai でも使えますか？

スキルの標準（Markdown + YAML フロントマター）はオープンなので、内容はたいてい再利用できます。ただし読み込み方は異なります。Claude Code はローカルのファイルフォルダ（~/.claude/skills/）を使いますが、claude.ai の Web アプリは独自の方法で読み込みます。SKILL.md ファイルは再利用できる資産として扱いましょう。どこでもそのまま同一に使えるものではありません。

すぐ使える出来合いのスキルはありますか？

あります。ゼロから始めたくないなら、AgentKit のようなキットが、多くの領域にわたる Claude Code 向けの108以上のスキルをまとめています。カスタマイズのために自分で書く方法は知っておくべきですが、キットは繰り返しの下地仕事を省いてくれます。

まとめ + 次のステップ

カスタムスキルは、プロンプトを繰り返すことなく、あなたのぴったりの基準で動くように Claude Code を「教える」もっとも効果的な方法です。小さく始めましょう。毎週やるワークフローを1つ選び、SKILL.md に結晶化させ、本当に明確な description を書き、テストして、反復します。基礎をしっかり押さえるには次に Claude Code のスキルとは何かを読み、意図的なショートカットとスキルを組み合わせるには Claude Code のスラッシュコマンドを読んでください。そして、一つひとつ書く代わりに今すぐ本番で使えるスキルセットが必要なら、ビルド済みキットを検討しましょう（下のボックスを参照）。

出典：Claude Code Docs - Skills（Anthropic、2026年更新）、SKILL.md の構造と読み込みの仕組みについて。スキルは進化途上の機能であり、バージョン間で細部が変わる可能性があります。