Claude Codeで実際に少しでも時間を使ったことがあるなら、きっと私が気づいたのと同じ問題に気づいているはずです。あなたは毎日おきに、同じ指示をプロンプトに書いています。「ここでは4スペースのインデントを使ってください。」「編集したら必ずリンターを実行してください。」「コミットメッセージはこの形式にしてください。」3回目か4回目くらいで、それはもはやプロンプトというより、「設定が足りない」感じがしてきます。
Claude Codeのスキルは、その問題を直します。スキルとは小さなフォルダのことで、中に1つのマークダウンファイルが入っています。そして、そのスキルは、あなたの依頼が本当にそれを必要とするときだけ、Claudeが会話に取り込む仕組みです。セットアップ画面もありません。プラグインマネージャもありません。フォルダ内のファイルと、それが何のためのものかをClaudeに伝える1行の説明だけです。
この記事は2026年向けの、きれいなウォークスルーです。スキルとは実際に何か、最初のスキルの書き方、置き場所、そしてよく混同される2つのもの——スラッシュコマンドとサブエージェント——との比較を説明します。
Claude Codeのスキルとは実際に何か
最も基本的なレベルでは、スキルはSKILL.mdという名前の1つのファイルが入ったディレクトリです。そのファイルには2つの部分があります。
- 先頭に短いYAMLフロントマターがあり、
nameとdescriptionが含まれます。 - その下に続くMarkdown本体で、スキルがトリガーされたときにClaudeが従う指示が書かれます。
それが仕様のすべてです。それ以外のもの——例、サポート用スクリプト、テンプレート、ヘルパーファイルなど——は任意で、同じディレクトリ内に置かれます。
これがあなたが書ける最小の有効なスキルです：
.claude/skills/run-tests/
└── SKILL.md
---
name: run-tests
description: "Run the project's test suite using the Makefile target. Use this whenever the user asks to run tests, check tests, or verify the test suite is passing."
---
Run `make test` from the repo root. If the command fails, read the failing test
output, point out the specific assertion that broke, and ask before changing
anything in the source files.
これは動作するスキルです。これを.claude/skills/run-tests/に入れて、Claude Codeを再起動し、「テストを実行して」と次にあなたが言ったとき、Claudeは推測ではなくこのスキルを使います。
Claudeは実際にどうやってスキルを取り込むのか
ここが最も混乱しやすいポイントです。スキルは常に有効というわけではありません。自動で発見されます。
あなたがメッセージを送るときに起きることは以下の通りです：
- Claudeは、見える範囲のすべてのスキルの説明を読み取ります。
- それらの説明と、あなたのメッセージを照合します。
- 一致した場合、そのスキルの全文が会話に取り込まれます。
- 一致するものがなければ、スキルは読み込まれず、デフォルトの動作になります。
これが、descriptionがどんなスキルでも実質的に大部分の仕事をする理由です。Claudeがスキルに適用すべきかどうかを判断するために持っているのは、それだけだからです。曖昧な説明（「テストを手伝う」）は、ほとんど発火しません。具体的な説明（「ユーザーがテストを実行、チェック、または検証するよう求めたときに、pytestのテストスイートを実行する」）は、確実に発火します。
簡単なテスト：説明文を声に出して読んでください。明確な動詞で始まり、明確なトリガーで終わらないなら、書き直しましょう。
スキルの置き場所
スキルは3つの場所のどれかに置かれます。置き場所によって、誰がそれを見るかが決まります。
| 場所 | スコープ | いつ使うべきか |
|---|---|---|
.claude/skills/<name>/ リポジトリ内 |
プロジェクト | 特定のコードベースに固有のワークフロー |
~/.claude/skills/<name>/ 自分のホームディレクトリ内 |
パーソナル | どこでも使いたいワークフロー |
| プラグイン、または共有パッケージ | チーム | 他の人にも配布したいスキル |
プロジェクトのスキルは競合時に勝ちます。つまり、あなたのリポジトリにrun-testsスキルがあり、個人用のフォルダにも同じものがある場合は、そのリポジトリ内にいる間はプロジェクト側のスキルが使われます。これはほとんどの場合、望んでいる挙動です。
小さいけれど重要な詳細：リポジトリ内に置かれたスキルは、デフォルトでgitにコミットされます。これで問題ありません。通常は短く、すべての共同作業者の助けになり、長いCLAUDE.mdファイルよりレビューしやすいからです。
ウォークスルー：ゼロからスキルを作る
run-testsより少しだけ役に立つものを書いてみましょう。仮に、すべてのコミットメッセージをConventional Commitのタイプ（feat:、fix:、chore:）で始めるという個人的な習慣があるとします。あなたは、Claudeがコミットするときも同じことをしてほしい。
Step 1: ディレクトリを作成する
プロジェクトのルートから：
mkdir -p .claude/skills/conventional-commit
Step 2: SKILL.mdを書く
.claude/skills/conventional-commit/SKILL.mdを開き、以下を入れます：
---
name: conventional-commit
description: このスキルは、ユーザーがgit commitを求めたとき、変更をコミットするとき、またはコミットメッセージを書かせたいときはいつでも使ってください。メッセージはConventional Commit形式で書かれます。
---
git commitを作成するときは、次のルールに従ってください。
1. 件名の行を次のいずれかで始めます：feat, fix, chore, docs, refactor, test, perf.
2. コロンとスペースを追加し、その後に短い命令形の要約を書きます。ピリオドは不要です。
3. 件名は70文字未満に保ちます。
4. 変更が2つ以上のファイルにまたがる場合は、「なぜそうするのか」を1行で書いたボディを追加します。
例：
feat: add IndexNow ping to publish workflow
mainへのすべてのプッシュのたびにBingに自動通知し、新しい投稿がより早くインデックスされるようにします。
Step 3: 試してみる
Claude Codeを再起動する（または新しい会話を開くだけでOKです）。「commit these changes」と言ってください。Claudeはスキルを取り込み、フォーマットに従い、ルールに一致するコミットのサブジェクトが表示されるはずです。
発火しない場合、まず直すべきなのは説明文です。トリガーワードが、実際にClaudeへ言う内容と一致するようにしてください。
Skills vs slash commands vs subagents
これが私が最も頻繁に受ける質問で、しかも3つの機能は時間とともにかなり近づいてきたため、線引きがあいまいになっています。実際にはこう考えています。
Skills
- 自動で発見されます。Claudeが、あなたのメッセージに基づいていつ使うかを判断します。
- メインの会話の中に存在するため、作業内容が見えるままで、介入もできます。
- 最適: コミットのフォーマット、テストの実行、PRの慣習のように、繰り返し行うもののうち、毎回タイプしたくないワークフロー。
Slash commands
/command-nameで、手動で呼び出します。- スキルと同じファイル形式です。実際、1つのスキルファイルがあれば、自動トリガーと、無料で
/run-testsのようなslashコマンドの両方を得られます。 - 最適: 何かを実行するタイミングを完全に制御したいときの明示的なトリガー。
Subagents
- Claudeによって、別の新しいコンテキストで（それぞれ独自のツールとメモリを用いて）スポーンされます。
- あなたの会話は見ません。Claudeから簡単な指示を受け取り、結果を報告します。
- 最適: メインのコンテキストに置いておきたくない、重い作業やうるさい作業。例えばリポジトリ全体の検索、長い評価の実行、大きな差分の要約など。
役立つ目安です。作業が小さく、あなたの目の前に置いておくべきならスキルです。作業が大きく、サイドのプロセスとして実行すべきならサブエージェントです。入力としての明確な起点（typed entry point）を特に望むならslashコマンドです。
サブエージェント側の詳細は、このサイトのhooksガイドで扱っています。スキルベースのワークフローと相性のよい、シェルレベルのライフサイクルについて説明しています。
Three small skills that pay for themselves
これらは、私のほとんどのリポジトリに入れているスキルです。どれも賢さを競うものではありません。全部、実際に時間を節約してくれます。
1. lint-after-edit
---
name: lint-after-edit
description: プロジェクトのリンターを、コードの編集のたびに実行します。ユーザーがClaudeに編集、リファクタ、修正、ソースファイルの変更を依頼したときはいつでも使用します。
---
After completing any edit to a .ts, .tsx, .js, or .py file, run `npm run lint`
(or `ruff check .` for Python). If the lint fails, fix the warnings before
reporting that the edit is done.
これが機能する理由は、「ソースファイルを編集すること」が非常に一般的なトリガーだからです。このスキルはほぼ毎回のコーディングセッションで発火し、リント失敗がコミットに紛れ込むのが見えなくなります。
2. pr-description
---
name: pr-description
description: 現在のブランチのコミットからプルリクエストの説明文を書きます。ユーザーがPRの説明、PR本文、またはプルリクエストの要約を求めたときはいつでも使用します。
---
Read `git log main..HEAD` and write a PR description in this format.
## Summary
One short paragraph, no marketing language.
## Changes
- One bullet per logical change, not per commit.
## Test plan
- A checklist a reviewer can run.
Do not include emojis, do not start lines with "This PR".
「〜しないで」という行が重要です。否定の指示は、Claudeがデフォルトへ戻ってしまうのを止めるためのものです。
3. clean-imports
---
name: clean-imports
description: 未使用のimportを削除し、残りを並べ替えます。ユーザーがimportをクリーンアップ、importの並べ替え、またはファイル内のimport整理を依頼したときはいつでも使用します。
---
For each file the user asks to clean:
1. Remove imports that are not referenced anywhere in the file.
2. Sort what remains by: standard library, then third-party, then local.
3. Group each section with a blank line between them.
Do not touch import side effects (imports with no name).
スキル、slashコマンド、自動トリガーが1つのファイルに全部入っています。内容は同じ。呼び出し方が3通りあるだけです。
Best practices that actually matter
私自身とクライアントのために何十個もスキルを書いた後、際立つ3つのルールがあります。
One skill, one job
最もよくあるミスはメガスキルです。コミット、PR、ブランチ命名、そしてチェンジログ更新を一度に扱おうとする、単一のSKILL.mdです。メガスキルは読み込みが遅くなり、発火もより信頼できなくなり、2つの部分が衝突したときClaudeを混乱させます。分割してください。スキルは1画面に収まるべきです。
Write the description like a trigger, not a label
悪い例:
A skill for working with tests.
良い例:
Run the project's pytest suite when the user asks to run tests, check tests, or verify the test suite is passing.
良い方は、Claudeが見つける必要のある動詞名を挙げています。 「Run」「check」「verify」——これらは、ユーザーが実際にタイプする言葉です。
Keep instructions imperative
ドキュメントのように読めるスキル（「このスキルは〜を担当しています…」のようなもの）は、指示のように読めるスキル（「Xを実行。次にY。もしZならWを実行。」のようなもの）よりも、発火の信頼性が低くなります。直接的な動詞は、アクションへきれいに対応します。
Resist the urge to over-script
スキルフォルダ内にPythonやシェルスクリプトを同梱して出荷することもできますし、場合によってはそれが正しいこともあります。しかし多くのワークフローでは、素のMarkdownの指示で十分で、保守もしやすいです。スクリプトは、本当に決定論的（deterministic）な作業に対して使ってください。単に「できるから」という理由では使わないでください。
Common mistakes
私が何度も何度も見かける、いくつかのパターンです。
- 説明が抽象的すぎる。 もし「〜を手伝うスキル」から始まっているなら、めったに発火しません。動詞から始まるように書き換えてください。
-
スキルが間違ったフォルダにある。
~/.claude/skills/は、すべてのプロジェクトにまたがる個人用スキルの置き場です。.claude/skills/は、現在のプロジェクト専用です。これを取り違えることが、「スキルがピックアップされない」最も一般的な理由です。 - CLAUDE.mdを置き換えようとしている。 スキルは、繰り返し発生する、トリガー型のワークフローのためのものです。CLAUDE.mdは、プロジェクトの慣習のような常時オンのコンテキストのためのものです。両者は補完し合います。
- Claude Codeの再起動を忘れている。 スキルはセッション開始時に読み込まれます。会話の途中で追加した場合は、そのセッションを終了して新しいセッションを開始してください。
- 秘密情報をSKILL.mdの中に入れている。 多くのセットアップでは、スキルはgitにコミットされます。設定情報ではなく、ソースコードのように扱ってください。
Frequently asked questions
プロジェクトスキルは具体的にどこへ置きますか？
返却形式: {"translated": "翻訳されたHTML"}あなたのリポジトリ内の .claude/skills/<skill-name>/SKILL.md にあります。このフォルダは、無視しない限り git にコミットされます。
これはスラッシュコマンドとどう違いますか？
スキルファイルはスラッシュコマンドです。同じファイルが、自動検出と /skill-name の呼び出しの両方を提供します。スラッシュコマンドは手動での入口です。スキルは、その同じ仕組みの自動検出側です。
サブエージェントとはどう違いますか？
サブエージェントは、まったく新しく隔離されたコンテキストで実行されます。スキルは、現在の会話の中で動作します。目の前の作業をそのまま進めたいときはスキルを使います。作業を切り離して任せたいときはサブエージェントを使います。
スキルを追加したあと、Claude Code を再起動する必要がありますか？
はい。新しいスキルはセッション開始時に取り込まれます。会話を終了して、新しく開き直して読み込んでください。
スキルは外部スクリプトを使えますか？
はい。スキルフォルダにシェルや Python のスクリプトを含めて、SKILL.md からそれらを参照できます。ほとんどのワークフローでは、プレーンな Markdown の指示だけで十分です。
これは Claude Chat でも動きますか？それとも Claude Code だけですか？
同じ SKILL.md 形式が、Claude Code、Claude Chat、Claude Cowork のすべてで機能します。それぞれの製品は自分自身の場所にあるスキルを探しますが、ファイル形式は同一です。
スキルは CLAUDE.md に入れるべきですか？
いいえ。CLAUDE.md は、常時有効なプロジェクトコンテキスト用です。スキルは、トリガーされたワークフロー用です。すべてのワークフローを CLAUDE.md に読み込むと、メインコンテキストが膨らんでモデルが遅くなります。
最後にひとこと
スキルが重要なのは、それが賢いからではありません。同じことを毎日 Claude に伝えるという、小さくて繰り返し発生する面倒を取り除いてくれるからです。良いスキルは短く、的確で、ほとんど見えないようなものです。作業が、あなたの望んだ形でそのまま進むので、気にする必要がなくなります。
まず 1 つから始めましょう。思いつく中でいちばん小さいものです。コミット形式、lint ルール、PR テンプレート。うまく動き始めたら、次のものを書きます。1、2 週間もすると、プロジェクトで Claude がどう振る舞うかを静かに形作っている小さなファイルのフォルダができ、そのことなしにどうやってやっていたのか不思議に思うでしょう。
もし シェルレベルの強制のための hooks で Claude Code を拡張したり、よりリッチな連携のために MCP サーバーを構築したりするなら、スキルはそのちょうど間に位置します。サーバーより軽く、hook より柔軟で、どちらよりもチームで共有しやすいのです。
