Skills（スキル）入門

Skill（スキル）とは何か

Skill は、Claude に特定の作業の「やり方」を教えるための、整理されたフォルダです。正式には Agent Skills と呼ばれ、手順書（説明書）に作業の流れや知識をまとめておくと、関連するタスクが来たときに Claude がそれを読み込んで、その通りに作業します。

身近な例えでいうと、Skill は「業務マニュアル」のようなものです。普段は棚にしまってあり（コンテキストを消費しない）、必要になったときだけ棚から出して読みます。Claude 本体（司令塔）が、そのマニュアルを見ながら自分の頭で作業を進めるイメージです。

一言でいうと、Skill は「Claude に知識を足す」しくみ。常に全部を覚えさせるのではなく、必要になったときに必要な分だけ開く——これが後で説明する段階的開示の考え方につながります。

Claude を拡張する4つの手段

Skill を正しく位置づけるために、混同しやすい4つを整理しておきます。

• CLAUDE.md：プロジェクト全体に常に効く前提・ルール（就業規則のようなもの）。
• Skill：特定タスクの手順・知識を必要なときだけ注入（業務マニュアル）。実行するのはメインの Claude。
• Subagent：仕事を丸ごと委任する、独立した文脈を持つ別の Claude（専門スタッフ）。
• MCP / Tool：外部サービスや API への接続口（外線電話）。

このうち Skill は「専門知識・手順書」を担当し、Claude が会話の内容から「いま使うべきか」を自動で判断するのが特徴です。

なぜ Skill が必要なのか

• 再現性：「この手順で処理して」を毎回打たなくても、一貫した品質で実行される。
• 専門知識の注入：社内の命名規則・独自フォーマット・業界ルールなど、Claude が知らない知識を渡せる。
• コンテキスト節約：全部を常時読ませると重い。Skill は必要なときだけ開くので軽い。
• 共有・再利用：フォルダを配るだけで、チーム全員が同じ Skill を使える。

Skill が「発動」する仕組み

あなたが Skill を明示的に呼ばなくても、Claude が会話の内容を見て「これは○○ Skill の出番だ」と自動判断します。その判断材料が、各 Skill の description（説明文）です。だから description の書き方が最重要になります（後述）。

もちろん明示呼び出しも可能で、Claude Code ではユーザーが /スキル名 と打って直接起動することもできます。

Skill のファイル構造

Skill の実体はとてもシンプルで、「1つのフォルダ ＋ その中の SKILL.md という説明書」＝ 1つの Skillです。手順書だけでなく、補助スクリプト・テンプレート・参考資料なども同梱できます。

.claude/skills/
└─ pdf-processing/         ← Skill 名＝フォルダ名（kebab-case 推奨）
   ├─ SKILL.md             ← 【必須】説明書（frontmatter ＋ 本文）
   ├─ reference.md         ← 任意：詳細リファレンス（必要時に開く）
   ├─ scripts/
   │  └─ extract.py        ← 任意：実行可能なスクリプト
   └─ templates/
      └─ report.md         ← 任意：テンプレート等の資産

必須なのは SKILL.md だけです。これが1枚あれば、それだけで立派な Skill になります。補助ファイルは必要になってから足せば OK です。

置き場所（スコープ）

Skill は有効範囲によって置き場所が変わります。起動時、Claude はこれらの場所をすべて読み込んでマージします。

• 個人用（Personal）：~/.claude/skills/ に置く。自分の全プロジェクトで効く。Windows では ~ は C:\Users\<ユーザー名>\ に相当。
• プロジェクト用（Project）：リポジトリ内の .claude/skills/ に置く。そのプロジェクト限定で、git に入れればチーム共有できる。
• プラグイン経由・組み込み：プラグインや Claude Code 本体に同梱。後述の組み込みスキルはフォルダには現れない。

使い分けの指針：「どこでも使う自分の道具」は個人用へ、「このリポジトリ固有の作法」はプロジェクト用へ。同名なら一般にプロジェクト側が優先（個別の上書き）です。

SKILL.md の書き方

SKILL.md はfrontmatter（メタ情報）と本文（手順）の2部構成です。frontmatter はファイル冒頭の --- で囲まれた YAML、本文はそのあとに続く Markdown です。

# ① frontmatter（YAML）— メタ情報。発動判定にも使われる
---
name: pdf-processing
description: PDFからのテキスト抽出・フォーム記入・ページ結合を行う。
  ユーザーがPDFの中身を読む/編集する/分割・結合すると言ったら使う。
---

# ② 本文（Markdown）— Claude への実際の指示書
# PDF Processing

## いつ使うか
ユーザーがPDFファイルの操作を求めたとき。

## 手順
1. まず scripts/extract.py でテキスト層を確認する。
2. テキストが無ければOCRにフォールバックする。
3. ...

frontmatter の重要項目

frontmatter は Skill の「顔」であり、ここの品質が発動精度を左右します。主な項目は次の3つです。

• name（必須）：Skill 名。小文字＋ハイフン（kebab-case）。フォルダ名と一致させる。
• description（必須）：最重要。「何をする Skill か」＋「いつ使うか」を具体的に書く。Claude はこれを読んで発動可否を判断する。
• allowed-tools（任意）：この Skill 実行中に使えるツールを限定する。安全性の向上に有効。

description は具体的に書く

Claude は description を読んで、そのスキルを使うかどうかを判断します。そのため「何をするか」だけでなく「いつ使うか（どんな言葉が出たら）」まで書くことが、正しく発動させる最大のコツです。

• 悪い例：description: PDFを扱うスキル。 — 抽象的すぎて、Claude が「いつ使えばいいか」判断できず、発動しない／誤発動する。
• 良い例：description: PDFからのテキスト/表の抽出、フォーム入力、ページの分割・結合・回転を行う。ユーザーがPDFを「読む・埋める・分割・結合する」と言及したら使う。 — 「何を」「どんな言葉が出たら」が明確。

鉄則：description は「第三者（未来の Claude）への発注書」だと思って書く。一人称ではなく「〜のとき使う」という発動トリガーを必ず含めること。

段階的開示（Progressive Disclosure）

Skill が賢く・軽量に動く理由がこれです。Skill の全ファイルを常にコンテキストへ読み込むとすぐにパンクするので、Claude は3段階で、必要な情報だけを開いていきます。

1. レベル1：name と description だけ（起動時・常に見える）
   起動時、Claude は全 Skill の name と description だけを把握している。コストはごくわずか。「どんな道具箱があるか」のカタログ状態。
2. レベル2：SKILL.md 本文（発動時に開く）
   会話が description にマッチすると、その Skill の本文を読み込む。ここで具体的な手順を理解する。
3. レベル3：同梱ファイル（さらに必要なら開く）
   本文中で参照された reference.md やスクリプトを、その時になって初めて開く・実行する。

この仕組みのおかげで、たとえ100個のスキルがあっても起動時のコストは最小限で済みます。起動時に読むのはレベル1のメタデータだけで、実際に使うスキルだけがレベル2・3の詳細を読み込むためです。

設計のコツ：SKILL.md 本文は簡潔に保ち、長大な詳細・データ・例は別ファイルに切り出して「必要なら reference.md を読め」と書く。これがプロの書き方です。

ハンズオン：Skill を作ってみる

実際に「コミットメッセージ規約」を強制する Skill を作る流れを体験します。

ステップ1：フォルダを作る

# PowerShell
New-Item -ItemType Directory -Force "$HOME\.claude\skills\commit-style"

ステップ2：SKILL.md を書く

作成したフォルダの中に SKILL.md を置き、frontmatter と本文を書きます。

---
name: commit-style
description: Gitコミットメッセージを社内規約（Conventional
  Commits + 日本語要約）に整形する。ユーザーがコミットを作る/
  メッセージを書くと言ったら使う。
---

# コミットメッセージ規約

## フォーマット
`<type>(<scope>): <日本語の要約>`

- type: feat / fix / docs / refactor / test / chore
- 要約は 50 文字以内、句点なし
- 本文がある場合は1行空けて記述

## 例
feat(auth): ログイン失敗時のリトライ処理を追加

## 禁止
- "update" や "fix bug" など内容の無い要約
- 過去形（"added"）は使わず現在形で

ステップ3：使う

あとは普通に「コミットして」と頼むだけです。Claude が description を見て自動でこの Skill を発動し、規約通りのメッセージを作ります。明示するなら /commit-style と打ちます。

もっと楽に作るには：Anthropic は Skill 作成を支援する skill-creator という Skill も提供しています。「Skill を作って」と頼めば、対話しながら雛形を生成してくれます。

組み込みスキル一覧

Claude Code には最初から多くのスキルが同梱されています。多くは /スキル名 で明示的に呼び出せます。代表的なものを系統別に挙げます。

開発・レビュー系

• code-review：現在の差分をレビューし、バグや簡素化できる箇所を指摘。深さ（effort）を調整できる。
• review：プルリクエスト（PR）をレビューする。
• security-review：未コミットの変更にセキュリティ上の問題がないか監査する。
• simplify：変更箇所を再利用・簡素化・効率の観点で整理し、修正まで適用する（バグ探しはしない）。
• verify：変更が意図通り動くか、実際にアプリを動かして挙動を確認する。

リサーチ・設定・運用系

• deep-research：多数の Web 検索を展開し、出典を精査・検証して引用付きレポートに統合する。
• update-config：settings.json を編集。権限の追加・環境変数・フック（自動化）の設定。
• keybindings-help：キーボードショートカットのカスタマイズ。
• fewer-permission-prompts：よく使う安全なコマンドを許可リスト化し、権限確認を減らす。
• schedule / loop：定期実行のリモートエージェント作成や、一定間隔での繰り返し実行。

起動・連携系

• run：プロジェクトのアプリを起動し、変更が動く様子を確認する。
• init：コードベースを解析して CLAUDE.md を新規作成する。
• claude-api：Claude API / Anthropic SDK アプリの構築・デバッグ・最適化を支援する。

同梱スキルの顔ぶれは環境・バージョン・導入プラグインによって増減します。Claude Code で / と打つと、今使えるスキル一覧が表示されます。まず手元のカタログを眺めるのが上達の近道です。

まとめ：よい Skill のための指針

• 1スキル ＝ 1目的：欲張らず、明確な目的をひとつだけ持たせる。
• description を具体的に：発動条件（いつ使うか）を明示する。
• 段階的に詳細化：本文は簡潔にし、詳しい内容は別ファイルに分ける。
• スクリプトを活用：複雑な処理は Python スクリプトなどに任せる。