/my-deploy と打ったのに何も起きない。あるいは逆に、ちょっと「このAPI どう書いた？」と聞いただけで、関係なさそうな自作Skillが勝手にロードされる—。Claude Code v2.1系で Custom commands が Skills に統合されてから、こうした「発動制御」絡みの相談を周りで何度か聞きました。公式ドキュメントの How to create custom Skills セクションはディレクトリ構成のサンプルこそ載っているものの、frontmatter の仕様や発動の挙動はあちこちに散らばっていて、全体像が掴みにくいんですよね。SKILL.md の最小構成から、Claude が自動発動を判断する仕組み、発動しないときの確認手順まで、実際に触りながら整理してみます。
v2.1系で「commands」と「Skills」の関係が整理された
公式ドキュメントの Skills ページに 「Custom commands have been merged into skills.」 という一文が追加されています。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy として動く、という記述。これだけ読むと「ファイル置き場が増えただけ」に見えますが、Skill 側にしかない仕組みがいくつかあって、そこを押さえないと「自作したのに発動しない」で詰まりやすいです。
Google サジェストでも「claude code skills 使い方」「claude skill not triggering」あたりが上位に並んでいる通り、ハマりどころは大きく二つ。Claude が自動で呼んでくれないケースと、/skill-name で叩いたのに期待通り動かないケースです。順を追って潰していきます。
動作確認した環境
- Claude Code 2.1.119（2026-04-23 リリース）
- macOS Sonoma 14.x
- 個人スキル:
~/.claude/skills/配下
最小構成のSKILL.mdから動かしてみる
まずは公式の Create your first skill セクションをなぞる形で最小構成を作ります。スキルはディレクトリ単位で、ディレクトリ名がそのままコマンド名になる仕組みです。
ディレクトリとSKILL.mdを置く
mkdir -p ~/.claude/skills/explain-code
$EDITOR ~/.claude/skills/explain-code/SKILL.md~/.claude/skills/
└── explain-code
└── SKILL.md (1 file, 312 bytes)SKILL.md の中身は YAML frontmatter と指示文だけ。name は省略するとディレクトリ名が使われるので、最小構成だと description 1 行で動きます。
---
description: コードの動きを図とアナロジーで説明する。「これってどう動いてるの？」と聞かれたときに使う。
---
コードを説明するときは、必ず以下を含める:
1. 日常生活のたとえ話で導入
2. ASCIIアートで構造を図示
3. 行ごとの流れを追跡
4. ハマりがちなポイントを最後に1つ動作確認
> /explain-code src/auth.py
🔧 Skill 'explain-code' loaded (~210 tokens)
このコードは郵便局の窓口に並ぶような仕組みになっています...ロード時に消費トークン数が表示されますが、SKILL.md 自体は呼ばれるまでコンテキストに乗りません。ここが CLAUDE.md との大きな違いで、関連記事のClaude Code memoryとは？CLAUDE.mdとの違いと運用設計の実例でも触れた通り、CLAUDE.md は常時ロード、Skill は「説明文のみ常時、本体は呼出時」というモデル。長い手順書は Skill 化したほうがトークン効率がいいです。
frontmatterで押さえる5つのフィールド
frontmatter のフィールドは name、description、argument-hint、arguments、disable-model-invocation、user-invocable、allowed-tools、model、effort、context、agent、hooks、paths、shell と 14 個ありますが、最初に覚えるべきは 5 つで十分です。
| フィールド | 用途 | 典型値 |
|---|---|---|
description | Claudeが自動発動を判断する材料 | 1,536文字以内 |
disable-model-invocation | ユーザーだけが叩ける状態にする | true / false |
user-invocable | 逆にClaudeだけが使える知識として隠す | true / false |
allowed-tools | そのSkill実行中に追加で承認するツール | Bash(git *) |
paths | 特定ファイルを触っているときだけロード | src/api/**/*.ts |
disable-model-invocation: true と user-invocable: false はちょうど逆の意味で、両方 true/false の組み合わせで挙動が変わります。デプロイ系のように副作用が大きい操作は前者、レガシー仕様の参照ドキュメント系（Claude には知っていてほしいがユーザーがコマンドとして叩くものではない）は後者を使うのが定石です。
allowed-toolsはホワイトリストではない
地味にハマったのが allowed-tools の挙動で、ここに書いたツールは「Skill 実行中に事前承認される」だけで、書かなかったツールも普通に呼べます。「ここに書かないと使えない」と思って細かく列挙していたのですが、公式ドキュメントを読み直したら “does not restrict which tools are available” と明記されていました。制限したいなら /permissions 側の deny rule で縛るのが正解です。
descriptionの書き方で発動精度が決まる
自動発動の判断材料は description と when_to_use のテキストだけで、二つを合わせて 1,536 文字に切り詰められます。多くの Skill を入れているプロジェクトだと表示予算が足りなくなり末尾が削られるので、重要なキーワードは前半に置くのが鉄則です。
アンチパターン: 機能だけ書いて発動条件を書かない
---
name: api-review
description: APIエンドポイントを点検するスキル
---これだと「点検する」しか書かれていないので、Claude は「ユーザーが明示的にレビューを頼んだとき」しか連想しません。「実装直後にも、PR 作成前にも、レイテンシ問題が出たときにも」呼ばれてほしいなら、トリガーになる単語を全部入れます。
OKパターン: トリガーフレーズを並べる
---
name: api-review
description: REST APIエンドポイントを点検する。新しいハンドラを書いた直後、PRを作る前、レスポンスが遅いと感じたとき、エラーレートが上がったとき、認可漏れを疑うときに使う。
when_to_use: |
ユーザーが「このAPIどう？」「レビューして」と言ったとき、
または `app/handlers/` 以下のファイルを編集した直後。
paths: app/handlers/**/*.py
---「使う」「呼び出す」をどのタイミングで—を箇条書きで列挙する形が、個人的にはハマりやすかったです。paths を併用するとファイルパスでも縛れるので、自動発動を絞り込みたいときに有効です。
Skillが発動しないときの確認手順
「自作したのに呼ばれない」は公式トラブルシューティングにも Skill not triggering として独立セクションがある定番の悩み。順番に潰していきます。
① Skillリストに載っているか確認
会話で What skills are available? と聞くと、現在ロード可能な Skill 一覧が返ってきます。ここに名前が出ていなければ、そもそもファイル配置か命名（小文字英数とハイフンのみ、最大 64 文字）の問題です。
> What skills are available?
- /commit (~85 tokens)
- /explain-code (~210 tokens)
- /api-review (~340 tokens)② descriptionが切られていないか確認
たくさん Skill を入れていると、表示は文脈窓の 1%（フォールバック 8,000 文字）に収まるよう短縮されます。SLASH_COMMAND_TOOL_CHAR_BUDGET 環境変数で広げるか、各 Skill の description をスリムにします。
export SLASH_COMMAND_TOOL_CHAR_BUDGET=16000[debug] Skill listing budget: 16000 chars
[debug] Skills loaded: 23 (descriptions fit within budget)③ ライブ更新の落とし穴
~/.claude/skills/ や .claude/skills/ 配下のファイル変更はセッション中に自動で反映されます。ただしセッション開始時に存在しなかった「skills ディレクトリ自体」を新しく作った場合は、Claude Code の再起動が必要。これは公式の “Live change detection” にも明記されていますが、初見では気付きにくいポイントです。
個人・プロジェクト・プラグインの優先順位
同じ名前の Skill が複数の場所にあるとどうなるか。優先順位は enterprise > personal > project で、個人スキルがプロジェクトスキルを上書きします。プラグイン由来の Skill は plugin-name:skill-name という名前空間で衝突しない設計です。
| 場所 | パス | 適用範囲 |
|---|---|---|
| 個人 | ~/.claude/skills/<name>/SKILL.md | すべてのプロジェクト |
| プロジェクト | .claude/skills/<name>/SKILL.md | このプロジェクトのみ |
| プラグイン | <plugin>/skills/<name>/SKILL.md | プラグイン有効時 |
チームに配りたいなら .claude/skills/ をリポジトリに含めて Git 管理するのが定石。ただしマシンローカルな設定（API キー等）が混ざらないよう、Skill 本体には環境依存値を書かないように注意しています。
context: fork でサブエージェント化する応用
v2.1.117 で追加された forked subagents と組み合わせると、重い処理を別コンテキストに切り出せます。やり方は frontmatter に context: fork と agent: Explore を入れるだけ。
---
name: deep-research
description: 大きめのテーマを深く調査する。新しいライブラリの調査、リファクタ前の影響範囲調査、レガシーコードの読み解き等に使う。
context: fork
agent: Explore
---
$ARGUMENTS について以下の手順で調査する:
1. Glob/Grep で関連ファイルを洗い出す
2. 上位 3〜5 ファイルを読み込んで責務を把握する
3. 依存関係を図示し、変更時のリスクを列挙する
4. 最後に「次に踏むべきステップ」を3つ提案するこのSkillを /deep-research 認証フロー と叩くと、Explore エージェントが別コンテキストで起動して結果だけ返ってきます。メインの会話履歴を汚さずに済むので、関連記事のClaude Codeのコンテキスト管理術—トークン消費を抑える7つの工夫で書いたトークン削減と相性がいいです。
ひとつ注意点として、context: fork は具体的なタスクが書かれている Skill でないと意味がないと公式ドキュメントが警告しています。「API の命名規則」のようなリファレンス系を fork しても、サブエージェントは「ガイドラインだけ受け取って何もせず終わる」結果になってしまいます。サブエージェント化の判断基準については、関連記事のClaude Codeのサブエージェント並列実行—コスト管理と設計のハマりどころも参考になると思います。
まとめ
Claude Code v2.1 系の Skills まわりで押さえておきたい点は次の通りです。
- Custom command は Skills に統合された（
.claude/commands/も従来通り動くが、ディレクトリを持てる Skill 側が推奨） - SKILL.md は
description1 行から書ける。nameはディレクトリ名で代用される description+when_to_useは合計 1,536 文字までで、ここにトリガー語を前半詰めするのが発動精度の鍵allowed-toolsは事前承認の指定であって、ツール制限ではない- 発動しないときは「リスト表示 → description 短縮確認 → ディレクトリ新設時の再起動」の順に切り分ける
- 優先順位は enterprise > personal > project、プラグインは名前空間で衝突回避
context: forkで重い処理をサブエージェント化できるが、リファレンス系には不向き
個人的には、毎日叩く /commit や /review-pr 系を disable-model-invocation: true でユーザー専用にしておくと、想定外のタイミングで実行されないので安心感があります。Skill は「育てる」ものなので、まずは 1 個動かしてから少しずつ増やしていくのが運用しやすいと思います。
