Claude Code Skills 設計ガイド - CLAUDE.mdとslash commandから切り出す

Claude Codeを使い込むと、CLAUDE.mdがだんだん太ります。レビュー手順、デプロイ手順、記事作成ルール、顧客ごとの確認観点。最初は便利ですが、常時読むべき前提と、特定作業でだけ使う手順が混ざると、Claudeの判断は濁ります。

一方で、毎回プロンプトを貼り直すのも弱いです。手順が少しずつ変わり、レビュー観点が抜け、別のrepoへ持っていったときに同じ品質で再現できません。

この記事では、Claude Code Skillsを、CLAUDE.mdから重い手順を切り出し、必要なときだけ読み込む運用部品として整理します。Claude Code全体の導入順は Claude Code の使い方 実践ガイド、手動で呼ぶ短いコマンド化は Claude Code スラッシュコマンド実践ガイド、常時指示の整理は CLAUDE.md の書き方 設計パターン集、調査やレビューを別文脈へ切る設計は Claude Code サブエージェント運用ガイド に分けています。

今回扱うのは、.claude/skills/<name>/SKILL.md、description、supporting files、disable-model-invocation、allowed-tools、cloud / Cowork sessionでの同期、/skill-doctorやevalによる棚卸しです。

先に結論: skillは「長いルール」ではなく「再現したい作業手順」にする

Claude CodeのSkillsは、SKILL.mdに書いた手順をClaudeのtoolkitへ追加する仕組みです。公式docsでは、skillは関連するときにClaudeが使うか、ユーザーが/skill-nameで直接呼び出すものとして説明されています。大事なのは、skill本文が常時全文ロードされるわけではなく、必要になったときに読み込まれる点です。

私なら、skill化の条件を次の4つに絞ります。

条件	skillに向く理由
同じ種類の依頼を何度もする	毎回の貼り直しを減らせる
実行順序が決まっている	手順抜けを防げる
参照資料やtemplateがある	references/やassets/へ逃がせる
CLAUDE.mdへ常駐させるには重い	contextを使うタイミングを限定できる

逆に、全セッションで必ず守る禁止事項、repo固有のbuild command、触ってはいけないdirectoryは、skillではなくCLAUDE.mdやmanaged settingsへ置きます。skillは「常に守る憲法」ではなく、「必要時に呼ぶrunbook」です。

CLAUDE.md、slash command、skillを分ける

最初に置き場所を間違えると、後から修正しにくくなります。

置き場所	向くもの	向かないもの
CLAUDE.md	repoの前提、禁止事項、検証コマンド	長い手順、頻度の低い作業
.claude/commands/	明示的に呼ぶ短い定型prompt	supporting filesが必要な手順
.claude/skills/	参照資料やscriptを含む再利用workflow	毎回必ず強制したいrule
subagent	main会話から分離したい調査やreview	小さい修正、頻繁な方針相談
plugin	複数repoや組織へ配る拡張bundle	まだ揺れている個別runbook

Claude Codeのdocsでは、custom commandsはskillsへ統合され、.claude/commands/deploy.mdと.claude/skills/deploy/SKILL.mdはどちらも/deployを作れると説明されています。既存のcommandsはまだ使えますが、新しく育てるならskillを本命にした方が拡張しやすいです。

ただし、短い手動workflowまで全部skillへ寄せる必要はありません。/review-pr 123のように1ファイルで十分なものはcommandで始める。本文が長くなり、example、reference、script、subagent実行が必要になったらskillへ移す。この順番が現実的です。

最小のSKILL.mdはdescriptionから書く

Claude Codeでは、skill directory名が呼び出し名になります。project skillなら次の形で始められます。

.claude/
  skills/
    release-note/
      SKILL.md
      references/
        format.md
      scripts/
        collect-changes.sh

SKILL.mdはまずdescriptionを締めます。

---
name: release-note
description: Draft release notes from a git range. Use when the user asks for a release note, changelog, or customer-facing summary. Do not use for code review.
disable-model-invocation: true
allowed-tools: Bash(git log *) Bash(git diff *)
---

# Release Note

1. Confirm the target range.
2. Collect merged PRs and user-visible changes.
3. Exclude internal refactors unless they changed behavior.
4. Draft the note in customer-facing language.

Agent Skillsの仕様では、nameとdescriptionが基本metadataです。Claude Code側ではfrontmatter fieldの多くがoptionalで、nameを省けばdirectory名が表示名やcommand名の基準になります。ただし、他のsurfaceへ持ち出す可能性があるなら、最初から標準仕様に寄せてnameとdescriptionを書いておく方が安全です。

descriptionには「何をするか」だけでなく「いつ使うか」を入れます。さらに長く運用するskillでは「いつ使わないか」も入れます。ここが曖昧だと、本文を丁寧にしても誤発火します。

SKILL.mdを太らせず、supporting filesへ逃がす

Claude Code docsは、skill directoryにsupporting filesを置けると説明しています。長いAPI仕様、チェックリスト、template、scriptを全部SKILL.mdへ入れる必要はありません。

私なら、ファイルの責務を次のように切ります。

ファイル	置く内容
SKILL.md	目的、起動条件、手順、出力形式、禁止事項
references/*.md	長い仕様、判断表、過去事例
assets/*	生成物template、画像、雛形
scripts/*	毎回同じ入出力で回す処理

SKILL.mdは目次兼runbookに留めます。Claudeが必要になったときだけreferenceを読む形にすれば、通常の会話で余計な文脈を食いません。

たとえば、セキュリティレビュー用skillなら、本文へOWASPの長い説明を貼るより、references/security-checklist.mdへ分けます。本文には「認可、secret、外部入力、audit logの順に見る」とだけ書く。細部は必要になったら読む。この粒度が保守しやすいです。

自動起動を許すskillと、手動だけにするskillを分ける

Claude Codeのskillは、ユーザーが/skill-nameで呼ぶだけでなく、Claudeが関連すると判断して読み込むこともあります。ここを便利さだけで決めると事故ります。

私なら、次の基準で分けます。

invocation	向くskill
自動起動を許す	style guide、API conventions、blog frontmatter checkのように副作用が小さいもの
disable-model-invocation: true	commit、deploy、外部送信、課金、権限変更のように人間がタイミングを決めるもの
user-invocable: false	legacy system contextのようにClaudeだけが読む背景知識

特にallowed-toolsを入れるskillは慎重に見ます。Claude Code docsでは、allowed-toolsはskillを呼んだturnだけtool approvalを事前許可するfieldであり、skill本文が残ってもpermission grantは次のuser messageで消えると説明されています。これは便利ですが、repoに入ったskillが広いBash許可を持つと、初回実行の危険が上がります。

最低限、review時には次を確認します。

skill_permission_review:
  name: deploy
  invocation: user-only
  allowed_tools:
    - Bash(pnpm test *)
    - Bash(pnpm build *)
  forbidden:
    - broad Bash(*)
    - network write without owner
    - secret echo or env dump
  owner: platform-team

skillはpromptではなく、tool accessと結びつく運用資産です。便利な定型文としてではなく、小さな権限境界として扱います。

dynamic context injectionは強いが、失敗条件を先に書く

Claude Code skillsでは、本文中に!でshell commandの結果を注入できます。たとえば!git diff HEADを入れると、skillが読まれる前に現在のdiffを展開できます。

これは、変更要約やrelease noteではかなり効きます。

---
name: summarize-changes
description: Summarize the current git diff and list review risks.
allowed-tools: Bash(git diff *)
---

## Current diff

!`git diff HEAD`

## Instructions

Summarize behavior changes, then list risks and missing verification.

ただし、injected commandが失敗するとskill invocation全体が止まります。失敗してよい探索コマンドなら|| trueを付ける、permissionが必要なコマンドならallowed-toolsを絞って明示する。ここを雑にすると、skillが便利になる前に「たまに動かない謎の手順」になります。

外部APIを叩くscriptを入れる場合は、さらに厳しく見ます。network、token、timeout、出力上限、失敗時のfallbackをSKILL.mdへ書きます。scripts/に逃がしても、運用責任は消えません。

cloud sessionとCoworkでlocal skillを前提にしない

Claude CodeのSkillsで見落としやすいのが、実行surfaceごとの差です。AnthropicのAgent Skills overviewでは、Claude Code、claude.ai、Claude APIでsharing scopeやruntime constraintsが違うと整理されています。

特にClaude CodeのCoworkやcloud sessionでは、手元の~/.claude/skills/をそのまま読みません。必要ならclaude.ai accountで有効化して同期するか、project skillとしてrepoにcommitするか、pluginとして配布します。remoteで動くRoutineに「自分のMacのpersonal skillがある前提」でpromptを書くと、次回実行でskill not foundになります。

私なら、運用表に必ずsurfaceを書きます。

skill_distribution:
  local_dev:
    source: "~/.claude/skills/review-note"
    use: personal draft only
  project:
    source: ".claude/skills/review-note"
    use: repo workflow shared by contributors
  cloud_session:
    source: "committed project skill"
    use: routine and cowork sessions
  organization:
    source: "managed settings or plugin"
    use: reviewed team distribution

APIやclaude.aiへ持ち出すskillでは、Claude Code専用frontmatterをそのまま入れないことも重要です。Claude Codeではargument-hintやdisable-model-invocationを使えますが、標準仕様外のfieldはuploadやpackagingで弾かれる場合があります。複数surfaceで使う予定があるskillは、標準仕様のname、description、license、compatibility、metadata、allowed-toolsへ寄せます。

subagentで走らせるskillは返却形式を固定する

Claude Codeでは、context: forkを使うとskillをsubagent contextで実行できます。長い調査やレビューをmain会話から分離したい場合には有効です。

ただし、forked skillは会話履歴を持ちません。つまり、main側の「さっき話した前提」を読んでくれると期待してはいけません。skill本文に、目的、入力、禁止事項、返却形式をすべて入れます。

---
name: security-impact-check
description: Check security impact for a code diff and return findings only.
context: fork
background: false
allowed-tools: Read Grep Bash(git diff *)
---

Return:

- finding
- evidence
- risk
- recommended action
- confidence

Do not edit files.
Do not call external services.

subagent化の目的は、main会話を軽くすることです。書き込み権限まで持たせるなら、skillではなくworktree、review owner、rollback条件を先に決めます。

作ったskillは使われたかではなく、効いたかを見る

skillは作って終わりではありません。Claude Code docsでは、skillがtriggerされた事実と、期待する出力を返した事実を分けて測るべきだと説明されています。ここはかなり実務的です。

私は最初の3本だけ、次のような小さいevalを作ります。

見る項目	判定
should trigger	期待する依頼でskillが使われるか
should not trigger	近いが対象外の依頼で誤発火しないか
output quality	期待する見出し、判断基準、禁止事項が出るか
tool boundary	許可したtoolだけで足りるか
maintenance	SKILL.mdが長くなりすぎていないか

/skill-doctorで未使用skillやcontext costを棚卸し、必要ならdescriptionを直します。evalは大げさに始めなくてよいです。3つのpositive promptと3つのnegative promptを置くだけでも、誤発火はかなり見えます。

最初の1週間の導入runbook

組織やチームで始めるなら、いきなりskill集を作らない方がよいです。

1. CLAUDE.mdから、長くて頻度の低い手順を3つ抜き出す
2. そのうち1つだけ.claude/skills/へ移す
3. descriptionに「使う条件」と「使わない条件」を入れる
4. supporting filesは最初から分ける
5. allowed-toolsは最小にする
6. cloud / Cowork / localのどこで使うかを決める
7. 1週間後に/skill-doctorと実例で残すか消すか決める

この流れなら、CLAUDE.mdを短くしながら、必要な手順だけを再利用できます。重要なのは、skillを増やすことではありません。Claudeに常時読ませる情報を減らし、必要な仕事だけを再現できる形で渡すことです。

よくある失敗

1. CLAUDE.mdの退避場所にする

太ったCLAUDE.mdをそのままskillへ移しても、問題は移動するだけです。skillには作業手順、入力、出力、禁止事項を書きます。背景知識や長い仕様はreferenceへ分けます。

2. descriptionが広すぎる

「開発を助ける」「レビューを改善する」のようなdescriptionは弱いです。対象作業、対象外、返すものまで書きます。skillの品質は本文より先にdescriptionで決まります。

3. allowed-toolsを広くしすぎる

allowed-tools: Bash(*)のようなskillは、実質的に広い実行許可を配るのと同じです。commitやdeploy系は手動起動にし、許可コマンドもpatternで絞ります。

4. local skillをcloud Routineで使えると思う

localの~/.claude/skills/は、cloud / Cowork sessionにそのまま渡りません。remoteで使うなら、account sync、repo commit、plugin配布のどれで届かせるかを先に決めます。

5. 作った後に棚卸ししない

skillは増えるほどdescriptionだけでもcontextを使います。使っていないskillは消すか、手動起動のみにします。残すskillは、trigger精度と出力品質を小さいevalで確認します。

まとめ

Claude Code Skillsは、長いpromptを保存する機能ではありません。CLAUDE.mdに常駐させるには重いが、何度も再現したい仕事を、必要なときだけClaudeへ渡す仕組みです。

実務では、まずCLAUDE.md、slash command、skill、subagent、pluginの置き場所を分けます。そのうえで、description、supporting files、tool permission、cloudでの到達性、evalをセットで設計します。ここまで決めれば、skillは単なる便利機能ではなく、AIワークフローを保守できる形で小さく分解する部品になります。