はじめに

Claude Codeを使っていて、こんな経験はありませんか？

「毎回同じような指示を書くのが面倒...」
「CLAUDE.mdが肥大化してトークンを圧迫している」
「MCPを設定したけど、使い方の指示はどこに書けばいい？」

2025年10月にAnthropicがリリースしたAgent Skillsは、まさにこれらの課題を解決するために設計された機能です。

この記事では、公式ドキュメントに基づいて、Skillsの仕組みを図解で解説し、従来手法との違いをAs-Is / To-Be分析とFit & Gap分析で整理します。

この記事で学べること

Skillsとは何か、どう動くのか（シーケンス図で理解）
従来手法（プロンプト、CLAUDE.md、MCP）との違い
どの場面でSkillsを使うべきか（Fit & Gap分析）
最初のSkillを作る手順

想定読者

Claude Codeを使ったことがある方
Python/bashの基本知識がある方
Skillsを聞いたことはあるが、まだ使っていない方

1. Skillsとは何か

公式定義

Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant.

— Anthropic公式ドキュメント

一言でいうと、Skillsは「Claudeに特定のタスクのやり方を教えるパッケージ」 です。

新入社員に渡すオンボーディング資料のようなもので、必要なときだけ参照される点が特徴です。

Skillsの全体像

従来手法との根本的な違い

観点	従来のプロンプト	CLAUDE.md	MCP	Skills
読み込みタイミング	毎回全文	毎回全文	起動時に全ツール定義	必要時のみ
トークン消費	大	大	大	小
再利用性	低	中	高	高
目的	一時的な指示	プロジェクト規約	外部接続	手順・知識

参考: Skills vs MCP: Key Differences Explained

2. As-Is分析：従来手法の課題

2.1 毎回プロンプトで説明する方法

現状（As-Is）

ユーザー: PDFからテキストを抽出して。pdfplumberを使って、
テーブルも抽出して、JSONで出力して...（以下、毎回同じ説明）

課題

同じ指示を何度も書く手間
指示の一貫性が保てない
トークンの無駄遣い

2.2 CLAUDE.mdに全て書く方法

現状（As-Is）

# CLAUDE.md（肥大化した例）

## コーディング規約
...（500行）

## PDF処理の手順
...（200行）

## Excel操作の手順
...（300行）

## テスト方法
...（400行）

課題

毎回全文がコンテキストに読み込まれる
関係ないタスクでもトークンを消費
1,000行を超えると管理が困難

Think of skills as modular chunks of a CLAUDE.md file. Instead of Claude reviewing a massive document every time, skills let Claude access specific expertise only when needed.

— alexop.dev

2.3 MCPサーバーとの役割の混同

現状（As-Is）

MCPで外部接続を設定したが、「どう使うか」の指示がない。

// MCP設定
{
  "mcpServers": {
    "github": { "command": "mcp-server-github" }
  }
}

Claude: GitHubに接続できますが、PRレビューの観点や
フォーマットは指示がないので一般的な方法で行います...

課題

MCPは「接続」を提供するが「手順」は提供しない
使い方の指示が別途必要
トークン消費が大きい（全ツール定義が常時ロード）

As-Is課題マップ

3. To-Be分析：Skillsによる理想の姿

3.1 Progressive Disclosure（段階的開示）

Skillsの最大の特徴はProgressive Disclosureです。

At startup, the agent pre-loads the name and description of every installed skill into its system prompt. This metadata is the first level of progressive disclosure: it provides just enough information for Claude to know when each skill should be used without loading all of it into context.

— Anthropic Engineering Blog

3.2 再利用性とチーム共有

# プロジェクトスキルとしてgit管理
.claude/skills/
├── code-review/
│   └── SKILL.md
├── testing/
│   └── SKILL.md
└── documentation/
    └── SKILL.md

# チームメンバーは git pull するだけで利用可能
git pull
claude  # スキルが自動的に利用可能

To-Be理想状態

4. Skillsの仕組み

4.1 ディレクトリ構造

配置場所

種類	パス	用途
Personal Skills	`~/.claude/skills/`	個人用、全プロジェクト共通
Project Skills	`.claude/skills/`	チーム共有、git管理
Plugin Skills	プラグイン内	プラグイン経由で配布

参考: Claude Code Skills公式ドキュメント

4.2 SKILL.mdの書き方

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

Extract text with pdfplumber:
python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

## Advanced features

**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods

必須フィールド

フィールド	制限	説明
`name`	最大64文字、小文字・数字・ハイフンのみ	スキル名
`description`	最大1024文字	何をするか + いつ使うかの両方を記載

命名規則

Skillsには厳格な命名規則があります。

ファイル名

ファイル	規則
メインファイル	`SKILL.md`（必須、大文字小文字は区別しない）
参照ファイル	任意の名前（例: `reference.md`, `FORMS.md`）
スクリプト	`scripts/` ディレクトリ内に配置推奨

nameフィールドの規則

規則	詳細
使用可能文字	小文字（a-z）、数字（0-9）、ハイフン（-）のみ
最大文字数	64文字
禁止語	`anthropic`, `claude` は使用不可
XMLタグ	使用不可

推奨される命名パターン

公式ドキュメントでは 動名詞形（-ing） が推奨されています。

# ✅ 推奨：動名詞形
name: processing-pdfs
name: analyzing-spreadsheets
name: generating-commit-messages

# ⚠️ 許容：名詞形
name: pdf-processor
name: spreadsheet-analysis

# ❌ 避ける：曖昧・汎用的
name: helper
name: utils
name: tools

We recommend using gerund form (verb + -ing) for Skill names, as this clearly describes the activity or capability the Skill provides.

— Skill authoring best practices

ディレクトリ構成の例

~/.claude/skills/
├── processing-pdfs/          # ディレクトリ名はnameと揃える
│   ├── SKILL.md              # 必須（大文字推奨）
│   ├── FORMS.md              # 参照ファイル
│   └── scripts/
│       └── extract.py        # ユーティリティスクリプト
└── generating-commit-messages/
    └── SKILL.md

descriptionの書き方（重要）

The description field is critical for Claude to discover when to use your Skill.

— Skill authoring best practices

# ❌ 悪い例：曖昧
description: Helps with documents

# ✅ 良い例：具体的 + トリガー条件
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

4.3 Claudeがスキルを読み込む流れ

The skill selection mechanism has no algorithmic routing or intent classification at the code level. Claude Code doesn't use embeddings, classifiers, or pattern matching to decide which skill to invoke. Instead, the system formats all available skills into a text description embedded in the Skill tool's prompt, and lets Claude's language model make the decision.

— Claude Agent Skills: A First Principles Deep Dive

5. Fit & Gap分析

5.1 Skills vs 従来プロンプト

評価軸	従来プロンプト	Skills	適合度
繰り返し作業	毎回記述	一度定義	✅ Skills優位
一貫性	人依存	標準化	✅ Skills優位
即座の変更	容易	再起動必要	⚠️ プロンプト優位
一回限りの指示	最適	過剰	❌ プロンプト優位

結論: 繰り返すタスクはSkills、一回限りはプロンプト

5.2 Skills vs CLAUDE.md

評価軸	CLAUDE.md	Skills	適合度
トークン効率	常時全文読込	必要時のみ	✅ Skills優位
プロジェクト規約	最適	過剰	❌ CLAUDE.md優位
複雑なワークフロー	肥大化	モジュール化	✅ Skills優位
常に適用すべきルール	最適	発動条件必要	❌ CLAUDE.md優位

結論: 常時適用ルールはCLAUDE.md、タスク固有手順はSkills

Skills are more token-efficient because Claude Code only loads them when needed. If you want something simpler, you can put a condensed version in ~/.claude/CLAUDE.md instead, but that gets loaded into every conversation whether you need it or not.

— ykdojo/claude-code-tips

5.3 Skills vs MCP

評価軸	MCP	Skills	適合度
外部システム接続	可能	不可	❌ MCP必須
リアルタイムデータ	可能	不可	❌ MCP必須
手順・ベストプラクティス	なし	提供	✅ Skills優位
トークン効率	低（全定義読込）	高	✅ Skills優位
設定の複雑さ	高	低	✅ Skills優位

結論: 併用が最適。MCPで接続、Skillsで手順を提供。

MCP connects Claude to external services and data sources. Skills provide procedural knowledge—instructions for how to complete specific tasks or workflows. You can use both together: MCP connections give Claude access to tools, while Skills teach Claude how to use those tools effectively.

— What are Skills? | Claude Help Center

5.4 ユースケース別適合性マトリクス

適合性判断表

ユースケース	推奨手法	理由
GitHubからPRを取得してレビュー	MCP + Skills	接続（MCP）+ レビュー観点（Skills）
PDF処理（抽出、フォーム記入）	Skills	ローカル処理 + 複雑な手順
コーディング規約の適用	CLAUDE.md	常時適用すべきルール
一度きりのデータ変換	プロンプト	再利用性なし
Excelレポート作成	Skills	複雑なワークフロー
Slack通知送信	MCP + Skills	接続（MCP）+ フォーマット（Skills）

6. 実践ガイド：最初のSkillを作る

作成フロー

Step 1: ディレクトリ作成

# Personal Skill（個人用）
mkdir -p ~/.claude/skills/commit-helper

# または Project Skill（チーム共有用）
mkdir -p .claude/skills/commit-helper

Step 2: SKILL.md作成

cat > ~/.claude/skills/commit-helper/SKILL.md << 'EOF'
---
name: commit-helper
description: Generate clear commit messages from git diffs. Use when writing commit messages, reviewing staged changes, or asking for help with git commits.
---

# Commit Message Generator

## Instructions

1. Run `git diff --staged` to see changes
2. Analyze the changes and identify:
   - What was changed
   - Why it might have been changed
   - Which components are affected

## Commit message format

<type>(<scope>): <subject>

<body>

### Types
- feat: New feature
- fix: Bug fix
- docs: Documentation
- refactor: Code refactoring
- test: Adding tests
- chore: Maintenance

## Example

Input: Added user authentication with JWT tokens

Output:

feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware.
Includes refresh token support and secure cookie handling.

EOF

Step 3: テスト

# Claude Codeを再起動
claude

# テスト依頼
> コミットメッセージを書いて

Step 4: 発動しない場合の対処

If Claude doesn't use your Skill, check these common issues:

Is the description specific enough?

Is the YAML valid?

Is the Skill in the correct location?

— Claude Code Skills公式ドキュメント

# descriptionを具体的に
description: Generate clear commit messages from git diffs. Use when writing commit messages, reviewing staged changes, or asking for help with git commits.

7. ベストプラクティス

公式ドキュメントから、特に重要なポイントを抜粋します。

簡潔さが最重要

The context window is a public good. Your Skill shares the context window with everything else Claude needs to know.

— Skill authoring best practices

# ❌ 悪い例（約150トークン）
"""
PDF（Portable Document Format）ファイルは一般的なファイル形式で、
テキスト、画像、その他のコンテンツを含みます。テキストを抽出するには
ライブラリが必要です。pdfplumberをお勧めします...
"""

# ✅ 良い例（約50トークン）
"""
## Extract PDF text
Use pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
"""

500行以内に収める

Keep SKILL.md body under 500 lines for optimal performance.

— Skill authoring best practices

超える場合は、参照ファイルに分割します。

参照は1階層まで

# ✅ 良い構造
SKILL.md → reference.md
SKILL.md → examples.md

# ❌ 悪い構造（ネストが深い）
SKILL.md → advanced.md → details.md

三人称で記述

# ❌ 避ける
description: I can help you process Excel files

# ✅ 推奨
description: Processes Excel files and generates reports

8. まとめ

Skillsの位置づけ

手法	役割	使い分け
プロンプト	一時的な指示	一回限りのタスク
CLAUDE.md	プロジェクト規約	常時適用すべきルール
MCP	外部接続	リアルタイムデータアクセス
Skills	手順・知識	繰り返す複雑なワークフロー

今日から始められること

小さく始める: 繰り返している作業を1つ特定
SKILL.md作成: 手順をMarkdownで記述
テスト: 発動するか確認、descriptionを調整
チーム共有: Project Skillsとしてgit管理

参考リンク

公式ドキュメント

Anthropic公式

解説記事

この記事がSkillsを始めるきっかけになれば幸いです。

質問やフィードバックがあれば、コメントでお知らせください。