はじめに

2025 年 12 月、Anthropic が Claude Code の Agent Skills 機能を発表しました。その直後から OpenAI、GitHub Copilot、Cursor など競合が相次いで類似機能を発表し、急速に業界標準化が進んでいます。

「要はスラッシュコマンドの進化版でしょ？」「プロンプトを保存しておける機能ね」

そう思った方も多いのではないでしょうか。実は、この理解は本質を捉えていません。

この記事では、Agent Skills の正しい理解と、実際に動く Skill の作成方法をお伝えします。「スラッシュコマンドの延長」ではない設計思想を理解することが、Agent Skills を活用するための第一歩です。

Agent Skills とは何か

よくある誤解

Agent Skills を「保存されたプロンプト」と理解している方は多いです。確かに、SKILL.md という Markdown ファイルに指示を書くという点では、従来のスラッシュコマンドと表面的には似て見えます。

しかし、この理解では重要な特徴を見落としてしまいます。

本質：Context Engineering フレームワーク

Agent Skills の本質は、Context Engineering（コンテキスト設計）のフレームワークです。以下の 4 つの特徴がその核心を表しています。

特徴	説明
ドメイン固有知識の提供	特定ワークフローのベストプラクティスをパッケージ化
再利用可能なリソース	スクリプト・テンプレートをアセットとして配布
オンデマンドロード	必要なときだけ読み込み、コンテキストを節約
エージェントの自律判断	ユーザーが呼び出さなくても AI が自動で適用

Slash Commands との決定的な違い

従来の Slash Commands との違いを整理しましょう。

項目	Slash Commands	Agent Skills
動作	メインセッションにプロンプトを「追加」	処理を別コンテキストに「分離」して結果だけ戻す
起動	ユーザーが明示的に叩く	エージェントが自動判断で適用
本質	保存されたプロンプト	Context 設計フレームワーク

最も重要な違いはコンテキストの扱いです。Slash Commands はメインの会話に「決め打ちのプロンプトを追加する」仕組みでした。一方、Agent Skills は「処理そのものを別コンテキストに分離して、結果だけ戻す」仕組みです。

これにより、複雑なワークフローでもコンテキストを消費しすぎることなく、効率的に処理を進められます。

最小構成を理解する

配置場所

Skill は 2 つの場所に配置できます。

~/.claude/skills/        # 個人用（全プロジェクト共通）
.claude/skills/          # プロジェクト用

個人で繰り返し使う Skill は ~/.claude/skills/ に、特定プロジェクト専用の Skill は .claude/skills/ に配置します。

最小構成

驚くべきことに、Skill を作るために必要なのは SKILL.md ファイル 1 つだけです。

追加で以下のディレクトリも用意できますが、最初は不要です。

scripts/ - 自動化スクリプト
references/ - 参考ドキュメント
assets/ - テンプレート

まずは SKILL.md だけで始めて、必要に応じて拡張していくのがおすすめです。

Progressive Disclosure 設計

Agent Skills は、すべての情報を一度に読み込むのではなく、段階的に読み込む設計になっています。

Discovery: メタデータ（約 100 トークン）だけをスキャン
Loading: 関係ありそうな Skill の SKILL.md を読み込み
Execution: 実行時に必要な追加ファイルを読み込み

この設計により、コンテキストウィンドウを効率的に利用でき、多数の Skill を登録しても動作が重くなりません。

【ハンズオン】最初の Skill を作る

実際に手を動かして、最初の Skill を作成してみましょう。

【作成する】Skill: code-explainer

今回作成するのは、コードを解説し、Mermaid ダイアグラムで図解する「code-explainer」スキルです。

この Skill を選んだ理由は 3 つあります。

シンプルで実用的
Skill の基本構造を学べる
結果が視覚的にわかりやすい

Step 1：ディレクトリ作成

ターミナルで以下のコマンドを実行します。

mkdir -p ~/.claude/skills/code-explainer

Step 2：SKILL.md 作成

~/.claude/skills/code-explainer/SKILL.md を作成し、以下の内容を記述します。

---
name: code-explainer
description: コードファイルを読み込み、処理フローを Mermaid ダイアグラムで図解しながら解説するスキル
---

# Code Explainer

## 目的

指定されたコードファイルを読み込み、以下を生成する：

1. コードの概要説明（何をしているか）
2. 処理フローの Mermaid ダイアグラム
3. 重要なポイントの箇条書き

## 出力形式

### 概要
（コードの役割を 1-2 文で説明）

### 処理フロー
```mermaid
graph TD
    A[開始] --> B[処理1]
    B --> C[処理2]
    C --> D[終了]
```

### 重要ポイント
- ポイント 1
- ポイント 2
- ポイント 3

Step 3: 動作確認

Claude Code を起動して、動作を確認しましょう。

claude

起動したら、以下のように依頼してみてください。

> src/main.py を解説して

期待される動作

Claude Code が code-explainer スキルを自動で認識
description の内容に基づいて適用を判断
SKILL.md の指示に従った形式で出力

ユーザーが明示的にスキルを呼び出さなくても、AI が「コードを解説してほしい」というリクエストに対して自動的に code-explainer スキルを適用します。これが Agent Skills の「自律判断」という特徴です。

うまくいかない場合のチェックリスト

動作しない場合は、以下を確認してください。

ファイル名が SKILL.md（大文字）になっているか
YAML フロントマターの形式（--- で囲む）が正しいか
description が具体的に書かれているか

特に description は重要です。エージェントがスキルを適用するかどうかの判断材料になるため、抽象的すぎると認識されにくくなります。

SKILL.md の書き方詳細

効果的な Skill を書くためのポイントを解説します。

YAML フロントマターの重要性

SKILL.md の冒頭には、YAML フロントマターでメタデータを記述します。

---
name: skill-name           # 必須: スキル名（識別子）
description: 説明文         # 重要: エージェントの判断に使用
version: 1.0.0             # 任意: バージョン管理
author: your-name          # 任意: 作者情報
---

最も重要なのは description です。これはエージェントがスキルを適用するかどうかを判断する材料となります。

本文 Markdown の設計原則

SKILL.md の本文は、以下の 4 つの原則を意識して書きましょう。

明確な目的: 何をするスキルかを冒頭に記述
具体的な手順: ステップバイステップで処理を記述
出力形式の定義: 期待する出力フォーマットを明示
制約条件: やらないこと、注意点も記載

良い description の例

description は具体的に書くことが重要です。

# NG: 抽象的すぎる
description: コードを説明する

# OK: 具体的で判断しやすい
description: コードファイルを読み込み、処理フローを Mermaid ダイアグラムで図解しながら解説する

NG の例では「コードを説明する」としか書かれていないため、どのような場面で使うべきか判断しにくくなっています。OK の例では「Mermaid ダイアグラムで図解」という具体的なアウトプットが示されているため、エージェントが適切に判断できます。

より実践的な構造へ

基本を理解したら、より実践的な構造への拡張を検討しましょう。

フルセットの構造例

code-explainer/
├── SKILL.md                  # 本体
├── scripts/
│   └── extract_functions.py  # 関数抽出スクリプト
├── references/
│   └── mermaid-syntax.md     # Mermaid 記法リファレンス
└── assets/
    └── template.md           # 出力テンプレート

各ディレクトリの使い分け

ディレクトリ	用途	例
`scripts/`	機械的処理の外出し	ファイル操作、データ整形
`references/`	知識の外部化	ガイドライン、仕様書
`assets/`	テンプレート類	出力フォーマット

scripts/ には、LLM に処理させるとコスパが悪いファイル操作や整形処理を外出しします。references/ には、必要なときだけ取りに行く「教科書」のような知識を配置します。

発展的なトピック

本記事では入門にフォーカスしましたが、Agent Skills にはさらに深いトピックがあります。

agents/ ディレクトリと Task 設計: 複数の Task を連携させるワークフロー
MCP との使い分け: 外部サービス連携との棲み分け
チームでの共有とバージョン管理: プロジェクト単位での Skill 管理

これらは別の記事で詳しく解説する予定です。

まとめ

この記事で学んだこと

Agent Skills は「保存されたプロンプト」ではなく「Context Engineering フレームワーク」
最小構成は SKILL.md 1 つだけで動く
4 つの本質的特徴：ドメイン知識、再利用性、オンデマンドロード、自律判断
実際に code-explainer スキルを作成し、動作を確認

次のステップ

まずは今回作成した code-explainer を使ってみてください。そして次は、自分の業務に合わせたオリジナルの Skill を作ってみましょう。

自分の業務フローを Skill 化してみる
公式スキルコレクション（document-skills 等）を試す
scripts/ や references/ を活用した拡張に挑戦

参考リンク