はじめに
Claude Codeを使い始めて数週間たつと、こんな場面が増えてきませんか。
- 「テストを先に書いてから実装して」「コミットメッセージはこの形式で」と、毎回同じ前置きを打ち込んでいる
- 前置きをCLAUDE.mdに書き足していったら、ファイルが長くなりすぎて何が書いてあるか自分でも分からなくなった
- 同僚に「この手順でやると上手くいくよ」と伝えたいのに、手順書がチャットログの中にしかない
こうした「繰り返し伝えている手順」をひとまとまりのファイルにして、必要なときだけClaudeに読ませる仕組みがスキル（Agent Skills）です。
この記事では、スキルを一度も作ったことがない方を想定して、次のことを順に説明します。
- スキルとは何か、CLAUDE.mdやカスタムコマンドと何が違うのか
- 実際に1つ作って動かすまでの手順（公式ドキュメントと実機で検証済み）
- フロントマターの各項目と、配置場所ごとの優先順位
- 組み込みスキルと、少し進んだ使い方
- 大手企業・団体が公開している信頼できるスキル集と、その導入方法
- 起動しないときの切り分け方
本文の仕様はすべて2026年9月17日時点の公式ドキュメント（code.claude.com、agentskills.io）に基づき、コマンドはClaude Code v2.1.274で動作を確認しています。仕様は頻繁に更新されるため、迷ったら記事末尾の公式リンクを正としてください。
まず、スキル導入前後で何が変わるのかを1枚の図で確認しておきます。
図1: 左が導入前、右が導入後。右側のように、手順は1つのファイルに集約され、必要なときだけ読み込まれます。（静止画版）
スキルとは何か（30秒版）
スキルの実体は、SKILL.mdという名前のMarkdownファイルを1つ含むフォルダです。Claude Codeはこのフォルダを見つけると、SKILL.mdの先頭にある「名前」と「説明」だけを先に読み、あなたの依頼がその説明に合致したときに本文全体を読み込んで、書かれた手順に従います。
公式ドキュメントでは、スキルを作るべき場面を「同じ指示・チェックリスト・複数ステップの手順をチャットに貼り付け続けているとき」「CLAUDE.mdの一部が事実ではなく手順になってきたとき」と説明しています。CLAUDE.mdとの最大の違いは読み込まれるタイミングで、CLAUDE.mdは毎回すべて読み込まれるのに対し、スキルの本文は使われるときにしか読み込まれません。長い手順書を持たせても、使わない間はほとんどコストがかからないのが利点です。
図2: 公式ドキュメント「Extend Claude with skills」（code.claude.com）。2026年9月17日時点の画面です。
なお、以前あった「カスタムスラッシュコマンド（.claude/commands/）」は、現在はスキルに統合されています。.claude/commands/deploy.mdと.claude/skills/deploy/SKILL.mdはどちらも/deployコマンドを作り、同じように動きます。既存のコマンドファイルはそのまま使えますが、新しく作るならスキル形式が推奨されています。スキルには補助ファイルを同じフォルダに置ける、誰が起動できるかを制御できる、Claudeが自動で読み込めるといった追加機能があるためです。
まず1つ作って動かす
理屈より先に、手を動かして「起動する感覚」をつかむのが早道です。ここでは、直近のコミット履歴からリリースノートの下書きを作るrelease-notesスキルを作ります。書籍やドキュメントによくあるテスト駆動開発の例とは別に、Gitさえあればどのプロジェクトでも試せる題材を選びました。
前提
- Claude Code v2.1.x がインストール済み（
claude --versionで確認できます） - Gitリポジトリになっているプロジェクトフォルダ（コミットが数件あるとよいです）
手順
- スキル用のフォルダを作ります。プロジェクト専用にするなら、プロジェクト直下で次のコマンドを実行します。
# プロジェクト直下で実行（このリポジトリだけで使うスキル）
mkdir -p .claude/skills/release-notes
自分のすべてのプロジェクトで使いたい場合は、代わりに個人用の場所に作ります。
# 個人用（自分の全プロジェクトで使えるスキル）
mkdir -p ~/.claude/skills/release-notes
- 作ったフォルダの中に
SKILL.mdを作成し、次の内容を保存します。
---
name: release-notes
description: 直近のコミット履歴からリリースノートの下書きを作成する。「リリースノート」「変更点をまとめて」「更新履歴」と言われたときに使う。
argument-hint: [since-tag]
allowed-tools: Bash(git log *) Bash(git tag *)
---
## 対象のコミット
!`git log --oneline -20`
## 手順
1. 上のコミット一覧を「新機能」「改善」「バグ修正」に分類する
2. 利用者向けの言葉で1行ずつ書き直す（内部のファイル名は書かない）
3. `## リリースノート` の見出しで Markdown として出力する
- 構文に問題がないか、Claude Codeのコマンドで検証します。v2.1.233以降で使えます。
claude plugin validate .claude/skills
以下は、この記事のために実際に作成して検証した結果です。
図3: 実際の実行結果。√ Validation passedと表示されれば、フロントマターの構文は問題ありません。
- Claude Codeを起動して、2通りの方法で呼び出します。
# 方法A: スラッシュコマンドで直接呼び出す（必ず起動する）
/release-notes
# 方法B: 説明文に合う言い方で頼む（Claudeが判断して自動で起動する）
直近の変更点をリリースノートにまとめて
方法Bで起動したかどうかは、Claudeの応答にSkill(release-notes)のような表示が出るかで確認できます。起動しない場合は、後述のトラブルシューティングを参照してください。
ここで何が起きているか
上のSKILL.mdには、初心者が最初に覚えておくと便利な仕掛けを3つ入れています。
| 書いた場所 | 仕掛け | 効果 |
|---|---|---|
本文の!`git log --oneline -20` |
動的コンテキスト注入 | Claudeが本文を読む前にこのコマンドが実行され、結果が本文に差し込まれます。Claudeは推測ではなく実際のコミット一覧を見て作業します |
allowed-tools: Bash(git log *) Bash(git tag *) |
ツールの事前承認 | このスキルを起動したターンの間、git logとgit tagは確認プロンプトなしで実行できます。次のメッセージを送ると許可は解除されます |
argument-hint: [since-tag] |
引数のヒント | /release-notesと入力したときの補完に「[since-tag]」と表示されます |
起動までの流れを図にすると次のようになります。
図4: 経路Aは必ず起動し、経路BはClaudeが説明文と依頼を照合して判断します。どちらの経路でも、その後の処理は同じです。（静止画版）
なぜコンテキストを圧迫しないのか
スキルの設計で一番重要なのが、3段階に分けて読み込むという考え方です。オープン仕様（agentskills.io）ではこれを「progressive disclosure（段階的な開示）」と呼んでいます。
図5: 常時読み込まれるのはフロントマターだけです。本文は起動時、補助ファイルは本文から参照されたときに初めて読まれます。（静止画版）
公式ドキュメントと仕様に書かれている目安をまとめます。
| 段階 | 読み込まれるもの | タイミング | 目安 |
|---|---|---|---|
| 1 | フロントマター（name、descriptionなど） |
セッション中は常時 | 約100トークン |
| 2 | SKILL.mdの本文 |
スキルが起動したとき | 5,000トークン以下、500行以内を推奨 |
| 3 | 補助ファイル（reference.md、scripts/など） |
本文から参照され、必要になったとき | 内容しだい |
つまり、スキルを10個持っていても常時コストは「10個分の名前と説明」だけです。ただし注意点もあります。Claude Codeはスキル一覧の文字数に予算（既定でモデルのコンテキストウィンドウの1%）を設けており、これを超えると使用頻度の低いスキルから説明が切り詰められます。descriptionとwhen_to_useの合計も1,536文字で切られるため、説明は「一番大事な用途を先頭に」書くのがコツです。
また、一度起動したスキルの本文は、その後の会話にも残り続けます（毎ターン読み直すのではなく、会話に1メッセージとして追加される形です）。コンテキストが自動圧縮されるときは、直近に起動したスキルから順に先頭5,000トークンが引き継がれます。長い手順を書くときは「一度きりの指示」ではなく「作業中ずっと守ってほしい指針」として書くと、圧縮後も効きやすくなります。
フロントマターを理解する
SKILL.mdの先頭、---で囲まれた部分がフロントマターです。ここには「オープン仕様で決まっている共通項目」と「Claude Codeが独自に追加した項目」の2種類があります。
図6: 公式ドキュメントのフロントマター一覧の一部。全項目が省略可能で、descriptionだけが「推奨」となっています。
オープン仕様で定義されている6項目
| 項目 | 必須 | 内容 |
|---|---|---|
name |
仕様上は必須 | 小文字・数字・ハイフンのみ、64文字以内。フォルダ名と一致させる |
description |
仕様上は必須 | 何をするか、いつ使うか。1,024文字以内 |
license |
任意 | ライセンス名または同梱ファイル名 |
compatibility |
任意 | 必要な環境（対象製品、必要なコマンドなど）。500文字以内 |
metadata |
任意 | 自由なキーと値のマップ |
allowed-tools |
任意（実験的） | 事前承認するツールをスペース区切りで指定 |
Claude Codeはこれより緩く、nameを省略するとフォルダ名が、descriptionを省略すると本文の最初の行が代わりに使われます。ただし、claude.aiへのアップロードやSkills APIではこの6項目以外を書くとエラーで拒否されるので、他の環境でも使う予定のスキルは6項目に収めておくのが安全です。
もう1つ注意したいのは、個人スキルやプロジェクトスキルではnameは一覧に表示される名前でしかなく、/で呼び出すコマンド名はフォルダ名で決まるという点です。name: rnと書いても、フォルダがrelease-notesなら/release-notesで呼びます。プラグインのスキルだけは例外で、nameがコマンド名の末尾になります。
Claude Code独自の主な拡張項目
| 項目 | 用途 |
|---|---|
when_to_use |
起動条件の補足（言い回しの例など）。descriptionと合わせて1,536文字まで |
argument-hint |
補完時に表示する引数のヒント |
arguments |
名前付き引数を定義し、本文で$nameとして参照する |
disable-model-invocation |
trueでClaudeの自動起動を禁止。スケジュール実行やサブエージェントへの事前読み込みも止まる |
user-invocable |
falseで/メニューから隠す（Claudeだけが使う背景知識向け） |
allowed-tools / disallowed-tools |
そのターンだけ承認する／使用禁止にするツール |
model / effort |
スキル実行中だけモデルや思考量を切り替える（次のプロンプトで元に戻る） |
context: fork / agent / background |
サブエージェントとして隔離実行する |
paths |
指定したglobに合うファイルを扱っているときだけ自動起動する |
hooks |
スキル起動時にフックを登録する |
shell |
動的コンテキスト注入に使うシェル（bashまたはpowershell） |
初心者のうちは、descriptionをしっかり書いたうえで、必要に応じてdisable-model-invocationとallowed-toolsを足す、というくらいで十分です。
誰が起動できるかを決める2つの項目
disable-model-invocationとuser-invocableは名前が似ていて混乱しやすいので、整理しておきます。
図7: 取り消しがきかない操作（デプロイ、Slack送信など）はdisable-model-invocation: trueにして、人だけが起動できるようにします。
disable-model-invocation: trueを付けると、Claudeが自分の判断でそのスキルを起動できなくなるだけでなく、説明文自体がコンテキストから外れます。Claudeがそれでも実行しようとした場合、Claude Codeが呼び出しをブロックし、「手順を別の方法で再現するのもやめる」よう指示するので、Claudeは「/deployを自分で実行してください」と提案してくるはずです。
一方、user-invocable: falseは「人が/で呼ぶ意味のない知識」に使います。たとえば旧システムの背景説明のようなスキルは、Claudeが必要なときに勝手に読んでくれればよく、メニューに出てくる必要はありません。
どこに置くか。配置場所と優先順位
スキルは「どこに保存したか」で、どのセッションに読み込まれるかが決まります。
図8: 同じ名前のスキルが複数の場所にある場合、エンタープライズ、個人、プロジェクトの順で優先されます。プラグインは名前空間付きなので衝突しません。（静止画版）
| 配置場所 | パス | 読み込まれる範囲 |
|---|---|---|
| エンタープライズ | 管理設定ディレクトリ内の.claude/skills/<name>/SKILL.md |
組織が配布した全ユーザー |
| 個人 | ~/.claude/skills/<name>/SKILL.md |
自分の全プロジェクト（ただしCoworkやクラウドセッションでは読まれません） |
| プロジェクト | .claude/skills/<name>/SKILL.md |
そのリポジトリ。コミットすればチームで共有 |
| ネスト | <サブディレクトリ>/.claude/skills/<name>/SKILL.md |
サブディレクトリ内のファイルを扱い始めたときに読み込まれる（モノレポ向け） |
| プラグイン | <plugin>/skills/<name>/SKILL.md |
プラグインが有効な場所で/プラグイン名:スキル名として |
| claude.ai同期 | claude.aiのアカウントで有効化したスキル | Cowork、クラウドセッション、およびclaude.aiアカウントでサインインした端末セッション |
覚えておくと便利な挙動をいくつか挙げます。
- スキルの追加や編集は、原則として再起動なしで現在のセッションに反映されます。ただし、セッション開始時に
.claude/skills/ディレクトリ自体が存在しなかった場合は、作成後にClaude Codeを再起動する必要があります - 個人スキルとプロジェクトスキルに同名のものがあると、個人のほうが勝ちます。「チームの共通スキルを自分用に上書きしたい」場合に使えます
- 自作スキルが組み込みスキルと同名なら自作が優先されますが、組み込みの別名（
/reviewなど）までは置き換わりません - claude.aiアカウントでサインインしているセッションでは、claude.aiで有効にしたスキルが
~/.claude/skills/synced/に自動で同期されます（v2.1.273以降）。syncedというフォルダ名は予約されているので、自作スキルに使わないでください
最初から入っている「組み込みスキル」
自分で作らなくても、Claude Codeにはスラッシュコマンドで呼べる組み込みスキルが多数用意されています。/helpや/compactのような固定処理のコマンドと違い、組み込みスキルはプロンプトベースで、Claudeが指示に従ってツールを組み合わせながら柔軟に動きます。
| スキル | 何をするか |
|---|---|
/batch <指示> |
コードベース全体に及ぶ大規模変更を、サブエージェントを並列起動して分担実行する |
/code-review |
直近の変更をレビューし、バグや改善点を報告する（別名/review） |
/simplify |
直近の変更を、再利用性・簡潔さ・効率の観点で見直して修正を適用する |
/debug |
セッション途中からデバッグログを取得し、トラブルシューティングする |
/loop [間隔] [プロンプト] |
プロンプトを一定間隔で繰り返し実行する |
/claude-api |
Claude APIのリファレンスを読み込む。モデル移行やManaged Agentの案内も含む |
/run / /verify |
アプリを起動して、変更が実際に動くかを確認する（/verifyは人が呼んだときだけ動く） |
/run-skill-generator |
自分のプロジェクトの起動手順を記録し、/runと/verifyに教える |
/skill-doctor |
各スキルのコンテキストコストと使用頻度を表示し、不要なスキルを見つける（v2.1.252以降） |
/doctor |
設定の健全性チェック。スキル一覧のコスト見積もりも出る |
一覧は/skillsコマンドで確認でき、各スキルを選んでスペースキーを押すと「表示する／名前だけ／人だけが起動可／無効」を切り替えられます。この設定は.claude/settings.local.jsonのskillOverridesに保存されるので、共有リポジトリのスキルファイルを直接編集せずに、自分の環境だけで挙動を変えられます。
組み込みスキルをまとめて無効にしたい場合は、設定のdisableBundledSkillsをtrueにします。
少し進んだ使い方
基本を押さえたら、次の4つを覚えると表現の幅が一気に広がります。
引数を受け取る
/release-notes v1.2.0のように呼び出したとき、本文の$ARGUMENTSはv1.2.0に置き換わります。位置ごとに取り出すなら$0、$1（または$ARGUMENTS[0]）、名前を付けるならargumentsフィールドを使います。
---
name: migrate-component
description: コンポーネントを別の言語に移植する
arguments: [component, from, to]
---
$component コンポーネントを $from から $to に移植してください。既存の挙動とテストは維持します。
/migrate-component SearchBar JavaScript TypeScriptと呼ぶと、$componentがSearchBar、$fromがJavaScript、$toがTypeScriptに展開されます。複数語を1つの引数にしたいときは引用符で囲みます。
実行時の情報を差し込む
本文中の!`コマンド`は、Claudeが本文を読む前にシェルで実行され、出力に置き換わります。行頭か空白の直後にある!だけが認識される点と、コマンドが失敗（非ゼロ終了）するとスキルの起動自体が中止される点に注意してください。失敗してもよいコマンドには|| trueを付けます。
## 環境
```!
node --version
git status --short
```
スキル内のスクリプトを呼ぶときは、${CLAUDE_SKILL_DIR}を使うと、個人・プロジェクト・プラグインのどこに置いても同じパスで動きます。allowed-tools側にも同じ変数を書けば、確認プロンプトなしで実行できます。
---
name: render-chart
description: CSVからチャートを描画する
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---
`${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` を実行してチャートを描画してください。
サブエージェントとして隔離実行する
context: forkを付けると、スキルの本文をプロンプトとして新しいサブエージェントが起動します。会話の履歴は引き継がれないので、本文だけで完結する指示にしておく必要があります。調査系のスキルには読み取り専用のagent: Exploreが向いています。
---
name: deep-research
description: トピックを徹底的に調査する
context: fork
agent: Explore
---
$ARGUMENTS について徹底的に調査してください。
1. GlobとGrepで関連ファイルを探す
2. コードを読んで分析する
3. ファイル名を添えて要点をまとめる
既定ではバックグラウンドで動き、結果が出たら会話に届きます。結果を待ちたいならbackground: falseを付けます。
ファイルの種類で自動起動を絞る
pathsを指定すると、そのパターンに合うファイルを扱っているときだけ自動起動します。フロントエンドの規約スキルをTypeScriptファイルの編集時だけ出したい、といった使い方です。
paths:
- "src/**/*.ts"
- "src/**/*.tsx"
スキルを作ってくれるスキル
一から書くのが面倒なら、Anthropic公式のskill-creatorプラグインを使う手があります。対話形式でSKILL.mdの雛形を生成できるほか、テストケースを作って「スキルあり／なし」で結果を比較するといった評価機能も備えています。
/plugin install skill-creator@claude-plugins-official
インストール後は/skill-creator:skill-creatorで呼び出すか、「release-notesスキルをskill-creatorで評価して」のように頼みます。
claude.aiでもスキルは使える
スキルはClaude Code専用ではありません。claude.aiの「設定 > スキル」から、自作スキルのアップロードや、Anthropicとパートナー企業が提供するスキルの追加ができます。ここで有効にしたスキルは、Coworkやクラウドセッション、そしてclaude.aiアカウントでサインインした端末のClaude Codeにも同期されます。
図9: claude.aiの「スキル」設定。上段が自分でアップロードしたスキル、下段がAnthropicとパートナー企業提供のスキルです。
「探索」タブでは、提供元とインストール数を見ながらスキルやプラグインを追加できます。
図10: 「探索」タブ。撮影時点でAnthropic提供の「Engineering」は190万件以上、「Legal」は130万件以上のインストール数が表示されていました。
右上の「追加」ボタンからは、ファイルのアップロード、エディタでの作成、Claudeとの対話による作成の3通りが選べます。
図11: 「追加」メニュー。Claude Code側で作ったスキルをそのままアップロードする場合は、フロントマターをオープン仕様の6項目に収めておく必要があります。
オープンスタンダードになったスキル
スキルは2025年10月にAnthropicがClaude向けの機能として公開し、同年12月に「Agent Skills」という名前でオープンスタンダード化されました。仕様はagentskills.ioで公開されており、GitHubのagentskills/agentskillsリポジトリで管理されています。
図12: agentskills.ioのトップページ。仕様リポジトリのStar数は撮影時点で25,419でした。
Claude Code以外にも、Cursor、GitHub Copilot（VS Code）、Gemini CLI、OpenAI Codex、OpenCode、Amp、gooseなど多数のツールが同じSKILL.md形式を読めるようになっています。つまり、一度書いたスキルは（Claude Code独自項目を使っていなければ）他のエージェントにもそのまま持ち込めます。次の節で紹介する公開スキル集の多くが「Claude Code、Codex、Cursor対応」を謳っているのはこのためです。
信頼できる公開スキル集と導入方法
「便利なスキルを入れたいが、出所の分からないものは避けたい」という方向けに、大手企業・団体が公式に公開しているリポジトリに絞って紹介します。Star数はいずれも2026年9月17日にGitHubで確認した値です。
| リポジトリ | 提供元 | Stars | 主な内容 |
|---|---|---|---|
| anthropics/skills | Anthropic | 176,739 | 公式スキル集。docx/pdf/pptx/xlsxの文書スキル、skill-creator、mcp-builder、frontend-designなど |
| anthropics/claude-plugins-official | Anthropic | 36,438 | Claude Code公式プラグインディレクトリ。/pluginの「Discover」で参照される |
| vercel-labs/agent-skills | Vercel | 31,254 | React/Next.jsのパフォーマンス規約、Webデザイン監査、ライティング規約、Vercel最適化 |
| openai/skills | OpenAI | 27,381 | Codex向けのスキルカタログ（同じSKILL.md形式） |
| agentskills/agentskills | 仕様本体 | 25,418 | Agent Skills仕様とリファレンス実装、検証ツール |
| huggingface/skills | Hugging Face | 11,061 | hf CLIの操作、モデル学習・評価、Jobsでのクラウド実行 |
| google-labs-code/stitch-skills | Google Labs | 8,325 | デザインツールStitch向けのデザイン生成・ビルド支援 |
| trailofbits/skills | Trail of Bits | 7,123 | セキュリティ監査、スマートコントラクト検査、GitHub Actionsの安全性確認 |
| remotion-dev/skills | Remotion | 4,596 | Reactでの動画生成 |
| microsoft/skills | Microsoft | 3,025 | Azure SDK・Microsoft AI Foundry向け。175スキル |
| cloudflare/skills | Cloudflare | 2,840 | Workers、Durable Objects、Wrangler、Web性能監査 |
| supabase/agent-skills | Supabase | 2,622 | PostgreSQLのベストプラクティス |
| expo/skills | Expo | 2,536 | Expoプロジェクトとビルドサービスの操作 |
図13: Anthropic公式のanthropics/skills。skills/にスキル本体、spec/に仕様、template/に雛形があります。
図14: Vercel公式のvercel-labs/agent-skills。React/Next.jsを使う方には特におすすめです。
なお、個人メンテナによるobra/superpowers（287,657 Stars）はコミュニティで最も広く使われているスキル集ですが、企業・団体の公式ではないため、この記事では表に含めていません。導入する場合はallowed-toolsや同梱スクリプトの内容を確認したうえで判断してください。
導入方法は2系統
公開スキルの入れ方は、大きく「Claude Codeのプラグイン機構で入れる」か「skills CLIで各エージェントの所定フォルダにコピーする」かの2系統です。
プラグインとして入れる（Claude Code、更新も追従）
# Anthropic公式スキル集
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills
# Hugging Face
/plugin marketplace add huggingface/skills
/plugin install hf-cli@huggingface/skills
# Trail of Bits（セキュリティ系）
/plugin marketplace add trailofbits/skills
/plugin menu
# Cloudflare
/plugin marketplace add cloudflare/skills
/plugin install cloudflare@cloudflare
プラグイン由来のスキルは/プラグイン名:スキル名という名前空間付きで呼びます。たとえばdocument-skillsを入れた後は「PDFスキルを使ってこのファイルのフォーム項目を抽出して」のように頼めば起動します。
skills CLIで入れる（複数エージェント共通）
# Vercel
npx skills add vercel-labs/agent-skills
# Microsoft（対話式で必要なスキルだけ選ぶ）
npx skills add microsoft/skills
# Supabase（特定スキルだけ）
npx skills add supabase/agent-skills --skill supabase
# Expo（全スキル）
npx skills@latest add expo/skills --skill '*'
npx skills addはskills.shが提供するCLIで、Claude Code、Codex、Cursorなど複数のエージェントのスキルフォルダに同じスキルを配置できます。
導入前に確認したいこと
公式リポジトリであっても、次の2点は目を通してから使うことをおすすめします。
allowed-toolsの中身。公式ドキュメントは、リポジトリに含まれるスキルのallowed-toolsは「Claude Codeを実行する前にレビューすべき」と明記しています。プロジェクトスキルのallowed-toolsは、ワークスペースを信頼していないフォルダで-p実行した場合でも適用されるためです- 同梱スクリプトが何をするか。
scripts/にあるファイルはClaudeが実行します。外部にデータを送るような処理がないか確認してください
スキルが起動しないときの切り分け
作ったスキルが思ったように動かないときは、次の順で確認します。
図15: 上から順に切り分けると、たいていは①〜③で原因が見つかります。（静止画版）
| 症状 | 原因の候補 | 対処 |
|---|---|---|
/skillsに出てこない |
フォルダ名やファイル名の誤り。セッション開始時にディレクトリが無かった | パスとSKILL.mdの綴りを確認し、Claude Codeを再起動する |
/nameでは動くが自動起動しない |
descriptionが短い、依頼の言い回しと一致しない |
実際に言う言葉をdescriptionやwhen_to_useに足す |
| 自動起動を期待しているのに一度も起動しない | disable-model-invocation: trueが付いている |
意図した設定か見直す |
/nameでもdescriptionが効かない |
フロントマターのYAMLが壊れている | claude plugin validateで検証する（下図） |
| 説明が途中で切れている | スキルが多く一覧の文字数予算を超えている | /doctorで確認し、skillOverridesで不要なスキルをname-onlyやoffにする |
| 逆に起動しすぎる | descriptionが広すぎる |
用途を絞る。人だけが呼ぶならdisable-model-invocation: true |
フロントマターが壊れていても、Claude Codeはスキルを「メタデータ空」の状態で読み込むため、/nameでの直接起動はできてしまいます。「直接なら動くのに自動起動しない」ときは、構文エラーを疑って検証コマンドを実行してください。以下は、わざと壊したフロントマターを検証した実際の結果です。
図16: 実際の実行結果。「実行時にはこのスキルは空のメタデータで読み込まれ、フロントマターの全項目が黙って捨てられる」と警告してくれます。
まとめ
この記事の要点を振り返ります。
- スキルは
SKILL.mdを含むフォルダで、CLAUDE.mdと違い本文は使うときだけ読み込まれる - 作るのは
mkdirとSKILL.mdの2ステップ。claude plugin validateで構文を検証できる - 起動経路は「
/nameで直接」と「descriptionを見てClaudeが自動で」の2つ。自動起動は説明文の書き方で決まる - 取り消せない操作は
disable-model-invocation: trueで人だけが起動できるようにする - 置き場所は個人・プロジェクト・プラグイン・claude.ai同期があり、同名なら個人がプロジェクトに勝つ
- スキルはオープンスタンダードになり、Anthropic、Vercel、Microsoft、Hugging Faceなどが公式スキル集を公開している
次のステップとしては、まず自分が過去1週間でClaude Codeに繰り返し伝えた指示を1つ選び、それをスキルにしてみることをおすすめします。動いたら/skill-doctorでコストを眺め、skill-creatorで「スキルあり／なし」の差を測ってみると、良いdescriptionの書き方が体感できます。
参考リソース
- Extend Claude with skills（Claude Code公式ドキュメント）
- Agent Skills 仕様（agentskills.io）
- Skill authoring best practices（Claude Developer Platform）
- anthropics/skills（GitHub）
- anthropics/claude-plugins-official（GitHub）
- vercel-labs/agent-skills（GitHub）
- huggingface/skills（GitHub）
- microsoft/skills（GitHub）
- trailofbits/skills（GitHub）
- Evaluating skill output quality（agentskills.io）
