Claude Code Agent Skills を強化する三銃士 — scripts / references / assets の使い分け

@shuhei_ohno 氏が X で投稿した、Claude Code の Agent Skills を強化するディレクトリ構造の解説が注目を集めています。

Agent Skill をもっと強くする三銃士！scripts / references / assets の使い方

Claude Code の Skills 機能は SKILL.md 1 ファイルで完結するものと思われがちですが、実際には scripts / references / assets の 3 つのサポートディレクトリを活用することで、はるかに強力な自動化が可能になります。本記事では、この 3 つのディレクトリの役割と設計パターンを、公式ドキュメントの知見を交えて解説します。

Agent Skills の基本構造

SKILL.md がすべての起点

Claude Code の Skill は、.claude/skills/ ディレクトリに配置された SKILL.md ファイルを起点として動作します。

.claude/skills/
└── my-skill/
    ├── SKILL.md          ← エントリポイント（必須）
    ├── scripts/          ← 実行可能なコード
    ├── references/       ← 参照ドキュメント
    └── assets/           ← テンプレート・バイナリ

SKILL.md は Markdown 形式で記述し、オプションの YAML フロントマターでメタデータを設定します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

---
name: deploy
description: プロダクション環境へのデプロイ
user-invocable: true
allowed-tools:
  - Bash
  - Read
  - Write
---

# デプロイスキル

## 手順

1. テストを実行する
2. ビルドを作成する
3. デプロイを実行する

user-invocable: true を設定すると、ユーザーが /deploy のようにスラッシュコマンドとして呼び出せます。

なぜサポートディレクトリが必要なのか

SKILL.md だけでも基本的なスキルは作れます。しかし、実用的なスキルを構築しようとすると、以下の問題に直面します。

SKILL.md だけの場合の問題:

  1. 複雑なロジック → Markdown にコードを直接書くと読みにくい
  2. 長い参照情報 → SKILL.md が肥大化してコンテキストを圧迫
  3. テンプレート → 出力のひな形を SKILL.md 内に埋め込むと煩雑

これらの問題を解決するのが、scripts / references / assets の 3 つのサポートディレクトリです。

scripts — 実行可能なコードを分離する

役割

scripts/ ディレクトリには、Claude が Bash ツール経由で実行する Python スクリプトやシェルスクリプトを配置します。

my-skill/
├── SKILL.md
└── scripts/
    ├── validate.py       ← バリデーションロジック
    ├── transform.sh      ← データ変換処理
    └── deploy.py         ← デプロイ実行

最大の利点 — コンテキスト効率

scripts/ の最大の利点は、スクリプト本体がコンテキストに載らないことです。

コンテキストの使われ方:

  SKILL.md の記述:
    「scripts/validate.py を実行してください」
    → SKILL.md のテキストのみがコンテキストに載る

  Claude の実行:
    Bash ツールで python scripts/validate.py を実行
    → スクリプト本体はコンテキストに載らない
    → 実行結果（stdout）だけがコンテキストに載る

100 行の Python スクリプトをそのまま SKILL.md に書くと数百トークンを消費しますが、scripts/ に分離すれば SKILL.md 側は「このスクリプトを実行せよ」の 1 行で済みます。

実践例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# scripts/check_migrations.py
"""Django マイグレーションの整合性チェック"""
import subprocess
import json
import sys

result = subprocess.run(
    ["python", "manage.py", "showmigrations", "--plan"],
    capture_output=True, text=True
)

unapplied = [
    line.strip() for line in result.stdout.splitlines()
    if line.strip().startswith("[ ]")
]

if unapplied:
    print(json.dumps({"status": "pending", "migrations": unapplied}))
    sys.exit(1)
else:
    print(json.dumps({"status": "ok", "message": "All migrations applied"}))

SKILL.md 側の記述:

1
2
3
4
5

## マイグレーションチェック

デプロイ前に `scripts/check_migrations.py` を実行し、
未適用のマイグレーションがないことを確認する。
pendingがある場合はデプロイを中止する。

Claude はこの指示を読み、Bash ツールでスクリプトを実行し、JSON 出力を解析して次のアクションを決定します。

scripts の設計原則

公式ドキュメントが推奨する設計原則があります。

references — 参照ドキュメントを分離する

役割

references/ ディレクトリには、スキルの実行時に Claude が参照する必要があるドキュメントを配置します。

my-skill/
├── SKILL.md
└── references/
    ├── api-spec.md       ← API 仕様書
    ├── coding-style.md   ← コーディング規約
    └── error-codes.md    ← エラーコード一覧

Markdown リンクによる遅延読み込み

references/ のファイルは、SKILL.md から Markdown リンクで参照します。

1
2
3

## コーディング規約

コードを書く際は [コーディング規約](references/coding-style.md) に従ってください。

この仕組みのポイントは 遅延読み込み（Lazy Loading） です。SKILL.md が読み込まれた時点では references/ の内容はコンテキストに載りません。Claude が「コーディング規約を確認する必要がある」と判断した時点で、Read ツールを使ってファイルを読み込みます。

コンテキスト効率:

  × references/ の内容を SKILL.md に全て埋め込む
    → 初回読み込みで数千トークン消費

  ○ Markdown リンクで参照
    → 必要な時だけ読み込み、不要な情報はコンテキストに載らない

プログレッシブ・ディスクロージャー

公式ドキュメントが推奨するプログレッシブ・ディスクロージャーパターンは、references/ の設計原則そのものです。

プログレッシブ・ディスクロージャーの構造:

  SKILL.md（レベル 1）:
    → 概要と手順の骨格。500 行以下を推奨
    → 「詳細は references/xxx.md を参照」

  references/（レベル 2）:
    → 詳細な仕様、規約、コード例
    → 必要な時だけ読み込まれる

  結果:
    → SKILL.md は軽量なまま
    → Claude は必要に応じて深い知識にアクセスできる

このパターンにより、SKILL.md を 500 行以下に保ちながら、数千行に及ぶ参照情報を持つスキルを構築できます。

実践例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# references/writing-guide.md

## 記事の構成ルール

### タイトル
- 「技術テーマ --- 具体的な価値」の形式
- 70 文字以内

### 本文
- H2 で大きなセクションを区切る
- コードブロックは言語指定する
- 表は Markdown テーブルで書く

### まとめセクション
- 箇条書き 5〜7 項目
- 各項目は太字のキーワード + 説明文

SKILL.md 側:

1
2
3

## 記事を書く

記事のスタイルは [ライティングガイド](references/writing-guide.md) に従う。

assets — 出力用のファイルを配置する

役割

assets/ ディレクトリには、スキルの出力やツール実行で使用するファイルを配置します。scripts/ や references/ と異なり、コンテキストに読み込まれることを想定しないファイルが中心です。

my-skill/
├── SKILL.md
└── assets/
    ├── template.html     ← 出力テンプレート
    ├── logo.png          ← 画像ファイル
    ├── config.json       ← 設定ファイル
    └── font.ttf          ← フォントファイル

scripts/ や references/ との違い

assets/ の典型的な使い方は、テンプレートファイルを元に成果物を生成するパターンです。

1
2
3
4
5

## レポート生成

1. `assets/report-template.html` をベースにレポートを作成する
2. ロゴ画像は `assets/logo.png` を使用する
3. 出力先は `/tmp/report.html`

Claude は Read ツールでテンプレートを読み、Write ツールで内容を埋めた成果物を出力します。画像やフォントはコンテキストに載せる必要がなく、パスだけを指定すれば済みます。

実践例

deploy-skill/
└── assets/
    ├── cloudformation.yaml   ← CloudFormation テンプレート
    ├── Dockerfile.prod       ← 本番用 Dockerfile
    └── nginx.conf            ← Nginx 設定テンプレート

1
2
3
4
5

## デプロイ手順

1. `assets/Dockerfile.prod` を使ってイメージをビルドする
2. `assets/cloudformation.yaml` のパラメータを更新する
3. デプロイを実行する

3 つのディレクトリの使い分け早見表

判断フローチャート:

Q: そのファイルは Claude に実行させたい？
  → Yes → scripts/

Q: そのファイルは Claude が読んで判断に使う？
  → Yes → references/

Q: そのファイルは成果物の素材やテンプレート？
  → Yes → assets/

設計パターン — 三銃士を組み合わせる

パターン 1: リサーチ + レポート生成

research-skill/
├── SKILL.md
├── scripts/
│   ├── fetch_data.py        ← API からデータ取得
│   └── analyze.py           ← データ分析
├── references/
│   └── writing-guide.md     ← レポートの書き方
└── assets/
    └── report-template.md   ← レポートテンプレート

SKILL.md は全体の手順を記述し、scripts/ でデータを取得・分析、references/ でレポートの品質基準を参照、assets/ のテンプレートに沿って最終出力を生成します。

パターン 2: デプロイパイプライン

deploy-skill/
├── SKILL.md
├── scripts/
│   ├── pre_check.py         ← 事前チェック
│   ├── run_tests.sh         ← テスト実行
│   └── deploy.sh            ← デプロイ実行
├── references/
│   ├── deploy-checklist.md  ← デプロイチェックリスト
│   └── rollback-guide.md    ← ロールバック手順
└── assets/
    ├── Dockerfile.prod      ← 本番 Dockerfile
    └── docker-compose.yml   ← 構成ファイル

パターン 3: コードレビュー

review-skill/
├── SKILL.md
├── scripts/
│   ├── lint.sh              ← リンター実行
│   └── security_scan.py     ← セキュリティスキャン
├── references/
│   ├── coding-standards.md  ← コーディング規約
│   └── security-policy.md   ← セキュリティポリシー
└── assets/
    └── review-template.md   ← レビューコメントのテンプレート

SKILL.md のフロントマター設定

三銃士を活用する際に重要なフロントマター設定があります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
name: my-skill
description: スキルの説明
user-invocable: true        # /my-skill で呼び出し可能
allowed-tools:              # 使用可能なツールを制限
  - Bash
  - Read
  - Write
  - Glob
  - Grep
---

context: fork を設定すると、スキルの実行がサブエージェントに委譲されます。スキルの実行で消費されるコンテキストがメインの会話に影響しないため、重い処理を行うスキルに有効です。

既存の docs/ ディレクトリを references として活用する

references/ は慣習であり制約ではない

references/ ディレクトリはあくまで慣習的なディレクトリ構造であり、技術的な制約ではありません。SKILL.md からの Markdown リンクは相対パスで解決されるため、リポジトリ内のどのファイルでも参照先にできます。

多くのプロジェクトでは、既に docs/ ディレクトリにドキュメントを体系化し、mkdocs や Sphinx で公開しています。この既存のドキュメントをそのまま references として活用できます。

1
2
3
4
5

# SKILL.md 内での参照例

コードを書く際は [コーディング規約](../../docs/coding-style.md) に従ってください。
API 仕様は [API リファレンス](../../docs/api/endpoints.md) を参照。
デプロイ手順は [運用ガイド](../../docs/operations/deploy.md) を確認。

Claude は必要時に Read ツールでそのパスのファイルを読むだけなので、ファイルが references/ にあるか docs/ にあるかは関係ありません。遅延読み込みの仕組みは同じです。

docs/ を直接参照する利点

ドキュメントを references/ に複製すると二重管理になります。docs/ のコーディング規約を更新したのに references/ の方を更新し忘れる、という事故が起きます。既に docs/ で体系化されているなら直接参照する方が合理的です。

使い分けの判断基準

Q: そのドキュメントはプロジェクト共通のもの？
  → Yes → docs/ を直接参照（mkdocs で管理）

Q: そのドキュメントはスキル固有のもの？
  → Yes → references/ に配置

Q: 複数のスキルで同じドキュメントを参照する？
  → Yes → docs/ を直接参照（重複を避ける）

スキル固有の参照情報（そのスキルでしか使わないガイドやチェックリスト）は references/ に配置し、プロジェクト共通のドキュメント（コーディング規約、API 仕様、運用手順など）は docs/ を直接参照する、というハイブリッド構成が実用的です。

my-skill/
├── SKILL.md
├── scripts/
│   └── validate.py
├── references/
│   └── skill-specific-guide.md    ← このスキル固有のガイド
└── （docs/ は参照のみ、コピーしない）

docs/                               ← プロジェクト共通ドキュメント
├── coding-style.md                 ← SKILL.md から相対パスで参照
├── api/
│   └── endpoints.md
└── operations/
    └── deploy.md

コンテキスト効率の設計思想

三銃士の設計は、Claude Code におけるコンテキストは希少資源という原則に基づいています。

コンテキスト効率の階層:

  SKILL.md（常にコンテキストに載る）
    → 軽量に保つ。500 行以下推奨

  references/（必要時にコンテキストに載る）
    → 遅延読み込み。プログレッシブ・ディスクロージャー

  scripts/（コンテキストに載らない）
    → 実行結果だけが返る。ロジックの分離

  assets/（コンテキストに載らない）
    → パスを指定するだけ。バイナリも配置可能

この設計により、複雑なスキルでも SKILL.md を軽量に保ちながら、必要な情報と実行能力を段階的に提供できます。

まとめ

• scripts/ は実行コードの分離: Python や Bash スクリプトを配置し、Claude が Bash 経由で実行する。スクリプト本体はコンテキストに載らず、実行結果だけが返るため効率的
• references/ は参照ドキュメントの遅延読み込み: 仕様書・規約・ガイドを Markdown リンクで参照し、必要時だけコンテキストに読み込む。SKILL.md の肥大化を防ぐプログレッシブ・ディスクロージャー
• assets/ は出力素材の配置: テンプレート・画像・設定ファイルなど、成果物の生成に使うファイルを配置する。基本的にコンテキストに載らない
• 3 つの使い分け: 実行する → scripts/、読んで判断する → references/、出力に使う → assets/
• コンテキスト効率が設計原則: SKILL.md を 500 行以下に保ちながら、数千行の参照情報と複雑なロジックを持つスキルを構築できる
• 組み合わせで強力なパイプラインを構築: リサーチ + レポート、デプロイ、コードレビューなど、実用的なスキルは 3 つのディレクトリを組み合わせて設計する
• 既存の docs/ を references として活用可能: references/ は慣習であり技術的制約ではない。mkdocs で管理する docs/ を SKILL.md から相対パスで直接参照すれば、二重管理を避けて Single Source of Truth を維持できる

参考

• @shuhei_ohno 氏のポスト
• Claude Code: Skills — 公式ドキュメント
• Claude Code: Skill Authoring Best Practices
• Claude Code: MCP を使用してツールに接続する
• 上位1% Claude Skills構築 × スキル設計パターンと組織展開
• Claude Code Skill × ドメイン知識レイヤー分離設計