Claude Code Skill 設計完全ガイド 2026｜呼ばれない原因・SKILL.md 肥大化対処・subagent 化判断

結論を 1 行で

Skill が思い通りに動かない原因の大半は「description が trigger 文として機能していない」か「SKILL.md が肥大化して指示が埋もれている」のどちらか。 公式仕様には対処法が明記されていて、ほぼテンプレで直る。

Claude Code 公式 docs (Skills) を読み解き、monorepo で Skill 10 本超を運用している筆者の実例で「動かない時の対処と設計思想」を整理する。

この記事の前提

• 環境: Claude Code v2.x、Skills は Agent Skills オープン標準
• 読者の状況: Skill を 1〜数本作ったが、自動起動しない / 振る舞いが安定しない / SKILL.md が大きくなりすぎて困っている
• 筆者の検証環境: monorepo で auto-invoke 型・手動 invoke 型・background knowledge 型の Skill を 10 本超併用

この記事でわかること:

• description が auto-invoke される条件
• SKILL.md の肥大化を防ぐ supporting files 分割パターン
• disable-model-invocation / user-invocable の 4 パターン
• subagent 化（context: fork）の判断軸
• 「呼ばれない / 呼ばれすぎる」の troubleshooting

入門との違い（位置付け）

【第1回】Claude Code Skills 入門 が「Skill を作る最初の手順」を扱ったのに対し、本記事は 「Skill を意図通り動かす設計思想」 を扱う。「動くようになった後の悩み」が対象。

読者のよくある詰まり

• 期待した文脈で Skill が呼ばれない（trigger phrase 不足）
• Skill は呼ばれるが指示通りに振る舞わない（content の書き方）
• SKILL.md が肥大化して何が効いているか分からない
• 副作用のある操作（deploy / commit）を Claude が勝手にやって困った
• subagent 化する基準が分からない

これらは全部「公式仕様の挙動を 1 度押さえれば消える」モヤモヤだ。

設計思想 1: description が「呼ばれる条件」を全て決める

公式の最重要記述：

"the description helps Claude decide when to load it automatically"

description は Skill の意図を Claude に伝える唯一の trigger 文。ここが曖昧だと Claude は「呼ぶべきか」を判断できない。

description のフォーマット 3 要素

1. 何をするか（動詞 + 対象）
2. いつ呼ぶか（trigger phrase / シナリオ）
3. 例文（when_to_use フィールド）

NG / OK 比較

NG 側の共通点は 「いつ呼ぶか」が抜けている。OK 側は「ユーザーが自然に発する trigger phrase」を含んでいる。

文字数制限の注意

公式：

"the combined description and when_to_use text is truncated at 1,536 characters in the skill listing to reduce context usage."

description + when_to_use の合算が 1,536 文字でカット される。要点を頭に置く（front-load）。長い説明を後ろに回すと、Claude の判断材料が削られる。

設計思想 2: SKILL.md は load されたら最後まで残る

公式：

"the rendered SKILL.md content enters the conversation as a single message and stays there for the rest of the session. Claude Code does not re-read the skill file on later turns"

含意は 3 つ：

1. Skill content は「standing instructions」として書く（毎回読まれるつもりで）
2. one-time 手順は load 直後の前半に書く（後半は standing rule に）
3. content は再 invoke されない限り更新されない（編集しても次の invoke までは古いまま）

compaction での挙動

公式：

"When the conversation is summarized to free context, Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each. Re-attached skills share a combined budget of 25,000 tokens."

つまり：

• 1 Skill あたり最初の 5,000 トークンが残る
• 全 Skill の合算で 25,000 トークン上限
• 古い Skill から落とされる

→ 大きい Skill は「最初の 5,000 トークンに重要事項」を集中させる 設計が必要。

設計思想 3: 肥大化したら supporting files に分割

公式：

"Keep SKILL.md under 500 lines. Move detailed reference material to separate files."

肥大化 Skill の分割パターン：

my-skill/
├── SKILL.md          (overview + 「いつ何のファイルを読むか」のナビ、100 行以下)
├── reference.md      (詳細仕様、必要時に Claude が Read)
├── examples.md       (例示集、必要時に Read)
└── scripts/
    └── helper.py     (実行可能スクリプト、bundled)

SKILL.md からの参照例：

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

公式：

"Reference these files from your SKILL.md so Claude knows what each file contains and when to load it"

「いつ何を読むか」を SKILL.md に書いておくと、Claude は必要時だけ追加ファイルを Read する。content budget に効く。

設計思想 4: 起動権限を 4 パターンで使い分け

公式 frontmatter フィールド disable-model-invocation と user-invocable の組み合わせで挙動を制御する。

公式の例：

• deploy / commit → disable-model-invocation: true（Claude が勝手に deploy しないように）
• legacy-system-context → user-invocable: false（コマンドメニューには出ないが Claude は文脈で参照）

Context 載せ方の違い

disable-model-invocation: true は Claude の判断材料から完全に外す 設計。重要な副作用操作はこれで「Claude には見えない」状態にする。

設計思想 5: subagent 化（context: fork）の境界

公式：

"Add context: fork to your frontmatter when you want a skill to run in isolation. The skill content becomes the prompt that drives the subagent."

subagent 化すべきタスクの判断軸

公式の警告

"context: fork only makes sense for skills with explicit instructions. If your skill contains guidelines like 'use these API conventions' without a task, the subagent receives the guidelines but no actionable prompt, and returns without meaningful output."

つまり 「ガイドライン型 Skill を fork しても意味がない」。task 型 Skill（明示的な「何をしろ」がある）だけが fork 対象。

例（公式）：

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

agent: Explore で Explore subagent を使い、独立 context で research を走らせる。結果サマリだけが親に戻る。

設計思想 6: 動的 context 注入（!command）

公式：

"The !`<command>` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself."

例：PR diff を skill 起動時に最新取得

---
name: pr-summary
description: Summarize PR changes
context: fork
allowed-tools: Bash(gh *)
---

## PR diff
- !`gh pr diff`
- !`gh pr view --comments`

## Task
Summarize this PR with: changed files, key risks, suggested questions.

! は preprocessing で実行され、Claude には実データだけが渡る。Claude が実行するわけではない。「invoke 時の最新状態」を skill content に埋め込みたい時に使う。

落とし穴トラブルシューティング 4 つ

1. 「Skill が自動で呼ばれない」

2. 「Skill は呼ばれるが指示通りに動かない」

3. 「SKILL.md が肥大化して効きが落ちた」

4. 「副作用のある操作を Claude が勝手にやった」

ケーススタディ: monorepo Skill の description 比較

筆者の monorepo で運用している Skill から、description 設計の違いを抜粋。

masatoman.net 記事 (MDX、無料・有料問わず) を新規執筆 / 大幅リライト /
タイトル変更 / 訴求変更する直前に必ず invoke する skill。
主顧客 @Bioinfo_Kimura に刺さる文体 + 禁止訴求 + 標準構造 + gains 必須化を
強制。Claude が記事を書き始める前に自発的に invoke する。

モノレポ全体の整合性監査を対話実行。plans/memory/scheduled-tasks/.claude/
GitHub Actions/Skills の6領域をチェックし、赤黄緑で分類したレポートを出す。
自動修正禁止、検出のみ。

Use this skill ONLY when the user explicitly invokes it
(e.g., `/session-recap` or "session-recap やって"). Do NOT fire
automatically — the user has opted out of auto-recap.

3 つとも description は 「いつ呼ぶか」を頭出し している。これが auto-invoke 精度に直結する。

今日やること（3 つ以内）

1. 既存 Skill の description を読み返す: trigger phrase が明示されているか確認、無ければ追加
2. 500 行超の Skill を supporting files に分割: SKILL.md を overview に絞り、詳細を reference.md / examples.md に
3. 副作用のある skill を整理: deploy / commit / send 系に disable-model-invocation: true を追加

関連記事

まとめ

• Skill が呼ばれない原因の大半は description の trigger phrase 不足
• SKILL.md は load されたら最後まで残る → standing instructions として書く
• 500 行超は supporting files に分割、SKILL.md は overview に絞る
• 副作用のある skill は disable-model-invocation: true で Claude の判断材料から外す
• subagent 化は task 型 Skill のみ、ガイドライン型を fork しても無意味
• compaction 時は最初の 5K token しか残らない → 重要事項を頭に集中

description の書き方と SKILL.md 設計思想が押さえられると、Skill が「動かない」「振る舞いが安定しない」という悩みのほとんどが消える。次は これらの Skill を組み合わせて 24 時間自走する Claude Crew を作るフェーズに進める。