Claude Code Skillsの作り方と使い分け — 最小単位・運用ROI・他レイヤ比較

この記事で扱うこと

Claude Code Skillsは、.claude/skills/<name>/SKILL.md を1つ置くだけでClaudeに「専門知識パック」を追加できる仕組みです。/skill-name で手動呼び出しもでき、Claudeが文脈に応じて自動的に読み込むこともできます。手順書・チェックリスト・判断基準・参照資料を「毎回ペーストする」運用から、「ファイル化して呼び出す」運用へ切り替えるための最小単位です。

本記事は「Skillsをどう作るか / なぜ作るか / 他レイヤとどう使い分けるか / 失敗をどう避けるか」を網羅した作成ナレッジです。具体的な書き方(手順書型 / チェックリスト型 / 判断基準型 等の5パターン)はClaude Code Skillsの書き方 — 使える5つのパターン集で、設計思想の背景はAgent Skillsとは何かで扱っています。

Skillsを自作するメリット

SkillsはCLAUDE.mdやシステムプロンプトに直書きする運用との比較で5つの優位性を持ちます。

「何度も同じ内容をChatGPT風にペーストしている」「CLAUDE.mdが手順の塊で膨れ上がってきた」がSkills化の最大シグナルです。公式も Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact. と明示しています。

Skillsを自作するデメリット・コスト

メリットの裏返しに、運用負荷もあります。

• メンテナンスコスト:本文の指示が古くなると、自動呼び出しのたびに古い手順を強化してしまう。リポジトリのコマンドやAPI変更に追随する必要がある
• 「呼ばれない問題」:description が抽象的だとClaudeが文脈一致を判断できず、自動呼び出しされない
• 「呼ばれすぎ問題」:逆にdescriptionが広すぎると意図せず発動して、別の作業を邪魔する
• 本文のコンテキスト居座り:一度ロードされたSkillの本文はそのセッション中ずっとcontextに居座る(Claude Codeは再ロードしない)。長尺のSkillをinvokeするとそのまま継続的なトークンコスト(recurring)になる
• 権限の責任:allowed-tools で承認をスキップできるぶん、.claude/skills/ を信頼するかどうかが信頼判断に直結する(プロジェクトSkillsはワークスペース信頼ダイアログを承諾した後に効く)
• 記述の重複:同じ知識をCLAUDE.mdとSkill両方に書くと矛盾が生まれる。「どちらに書くか」の判断軸を最初に立てる必要がある

作成の最小単位

Skillはディレクトリ単位で管理し、必須は SKILL.md 1ファイルだけ。

.claude/skills/summarize-changes/
└── SKILL.md

SKILL.md の中身:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
 
## Current changes
 
!`git diff HEAD`
 
## Instructions
 
Summarize the changes above in two or three bullet points...

ディレクトリ名(summarize-changes)がそのまま /summarize-changes というスラッシュコマンドになります。description はClaudeが「いつ自動呼び出しするか」を判断する根拠なので、トリガフレーズ込みで具体的に書きます。

スコープと優先順位

同名のSkillがスコープを跨ぐと、Enterprise > Personal > Projectの順で上書きされます。Plugin Skillは plugin-name:skill-name の名前空間で衝突を回避します。

フロントマター仕様(全フィールド)

必ず押さえる4軸

description と when_to_use の書き方

descriptionは1,536文字までで切られます。description + when_to_use の合計で skillListingBudgetFraction 設定(デフォルトはコンテキスト窓の1%)を超えると、利用頻度が低いSkillからdescriptionが削られていきます。/doctor で削れているかを確認可能。「最重要のユースケースを先頭に書く」のが定石です。

disable-model-invocation と user-invocable で呼び出し制御

/deploy や /commit のような「Claudeが勝手に発動してほしくない」副作用つきSkillには disable-model-invocation: true、/legacy-system-context のような「Claudeが必要なときに自動で参照する背景知識」には user-invocable: false を選びます。

allowed-tools で承認スキップを宣言

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

allowed-tools は「このSkillが動いている間は承認なしで使えるツール」を列挙します。プロジェクトの .claude/skills/ に置く場合はworkspace trustダイアログを受諾した後に効きます。リポジトリを信頼するかどうかの判断材料になるので、レビュー対象に含める価値があります。

context: fork で別エージェント実行

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

context: fork を付けると、Skillの本文が別のsubagentのシステムプロンプトとして実行されます。agent で実行先subagentを指定可能(Explore / Plan / general-purpose / カスタムsubagent)。長尺の調査・解析をSkill化しつつ、メインcontextを汚さない設計が組めます。

文字列置換変数(運用上の必修知識)

Skill本文には以下のプレースホルダが使えます。手順書型・副作用つきSkillでは特に頻出です。

例:

---
name: fix-issue
description: Fix a GitHub issue by number
disable-model-invocation: true
---
 
Fix GitHub issue $ARGUMENTS following coding standards.

引数を本文中で参照していない場合は、Claude Codeが自動で ARGUMENTS: <入力> を末尾に追記するので、引数が完全に無視されることはありません。

バンドルSkillsと .claude/commands/ の関係

自作する前に、標準で何が提供されているかを押さえておくと選択肢を狭めずに済みます。

バンドルSkills

Claude Codeは /simplify / /batch / /debug / /loop / /claude-api 等のバンドルSkillを全セッションで提供しています(commandsリファレンスにSkillマーク付きで掲載)。多くの組み込みコマンドが固定ロジックなのに対し、バンドルSkillはプロンプトベースでClaudeにツールを使わせる方式なので、自作Skillと同じ感覚で /skill-name で呼べます。

.claude/commands/ からSkillsへの統合

公式は Custom commands have been merged into skills. と明示しています。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy を作り、同じように動きます。既存の .claude/commands/ ファイルはそのまま動き続けますが、同名でSkillとCommandが両方ある場合はSkillが優先されます。「Skillのほうがディレクトリでサポートファイルを持てる / フロントマターで自動呼び出し制御ができる」ため、新規作成はSkills側を選ぶのが現代の推奨です。

monorepoのnested .claude/skills/

monorepoで packages/frontend/.claude/skills/ のようにnestedに置かれたSkillは、packages/frontend/ 配下のファイルを操作するときにオンデマンドで自動発見されます。--add-dir で追加したディレクトリ内の .claude/skills/ も例外的にロードされる仕様(他の .claude/* は --add-dir ではloadedされない)。リポジトリ全体でSkillを共有しつつ、パッケージ固有のSkillだけはnestedに置く分散運用が可能です。

作成すべき / 作成すべきでない判断軸

Skill化の効果は「反復性 × 手順性」で見ると判断しやすくなります。

Skills vsその他レイヤの使い分け

「SkillかCLAUDE.mdかSubagentかMCPか」は混乱しがちです。「いつ何がcontextに入るか」で見ると整理できます。

同じ知識をCLAUDE.mdとSkillのどちらに書くか

「毎ターン読まれる必要があるか」が分岐基準です。読まれる必要があるならCLAUDE.md、特定の場面でだけ読まれれば十分ならSkill。

Skills vs Subagents

「メイン会話の中で何かを完了させたい」ならSkill、「メイン会話を汚さず別contextで完了させたい」ならSubagent。両者の組み合わせとして、Subagentの skills フィールドでSkill内容を起動時にcontextへ注入する設計もできます。Subagentの自作判断はサブエージェント作成ガイドで扱っています。

失敗パターンと回避策

1. description が抽象的すぎて呼ばれない

description: Helper for git のような曖昧な説明だとClaudeが文脈一致を判断できません。「いつ・何を・どう判定するか」を1,536字以内で先頭に書きます。トリガフレーズ(「コミットしたい」「diffを見たい」)を入れると自動呼び出しが効きやすくなります。

2. SKILL.mdが肥大化(500行超え)

公式は Keep SKILL.md under 500 lines. を推奨。500行を超えるとinvoke時のcontext圧迫が大きくなります。長尺の参照資料は同ディレクトリ内の別ファイル(reference.md / examples.md)に切り出し、SKILL.mdから「必要時にReadしてください」と参照させる形が定石です。

3. invoke後にコンテキストに居座り続ける

Skill本文は一度invokeされるとセッション中ずっとcontextに残ります。Auto compaction後でも各Skillの先頭5,000トークンまでが再注入されますが、複数Skill間で合計25,000トークンの共有予算になっており、最近invokeしたSkillから順に埋まります。古いSkillはcompaction後にまるごとdroppedされることもある仕様です。長尺Skillを1セッションに多数invokeすると累積でcontextを食うので、呼ぶたびに必要な本文だけにする / 参照を別ファイルに切る設計が安全です。

4. disable-model-invocation 漏れによる事故

/deploy のような副作用つきSkillから disable-model-invocation: true が抜けていると、Claudeが「コードが完成したからdeployしよう」と判断して勝手に発動する可能性があります。副作用がある全Skillにこのフラグを付ける運用を徹底します。

5. allowed-tools の過剰許可

allowed-tools: Bash だけ書くとすべてのBashコマンドが承認なしに実行可能になります。Bash(git add *) Bash(git commit *) のようにサブコマンドまで明示するのが安全。Bash(rm *) のような破壊的操作は絶対に明示許可しない。

6. CLAUDE.mdとSkillの重複

「コミットメッセージは日本語で書く」をCLAUDE.mdと /commit の両方に書くと、片方更新が漏れたときに矛盾が出ます。重複が見つかったらCLAUDE.md側に統一(常時効く前提なので)、Skill側はリンクで参照する設計に倒すのが運用上のセオリーです。

トラブルシューティング(公式記載のチェック項目)

公式 /doctor で診断できる主な観点を挙げます。

• Skillが呼ばれない → description の具体性 / What skills are available? で表示されるか
• 逆に呼ばれすぎる → description を狭く / disable-model-invocation: true を検討
• descriptionが途中で切れている → skillListingBudgetFraction でcontext予算を増やすか、skillOverrides で利用頻度の低いSkillを name-only に格下げ
• Skill編集が反映されない → 親ディレクトリの .claude/skills/ をライブ監視する仕様。新規ディレクトリ作成時はセッション再起動が必要

skillOverrides で個別Skillの表示状態を制御する

.claude/settings.local.json の skillOverrides で、各Skillの見え方を4段階で制御できます。/skills メニューで対象Skillをハイライトし Space キーで循環、Enter で保存できます。

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

Bundled / Managed / Plugin Skillsは skillOverrides の対象外です(プラグインは /plugin で管理)。

Skill別に許可 / 拒否するpermission rules

/permissions でSkill単位の許可・禁止を書けます。

# 特定Skillだけ許可
Skill(commit)
Skill(review-pr *)
 
# 特定Skillを禁止
Skill(deploy *)

Skill(name) は完全一致、Skill(name *) は前方一致(引数付きで呼ばれてもマッチ)。disable-model-invocation: true はfrontmatterでSkill自身が宣言する方式、Skill(name) のpermission ruleはsettingsで外側から制御する方式と位置付けが違います。

disableSkillShellExecution で ! 注入を全停止

managed settingsで "disableSkillShellExecution": true を設定すると、!`<command>` のシェル注入をポリシーで全停止できます(Bundled / Managed Skillsは影響を受けない)。企業環境で「外部のSkillにシェルを走らせたくない」要件があるときに使います。

まとめ

Skills自作のROIは「手順反復性 / 動的データ注入 / 副作用つき操作のコマンド化 / プロジェクト規約の適用範囲制御」のいずれかに該当するかで決まります。

• 最小単位は .claude/skills/<name>/SKILL.md のYAMLフロントマター + Markdown本文
• スコープはEnterprise > Personal > Projectの優先順位
• 効くフィールドは description / disable-model-invocation / allowed-tools / context: fork
• CLAUDE.mdは常時 / Skillは呼び出し時 / Subagentは別context、と投入タイミングで使い分ける
• 「手順反復 + 動的データ + 副作用つき操作」のいずれかが当てはまるSkillから作り始めると効果が出やすい

書き方の具体パターンはSkillsの書き方5パターン集、設計思想の背景はAgent Skillsとは何か、SkillかSubagentかの判断軸はサブエージェント作成ガイド、CLAUDE.md・Settingsとの関係はClaude Codeのメモリ三層構造も合わせて参照してください。