Claude Code の Agent Skills は設定したほうがいい

**投稿者:** kuroneko (@_kuroneko_jp)

**元記事著者:** syu-m-5151 (nwiizo)

**投稿日時:** 2025年1月15日

**URL:** https://x.com/_kuroneko_jp/status/2011490663284818268

**記事URL:** https://syu-m-5151.hatenablog.com/entry/2025/12/19/173309

**エンゲージメント:** 116リポスト / 1,153いいね / 1,391ブックマーク / 31万表示

---

概要

Claude Codeの「Agent Skills」について詳細に解説した記事。「このプロジェクトではpython-pptxを使ってスライドを作って」「SQLは必ずこのフォーマットで」といった説明を毎回繰り返す問題を解決する機能。

---

なぜSkillsが必要か

LLMはステートレスで、セッション間で記憶を保持しない。トークン制約とコスト制約があるため、すべての知識を常に保持できない。**Agent Skillsは、必要な時に必要な知識だけを読み込む仕組み**。

「エージェントにSkillを作ることは、新入社員向けのオンボーディングガイドを作るようなもの」 — Anthropic公式ブログ

---

他の設定との違い

| 機能 | 役割 | 例 |

|-----|------|-----|

| CLAUDE.md | プロジェクトの文脈を伝える | 「うちはTypeScriptで、こういうアーキテクチャ」 |

| commands | 手動で呼び出すショートカット | /test-and-commit で一連の作業を実行 |

| Hooks | 特定のイベントで自動実行 | ファイル保存後に自動フォーマット |

| Subagents | 専門家を自動で呼び出す | デバッグ時にdebugger subagentが起動 |

| Rules | パス単位でルールを適用 | src/api/**/*.tsにセキュリティルール |

| **Agent Skills** | 専門知識をオンボーディング | PDF操作、Excel分析、独自ワークフロー |

**Skillsのポイント**: 「Claudeができること自体を拡張する」。他の設定がClaudeの「使い方」を定義するのに対し、SkillsはClaudeの「専門知識」を拡張する。

---

Tool、Skills、MCPの違い

| 概念 | 役割 | たとえ |

|-----|------|--------|

| Tool | 何ができるか（Capability） | 店にある道具そのもの |

| MCP | 道具へのアクセス（Connectivity） | 店の通路に入ること |

| Skills | どう振る舞うか（Behavior） | 道具の使い方を教える店員 |

---

Progressive Disclosure（段階的開示）

すべての情報を最初から渡すのではなく、必要になったタイミングで必要な情報だけを渡す設計原則。

3段階での情報開示

1. **Level 1: メタデータ（常にロード）** - 約100トークン/Skill

- name/descriptionだけ読み込み

2. **Level 2: 指示（トリガー時にロード）** - 5000トークン以下が目安

- SKILL.mdの本文

3. **Level 3: リソース（必要時にロード）**

- 追加のファイル、スクリプト、リファレンス

---

SkillsとSubagentsの使い分け

| 観点 | Skills | Subagents |

|-----|--------|-----------|

| コンテキスト | 親と共有 | 独立 |

| 向いているタスク | 継続的な作業、TDDなど | 試行錯誤、調査タスク |

| 状態の引き継ぎ | あり | なし（結果のみ返す） |

**判断基準:**

コンテキストを共有したい → Skills
コンテキストを独立させたい → Subagents
タスクの結果が「要約」で十分ならSubagent、「過程」も重要ならSkills

---

カスタムSkillの作成

基本構造

---
name: my-custom-skill
description: このSkillが何をするか、いつ使うべきかを説明。
---

# My Custom Skill

## 指示
[具体的な手順をここに書く]

## 例
[実際の使用例]

配置場所

| タイプ | パス | スコープ |

|-------|------|---------|

| 個人 | ~/.claude/skills/ | 全プロジェクト共通 |

| プロジェクト | .claude/skills/ | 現在のプロジェクトのみ |

---

ベストプラクティス

1. 簡潔に書く

Claudeが既に知っていることは書かない。冗長なSkillはトークン消費とノイズを増やす。

2. 自由度を適切に設定

高自由度（テキスト指示）: 複数のアプローチが有効な場合
低自由度（具体的スクリプト）: 操作がデリケートな場合

3. フィードバックループを入れる

複雑なワークフローでは検証ステップを入れる。

4. ネストを深くしない

参照ファイルはSKILL.mdから1階層までに留める。

---

よくある失敗と対策

| 問題 | 原因 | 対策 |

|-----|------|------|

| Skillがトリガーされない | descriptionが曖昧 | 「何をするか」と「いつ使うか」を明記 |

| コンテキスト不足 | SKILL.mdに情報が足りない | 参照ファイルを追加 |

| トークン消費が多すぎる | Progressive Disclosureしてない | 情報を複数ファイルに分割 |

| 出力が不安定 | 自由度が高すぎる | 具体的なテンプレートや例を追加 |

---

参考資料

[awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) - 100+の実戦投入可能なSkills
[Agent Skills - Anthropic Engineering Blog](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
[Agent Skills Overview - Claude Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)

---

*保存日: 2026-01-30*