STOP Inc.

【開発者向け】Claude Code Skillsの使い方｜仕組み・実装・運用Tips

2026.05.23
#Claude Code #生成AI #開発効率化

Claude Codeを使っていて、「同じ指示を毎回CLAUDE.mdに書いている」「プロジェクト固有のワークフローをチームで共有したい」と感じたことはないでしょうか。そんなときに役立つのが「Skills（スキル）」という仕組みです。

Skillsは、Claudeに専門的な知識・手順・ワークフローを後付けで教え込める拡張機能です。SKILL.mdというMarkdownファイルを1つ用意するだけで、PDFの読み取り、デプロイ手順、コードレビュー、社内ルール準拠の文書作成など、あらゆる作業をClaudeに専門家レベルで任せられるようになります。

本記事では、Claude CodeのSkillsについて、仕組み・作り方・YAMLフロントマターの詳細・実践的なコツまで開発者向けにまとめます。

Skillsとは何か

ひとことで言うと「Claudeの専門スキルセット」

Skillsとは、Claudeに特定のタスクの進め方を教える「再利用可能な指示書」です。1つのSkillは、最低限SKILL.mdというMarkdownファイル1つから構成され、必要に応じてスクリプト・テンプレート・参照資料を同梱できます。

たとえば「PDF処理スキル」を作っておけば、ユーザーが「このPDFを要約して」と頼んだとき、Claudeは自動的にそのスキルを発見し、定義された手順に従って作業を進めます。

CLAUDE.mdやコマンドとの違い

  • CLAUDE.md：プロジェクト全体に常に効く「グローバル指示」
  • Skills：必要なときだけ呼び出される「専門的な手順書」
  • Commands：従来のスラッシュコマンドは、現在Skillsに統合済み

CLAUDE.mdに大量の指示を書くと、毎ターン全部がコンテキストに乗ってトークンを消費します。Skillsは「必要なときだけロードされる」のが最大のメリットです。

Progressive Disclosure（段階的開示）の仕組み

Claude Codeは起動時に、利用可能なすべてのSkillsをスキャンしますが、読み込むのはnameとdescriptionのみ。1スキルあたり約100トークンしか消費しません。

そして、ユーザーのタスクに該当するSkillが見つかったときだけ、SKILL.md本体の全文がコンテキストに展開されます。さらに必要であれば、SKILL.md内で参照されているreferences/やscripts/のファイルが読み込まれる、という3段階の構造になっています。

Skillsのディレクトリ構造

Skillの基本構造は以下のとおりです。

my-skill/
├── SKILL.md          # 必須：YAMLフロントマター + Markdown指示
├── scripts/          # 任意：実行可能なスクリプト
│   └── process.py
├── references/       # 任意：必要時に読み込む参照ドキュメント
│   └── schema.md
└── assets/           # 任意：出力に使うテンプレート・アイコンなど
    └── template.docx

Claude Codeでは、以下のいずれかのディレクトリに配置すれば自動的に認識されます。

  • .claude/skills/（プロジェクト単位）
  • ~/.claude/skills/（ユーザー単位、全プロジェクト共通）

SKILL.mdの書き方

基本構造

SKILL.mdは「YAMLフロントマター」＋「Markdown本文」の2部構成です。

---
name: pdf-processor
description: PDFファイルからテキストやテーブルを抽出し、要約や分析を行う。ユーザーがPDFの読み取り、内容抽出、PDF解析を依頼したときに使用する。
---

# PDF Processor

## 目的
PDFファイルを処理し、構造化された情報を抽出する。

## 手順
1. `scripts/extract.py` を使ってテキストを抽出
2. テーブルがあれば `scripts/extract_tables.py` で構造化
3. 必要に応じて要約を生成

## 注意点
- スキャンPDF（画像化されたPDF）の場合はOCRを実行
- 大容量ファイル（50MB超）は分割処理

YAMLフロントマターの主要フィールド

フィールド必須説明
name推奨スキル名。スラッシュコマンドにも使われる（最大64文字）
description必須「何をするか」「いつ使うか」を記述。Claudeが自動発火するかを決める最重要フィールド
allowed-tools任意このスキル実行時に使えるツールを制限（例: Read, Grep）
disable-model-invocation任意trueにすると自動発火を無効化、ユーザーが明示的に呼ぶ場合のみ動作
model任意このスキル実行時のモデルを上書き指定

descriptionの書き方が9割

Claudeはdescriptionを読んで「今このスキルを使うべきか」を判断します。ここを雑に書くと、必要なときに発火しなかったり、逆に毎回発火して邪魔になったりします。

悪い例

description: コードを手伝う          # ← 曖昧すぎて常に発火する
description: APIを叩く              # ← 実装の説明、ユースケースが不明

良い例

description: >
  JiraとGitHubからデータを取得し、週次スプリントレポートを生成する。
  スプリントレビューやステークホルダー報告の準備時に使用する。
  ベロシティチャートとブロッカー一覧を含むMarkdownを出力する。

「何をするか」「いつ使うか」「何が得られるか」の3点を必ず含めましょう。また、Claudeはやや「発火しにくい」傾向があるので、descriptionは少し“押し出し気味”に書くのがコツです。

実践例：シンプルなSkillを作ってみる

「コミットメッセージを規約通りに書かせる」スキルを作ってみましょう。

ステップ1：ディレクトリ作成

mkdir -p .claude/skills/commit-message
touch .claude/skills/commit-message/SKILL.md

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

---
name: commit-message
description: >
  Conventional Commits規約に従ったGitコミットメッセージを生成する。
  ユーザーがコミットを作成する、コミットメッセージを書くと依頼したとき、
  またはgit commitコマンドを実行する前に使用する。
allowed-tools: Bash, Read
---

# Conventional Commit Message Generator

## 手順
1. `git diff --staged` でステージされた変更を確認
2. 変更内容から適切なtypeを判定
3. 以下の形式でメッセージを生成

## フォーマット
```
<type>(<scope>): <subject>

<body>

<footer>
```

## type一覧
- feat: 新機能
- fix: バグ修正
- docs: ドキュメント変更
- style: フォーマット変更（機能影響なし）
- refactor: リファクタリング
- test: テスト追加・修正
- chore: ビルド・補助ツール変更

## ルール
- subjectは50文字以内、命令形、末尾にピリオドなし
- 破壊的変更は footer に `BREAKING CHANGE:` で明記
- 日本語の場合も同じ構造で記述

ステップ3：使ってみる

Claude Codeのセッション内で以下のように呼び出します。

# 明示的に呼ぶ
/commit-message

# または自然な依頼でも発火する
> 今ステージされている変更にコミットメッセージをつけて

これだけで、チーム全員が同じ規約に沿ったコミットメッセージを生成できる環境ができあがります。

supporting files（補助ファイル）を活用する

SKILL.md本体は1,500〜2,000語以内に抑えるのが推奨されています。詳細はサブディレクトリに分離しましょう。

scripts/ — 決定論的な処理

毎回同じロジックで実行したい処理はスクリプト化します。Pythonで書いておけば、Claudeが必要に応じて実行してくれます。

scripts/
├── extract_tables.py    # PDF表抽出
└── validate_schema.py   # JSONスキーマ検証

references/ — 必要時に読む詳細資料

長大なAPI仕様書、社内ルール、データベーススキーマなど、毎回読み込む必要のない情報はここに置き、SKILL.mdから「必要に応じて参照」と指示します。

assets/ — 出力テンプレート

Wordテンプレート、ロゴ画像、CSSファイルなど、生成物に組み込む素材を格納します。

Skillsを書くときのベストプラクティス

  1. SKILL.mdは簡潔に：1,500〜2,000語が目安。詳細はreferences/へ
  2. 「Whatをする」を書く：「How」「Why」の説明は最小限に。手順を淡々と書く
  3. descriptionは具体的に：トリガーワードを含め、ユースケースを明示
  4. allowed-toolsで権限を絞る：必要なツールだけ許可することで安全性が高まる
  5. テストする：実際にClaudeに依頼してみて、想定通り発火・動作するか確認
  6. 1つのSkillに1つの責務：肥大化したら分割する

公開・配布の方法

チーム内で共有

プロジェクトルートの.claude/skills/をGit管理下に置けば、リポジトリをcloneするだけでチーム全員が同じスキルを使えます。

オープンソースで公開

SkillsはAgent Skillsオープン標準に準拠しているため、Claude Codeだけでなく、Cursor、Gemini CLI、GitHub Copilot、OpenAI Codex CLIなど他のAIコーディングツールでもそのまま使えます。

GitHubには既に1,000以上のコミュニティ製スキルが公開されており、Anthropic公式リポジトリ（anthropics/skills）にもサンプルが豊富にあります。

よくあるハマりどころ

  • Skillが発火しない → descriptionが曖昧。「いつ使うか」を明確に書く
  • YAMLパースエラー → インデントはスペース2つで統一、タブを使わない。---で挟むのを忘れない
  • 毎回発火して鬱陶しい → descriptionが広すぎ。スコープを絞るかdisable-model-invocation: trueを設定
  • references/が読まれない → SKILL.md内で「references/xxx.mdを参照すること」と明示的に指示する必要がある
  • context windowが膨れる → SKILL.md本体に詳細を詰め込みすぎ。references/に逃がす

まとめ

Claude CodeのSkillsは、AIエージェントに「専門知識」を後付けでインストールできる強力な仕組みです。

  • 必要なときだけ読み込まれるのでコンテキスト消費が小さい
  • SKILL.md 1ファイルから始められる
  • scripts/ references/ assets/ で拡張可能
  • Agent Skillsオープン標準なので他ツールとも互換性あり
  • チーム内・OSSコミュニティで共有可能

「同じ指示を毎回書いている」「プロジェクトの暗黙知をAIに渡したい」と感じている方は、まず1つだけ小さなSkillを書いてみることをおすすめします。コミットメッセージ生成、PR説明文の作成、ログ調査の定型手順など、定型作業を1つSkill化するだけで体験が大きく変わります。

※本記事の情報は2026年5月時点のものです。Skillsの仕様は活発に進化しているため、最新情報はClaude Code公式ドキュメントでご確認ください。

関連記事