Claude Code Skills 完全ガイド 2026年5月版 — 公式仕様・自作の作り方・おすすめ10選を実装視点で

エンジニアのゆとです。

Claude Code の「Skills」を本気で触り始めて2週間、自作Skillを12個作ってフリーランス業務を運用してみた。結論から言うと、CLAUDE.md とサブエージェントの中間に位置する仕組みで、「毎回同じ手順を書いていた作業」が一発で呼べるようになる。

ただし、ネット上の解説記事は2025年10月リリース直後のものが多く、2026年5月時点の最新仕様とズレているものが目立つ。本記事では公式ドキュメントを1行ずつ読み直して、SKILL.md frontmatter の全16項目・配置の4階層・動的コンテキスト注入・context: fork でのサブエージェント実行まで、実装視点で整理した。

おすすめSkill 10選はフリーランスエンジニアが「毎日使う」前提で選定した。サンプルコードもそのまま動く形で載せてある。

Claude Code Skills とは（公式定義）

Skills は SKILL.md ファイルに書かれた手順書を Claude Code が必要なときだけロードする仕組みだ。

公式ドキュメントの表現を借りると、こうなる:

Skills extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with /skill-name.

ポイントは「必要なときだけロードされる」こと。CLAUDE.md は常時コンテキストに乗るが、Skills は frontmatter の description だけが起動時に読み込まれ、本体は invoke されたタイミングで初めてコンテキストに入る。

これが何を意味するか:

• 100KB の手順書を Skills 化しておいても、起動時のトークン消費はほぼゼロ
• Claude が description を見て自動判定 or /skill-name で明示呼び出し
• 一度 invoke されると、その会話セッション中はコンテキストに残る（auto-compaction時は最新5,000トークン分が再注入される）

2026年5月時点の最新仕様（重要）

公式ドキュメントを読み直して、ネット上の古い解説と差分があったポイントを先に列挙する:

1. カスタムコマンドは Skills に統合された: 過去の .claude/commands/deploy.md は今も動くが、新規は .claude/skills/deploy/SKILL.md を使う方が推奨。同名なら Skills が優先される
2. Bundled skills が増えた: /simplify, /batch, /debug, /loop, /claude-api などが標準同梱
3. frontmatter フィールドが大幅に拡張: 旧来の name description allowed-tools に加えて、context agent model effort paths shell hooks argument-hint arguments などが追加
4. 動的コンテキスト注入の !command` 構文: シェルコマンドを Skills 内に埋め込んで、その出力を Claude に渡せる
5. context: fork でサブエージェント実行: Skill 自体をサブエージェントに切り出して並列実行できる

CLAUDE.md / AGENTS.md / Subagents との違い

ここが一番こんがらがる。整理する。

仕組み	ロードタイミング	用途	例
CLAUDE.md	常時ロード（セッション開始時）	プロジェクト全体の前提知識・ルール	コーディング規約、禁止事項
AGENTS.md	常時ロード（CLAUDE.md と並列）	Codex/Cursor等とも共通の規約	マルチツール対応の共通ルール
Skills	invoke 時のみロード	手順書・タスク特化のプロンプト	”/deploy” “/commit” “/security-review”
Subagents	委譲時に別コンテキストで実行	並列処理、コンテキスト隔離	大規模リファクタの分割実装

判断フロー:

• 常に従わせたいルール → CLAUDE.md / AGENTS.md
• 特定のタスクで毎回同じ手順を踏ませたい → Skills
• コンテキストを汚さず別作業として走らせたい → Subagents
• Skills を別コンテキストで走らせたい → Skills with context: fork（最新の合わせ技）

Skills の4階層配置

公式ドキュメントは配置場所を「誰が使えるか」で4階層に分けている:

階層	パス	影響範囲
Enterprise	managed settings 経由	組織全体
Personal	~/.claude/skills/<skill-name>/SKILL.md	全プロジェクト
Project	.claude/skills/<skill-name>/SKILL.md	このプロジェクトのみ
Plugin	<plugin>/skills/<skill-name>/SKILL.md	プラグインが有効な場所

優先順位: Enterprise > Personal > Project（同名 Skill があれば上位が勝つ）。Plugin は plugin-name:skill-name の名前空間を持つので衝突しない。

フリーランス運用なら、基本は Personal (~/.claude/skills/) に置く。クライアント別のルールがあるなら Project に置いて Git にコミットする。

モノレポでの自動発見

Claude Code は編集中ファイルから親方向に .claude/skills/ を探す。packages/frontend/ で作業していれば packages/frontend/.claude/skills/ も自動的に発見される。モノレポでパッケージごとのルールが必要なときに便利。

SKILL.md frontmatter 完全リファレンス（必須2項目 + オプション14項目）

ここが本記事の主軸。公式ドキュメントから全16フィールドを抽出した。

必須（または強く推奨）

フィールド	型	内容
name	string	スキル表示名。lowercase + 数字 + ハイフンのみ、64文字以内。省略時はディレクトリ名
description	string	何をするか・いつ使うか。最大1024文字、ただし when_to_use と合算で1,536文字までしか表示されない

description は Skills discovery の心臓部。Claude はこれを見て呼び出すかどうかを判断する。「Use when the user asks about X」「Triggers on Y」のような「いつ使うか」を必ず含める。

オプション（推奨度順）

---
name: commit
description: Stage and commit current changes. Use when user asks to commit, save changes, or finalize work.
when_to_use: Trigger phrases — "commit this", "save my changes", "create a commit"
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
disable-model-invocation: true
user-invocable: true
argument-hint: "[commit message]"
arguments: message
model: claude-sonnet-4-5
effort: medium
context: fork
agent: general-purpose
paths: "src/**, scripts/**"
shell: bash
hooks:
  before-skill:
    - command: "./.claude/hooks/pre-commit-check.sh"
---

各フィールドの実用ポイント:

• when_to_use: trigger phrases を箇条書きで書くと自動 invoke の精度が上がる
• allowed-tools: Bash の細かいサブコマンド（Bash(git add *) のように引数パターンで）まで指定可能。これを書いておくと「権限ダイアログを毎回出さない」が実現できる
• disable-model-invocation: true: Claude が勝手に呼ばないようにする。deploy・publish・send系の副作用ある Skills では必須
• user-invocable: false: 逆に Claude だけが呼べる「背景知識」用。/legacy-system-context のように人間がコマンドとして打つ必要がない知識
• argument-hint / arguments: スラッシュコマンドのオートコンプリート用のヒントと、本文中で $0 $1 $ARGUMENTS として参照可能な引数定義
• model + effort: その Skill の間だけモデル・思考強度を切り替えられる。重い分析だけ Opus に切り替えるみたいな運用が可能
• context: fork + agent: Explore: Skill 全体をサブエージェントに分離して、メインコンテキストを汚さずに走らせる
• paths: glob パターンで「この path のファイルを触っているときだけ自動 invoke」を制限できる
• shell: powershell: Windows で !command 注入を powershell で走らせたいとき（CLAUDE_CODE_USE_POWERSHELL_TOOL=1` 必要）

最小構成のSKILL.md（hello-world、3行レベル）

まずは何の変哲もない hello world を書いてみる。

mkdir -p ~/.claude/skills/say-hello

---
description: Say hello to the user in a friendly tone. Use when user types "hello", "hi", or asks for a greeting.
---

Greet the user warmly. Mention something positive about their work in the current directory if relevant.

このまま claude を起動して「hello」と打つだけで、Claude が say-hello Skill を invoke してくれる。これだけ。name は省略するとディレクトリ名（say-hello）が自動で使われる。

ただ、これは「skill とは何か」を理解するためのサンプル。実務では次の章のような書き方をする。

実用Skillの作り方（動的コンテキスト注入 + helper scripts）

実用Skillの典型パターンを 3 つ示す。

パターン1: コミットメッセージ生成（git diff を動的注入）

---
name: write-commit
description: Generate a Conventional Commit message from staged changes. Use when the user asks for a commit message or wants to commit changes.
allowed-tools: Bash(git diff *) Bash(git status *)
---

## Staged changes

!`git diff --cached`

## Status

!`git status --short`

## Instructions

Generate a Conventional Commit message based on the changes above. Format:
- First line: `<type>(<scope>): <subject>` (max 72 chars)
- Body: bullet points describing the change
- Footer: `BREAKING CHANGE:` or `Closes #N` if applicable

Types: feat, fix, docs, style, refactor, perf, test, chore, build, ci

!git diff —cached` の部分が動的コンテキスト注入。Skill 起動時にシェルコマンドが実行され、その出力が Claude に渡される前処理。Claude にコマンド実行させているわけではなく、Claude Code がプリプロセスする。

この Skill を /write-commit で呼ぶと、ステージング済みの差分を見て Conventional Commits 形式のメッセージを返してくれる。1秒で commit メッセージが完成する。

パターン2: PRレビュー（gh CLI を活用、サブエージェント分離）

---
name: review-pr
description: Review a pull request in depth. Use when user asks to review a PR, check code quality, or wants feedback on changes.
context: fork
agent: Explore
allowed-tools: Bash(gh pr *)
argument-hint: "[PR number]"
arguments: pr_number
---

## PR context
- Diff: !`gh pr diff $pr_number`
- Files: !`gh pr diff --name-only $pr_number`
- Comments: !`gh pr view $pr_number --comments`

## Your task

Review PR #$pr_number with these criteria:
1. Code correctness and edge cases
2. Test coverage (does this need new tests?)
3. Security issues (auth, input validation, secrets)
4. Performance hot paths
5. Readability and naming

Output a markdown report with sections "✅ Good" / "⚠️ Concerns" / "🔴 Blockers".

context: fork + agent: Explore でサブエージェントとして実行される。メインコンテキストを汚さず、PRレビュー用に最適化された read-only 環境で走る。/review-pr 123 のように引数を渡せる。

パターン3: 重い分析を Opus + max effort で

---
name: architect-review
description: Architectural review of recent changes. Use when user asks about overall design quality, refactor opportunities, or architectural concerns.
model: claude-opus-4-7
effort: max
allowed-tools: Bash(git log *) Bash(git show *) Read Grep
---

## Recent commits
!`git log --oneline -20`

## Your task

Walk through the recent 20 commits and evaluate:
1. Coupling between modules
2. Layering violations
3. Repeated patterns that could be abstracted
4. Hidden dependencies

Produce a markdown report with concrete refactor candidates.

model: claude-opus-4-7 + effort: max でこの Skill の間だけハイモデル・最大思考強度に切り替える。セッション全体は Sonnet で回しつつ、重い分析だけピンポイントで Opus にする運用が可能。

動的コンテキスト注入（!command` 構文）の詳細

!command` は Skill 起動時に「Claude Code がプリプロセスとして」コマンドを実行し、その出力で置き換える仕組み。Claude はコマンドを実行していない。Claude が見るのは最終結果だけ。

複数行コマンドは fenced code block で書く:

## Environment
```!
node --version
npm --version
git status --short
```

セキュリティ的に無効化したい場合は settings に "disableSkillShellExecution": true を入れる。組織全体で禁止したいときは managed settings で固定。

!command` で使える組み込み変数:

$\{CLAUDE_SESSION_ID\}  ← 現在のセッションID（ログ用途）
$\{CLAUDE_EFFORT\}       ← 現在の effort レベル（low/medium/high/xhigh/max）
$\{CLAUDE_SKILL_DIR\}    ← Skill 自身のディレクトリ（helper script の絶対パス参照用）

これらは Skill 本文や !command内で$VAR/scripts/helper.py` のような形で参照する（実際の表記はドル記号+中括弧+変数名）。

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

context: fork を frontmatter に書くと、Skill 全体がサブエージェントとして走る。メインの会話履歴は引き継がず、Skill 本文がそのままサブエージェントの prompt になる。

---
name: deep-research
description: Research a topic thoroughly across the codebase. Use when user asks for in-depth exploration.
context: fork
agent: Explore
arguments: topic
---

Research $topic in this codebase:

1. Find all relevant files with Glob and Grep
2. Read each file fully
3. Map dependencies between modules
4. Summarize findings with specific file:line references

Output as markdown with sections: Overview / Key Files / Dependencies / Recommendations.

agent: Explore を指定すると、Read-only ツール（Read/Grep/Glob/WebFetch）に限定された Explore subagent で実行される。agent: Plan だと計画立案用の subagent、agent: general-purpose だと全ツール使える汎用 subagent。

Skills と Subagents は組み合わせて使うのが正解で、公式ドキュメントは2方向の関係を示している:

アプローチ	システムプロンプト	タスク	補助ロード
Skill with context: fork	agent type の標準 prompt	SKILL.md の本文	CLAUDE.md
Subagent with skills field	Subagent の本文	Claude の委譲メッセージ	Preloaded skills + CLAUDE.md

つまり、Skill を別コンテキストで走らせたいなら context: fork、Subagent に最初から Skills を持たせておきたいなら Subagent の skills フィールドで preload。

フリーランスエンジニア向けおすすめSkill 10選

実際に2週間運用して効果があった Skills を10個。フリーランス業務（コーディング・契約管理・経理・記事執筆）を想定して選んだ。

1. /commit — Conventional Commits 自動生成

パターン1の write-commit をそのまま使う。git diff から Conventional Commit メッセージを生成。手動で commit メッセージを書く時間がゼロになる。

2. /security-review — 変更ファイルのセキュリティレビュー

git diff を読んで、credential 漏洩・SQL injection・XSS・パストラバーサルの可能性をチェック。context: fork + agent: Explore で実装。

3. /explain-this — 既存コードの仕組み説明

カーソル位置のファイル or ディレクトリを読んで、依存関係・呼び出し関係・データフローを Markdown で説明。新規プロジェクト join 時に超便利。

4. /test-gen — テストコード生成

対象関数を $ARGUMENTS で受けて、エッジケース3つを含む Jest/pytest コードを生成。テスト書きの初動を爆速にする。

5. /refactor — リファクタ候補抽出

直近20コミットの変更ファイルを読んで、重複コード・抽象化候補・命名揺れを抽出。model: claude-opus-4-7 で精度上げる。

6. /invoice — 請求書テンプレ生成（freee連携）

クライアント名・期間・金額を $ARGUMENTS で受けて、freee API 経由で請求書ドラフトを作成。CLAUDE.md と組み合わせると会社情報を毎回打たなくて済む。

7. /blog-stock — ブログ記事ストック追加（yuto-lab用）

タイトル・スラッグ・キーワードを受けて、src/content/blog/ に draft:true で .mdx を生成し RELEASE_SCHEDULE.json にも登録。

8. /db-explore — DBスキーマ探索

!psql -c ‘\dt’ で全テーブル取得、!psql -c '\d <table>' で詳細取得。普段は ER 図を見ない案件で素早く把握。

9. /release-notes — リリースノート生成

最新タグから HEAD までの commit を !git log` で取得して、ユーザー向けの changelog を生成。Conventional Commits ベースだと精度が高い。

10. /lawyer-eye — 契約書チェック

契約書 PDF を渡すと、不利な条項（責任無制限・著作権譲渡・違約金・期間自動更新）を抽出。フリーランス契約のチェック用。法的アドバイスではなくチェックリスト用途。

これら10個を ~/.claude/skills/ に置くだけで、日々の作業時間が体感30%は減る。

自作Skillの設計パターン（DO / DON’T）

公式 Best Practices ドキュメントから抽出した、自作するときに守るべきポイント:

DO

• description は third person で書く: 「I can help you…」「You can use this to…」は NG。「Processes Excel files and generates reports」のような客観表現
• 「いつ使うか」を含める: trigger phrases や utterance 例を具体的に
• gerund form の命名: processing-pdfs / analyzing-spreadsheets のような動名詞形
• SKILL.md 本文は 500 行以内: 超えるなら reference file に分割
• Reference は1階層まで: SKILL.md → reference.md は OK、reference.md → details.md は NG（Claude が partial read で full read しない可能性）
• disable-model-invocation を副作用ある Skills に: deploy / publish / send 系
• allowed-tools で過剰に絞らない: 必要な権限を漏らすと毎回確認ダイアログ
• !command` で動的に最新情報を注入: 静的な手順書より価値が上がる

DON’T

• 「これも、あれも選べる」と複数選択肢を提示: デフォルトを1つ示してエスケープハッチを最後に
• Magic Number を埋め込む: TIMEOUT = 47 ではなく「30秒は通常のHTTPで十分」とコメント
• Windows パス（バックスラッシュ）: 全 OS で forward slash
• 時限情報を本文に書く: 「2025年8月以前は」のような時系列依存は「Old patterns」セクションに隔離
• 「I can help you process Excel…」のような第一人称: discovery が乱れる

デバッグとトラブルシューティング

Skill が期待通りに動かないときのチェックリスト:

自動 invoke されない

1. description に trigger phrases が入っているか
2. What skills are available? で表示されるか
3. description 文字数が1,536字を超えていないか（超えると truncate される）
4. paths 設定で除外されていないか

逆に invoke されすぎる

1. description が抽象的すぎる → 具体的な trigger に絞る
2. disable-model-invocation: true で手動限定にする

説明が cut short される

• /doctor で skill listing budget overflow をチェック
• skillListingBudgetFraction を 0.02（2%）に上げる、または SLASH_COMMAND_TOOL_CHAR_BUDGET で固定値指定
• 重要度の低い Skills を skillOverrides で "name-only" にする

本文がコンテキストから消えた

• Auto-compaction で古い Skills が削除された
• 再 invoke すると full content が復元される

Skills と Subagents の使い分け

最後にこれだけ覚えておけば運用できる:

• 同じ操作を Claude にやってほしい → Skills（手順書を毎回呼び出す）
• 重い処理を裏で並列実行したい → Subagents（コンテキスト隔離）
• Skill を別コンテキストで実行したい → Skills + context: fork
• Subagent に最初から知識を持たせたい → Subagent の skills field で preload

Skills が万能ではない。例えば「巨大なリファクタを分割して並列実行」は Subagents の領域。「決まった手順で commit メッセージを書く」は Skills の領域。

関連リソース

公式:

• Extend Claude with skills（公式docs）
• Skill authoring best practices
• anthropics/skills（公式リファレンス）

コミュニティ:

• ComposioHQ/awesome-claude-skills（49,500+ stars）
• VoltAgent/awesome-agent-skills（13,400+ stars）
• hesreallyhim/awesome-claude-code

FAQ

Skills と CLAUDE.md はどう使い分ける？

CLAUDE.md は「常に守ってほしいルール」、Skills は「特定のタスクの手順書」。長くなった CLAUDE.md のセクションが「手順」になっていたら Skills 化を検討する。Skills は invoke 時のみロードされるので、CLAUDE.md を肥大化させずに知識を増やせる。

disable-model-invocation: true を付けるべき Skills は？

副作用が大きいもの全部。/deploy /publish /send-message /commit のような書き込み・送信系は、Claude が勝手に呼ばないように手動限定にする。逆に /summarize-changes のような read-only 系は自動 invoke で OK。

context: fork と Subagents はどっちを使うべき？

Skill を「タスクとして」走らせたいなら context: fork。Subagent を「再利用可能な専門エージェント」として定義したいなら .claude/agents/ に書く。両者は逆向きの関係で、Skills は Subagent に preload もできる。

Skills の本文がコンテキストから消えました

Auto-compaction の影響。再 invoke すれば full content が復元される。頻繁に使う Skill は description を強化して常に上位に呼び出されやすくする、または disable-model-invocation: true を外して自動 invoke 対象にする。

Plugin 経由の Skills と Personal の Skills の優先順位は？

Plugin は plugin-name:skill-name の名前空間を持つので衝突しない。同名でも別 Skill として扱われる。一方、Personal / Project / Enterprise は同名衝突時に Enterprise > Personal > Project の優先度。

Skills で MCP ツールを呼びたい

ServerName:tool_name の完全修飾名で書く（例: BigQuery:bigquery_schema）。プレフィックスを省略すると、複数 MCP サーバーがある環境で「ツールが見つからない」エラーになる。

まとめ

Claude Code Skills は「CLAUDE.md とサブエージェントの中間」を埋める仕組みだ。常時ロードされない・必要なときだけ呼ばれる・helper scripts も持てる・サブエージェント化もできる。

2026年5月時点で description の書き方・allowed-tools の粒度・context: fork の使い方の3つを抑えると、フリーランス業務の30%は自動化できる感触がある。

まずは本記事の最小構成 hello-world を作って、/say-hello で動くことを確認してから おすすめ10選 のうち1つを真似て自作してみるのがおすすめ。

関連記事

記事が見つかりません:

記事が見つかりません:

記事が見つかりません:

記事が見つかりません:

記事が見つかりません: