この記事は株式会社カオナビ Advent Calendar 2025の10日目（シリーズ3）の記事です。
はじめに
こんにちは。単調な作業をしていると、「これ、全部AIに丸投げできないかな…」と遠い目になること、ありますよね。私は毎日思っています。
そんなわけで、最近はClaude Codeを相棒にあらゆる作業の自動化を試みています。
特に最近挑んでいたのが、「仕様書から複雑な仕様のJSON（バリデーションルール入り）を一発で生成させる」というタスクです。
最初は気合いを入れてプロンプトに全仕様を詰め込んだ結果、速攻でトークン制限に引っかかり爆死しました。
しかし、Claudeの「Skills」機能を正しく使ったところ、トークンを節約しつつ複雑な処理を完走できるようになったので、その知見を共有します。
抱えていた課題：工程が多すぎてトークンが持たない
やりたいことはシンプルです。
「Excelの仕様書を読み込み、独自ルール（約1000行）を適用し、バリデーション付きのJSONを吐き出す」
これを毎回チャットで指示するのは苦行なので、Claude Codeのカスタムスラッシュコマンド一発で実行しようとしました。
❌ 失敗パターン（全部盛り）
最初は1つのプロンプトで全てをやろうとしました。
- 仕様書を読み込む
- 全ルールをプロンプトに展開
- JSON生成指示
しかし、これでは仕様書とルールだけでコンテキストが埋まり、トークンが一瞬で溶けます。
さらに、プロンプトが長すぎてClaudeが指示を読み飛ばしたり、メモリ不足で処理が止まったりと、散々な結果でした。
解決策：Skillsによる「分業」と「コンテキスト分離」
この問題を解決するために、2025年10月に正式発表されたSkillsを使って処理を分割しました。
アプローチ1：仕様書のマークダウン化
まず、「Excelをそのまま読ませる」という横着をやめました。
専用スクリプトでExcelをMarkdown化することで、情報の密度を高め、トークン消費を抑えました。
アプローチ2：Skillsで処理を分割
巨大な処理を以下の3つのSkill（専門知識パッケージ）に分割しました。
| Skill名 | 役割 |
|---|---|
| spec-analyzer | 仕様書を解析してMarkdown化する |
| json-generator | ルールを適用してJSONを生成する |
| json-validator | 生成されたJSONの整合性を検証する |
こうすることで、AIは「今やっている工程」に必要な知識だけをロードすれば良くなります。
実装：Skills
Skillsは以下のような形でSKILL.mdというファイル名で配置することで使うことができます。
その他にもreferenceやexampleなどのファイルを置くことでさらに細かく指示を出すことも可能です。
my-project/
├── .claude/
│ └── skills/
│ ├── spec-analyzer/ # スキル名
│ │ ├── SKILL.md # 必須
│ │ └── examples.md # (Examples) 入力と期待する出力のペア
│ │ └── scripts/ # (Script) 複雑なテキスト抽出ロジック
│ │ ├── parser.py #
│ │
│ ├── json-generator/
│ │ ├── SKILL.md
│ │ ├── reference.md # (Reference) 命名規則やフィールド定義書
│ │ └── templates/ # (Templates) JSONの基本構造
│ │ └── base.json
│ │
│ └── json-validator/
│ ├── SKILL.md
│ └── reference.md
│
├── input_specs/
└── output/
Skillsの例
仕様書を分析するツールは以下のように記述します。
---
name: spec-analyzer
description: Excel形式(.xlsx)の仕様書やデータ定義書を読み取り、内容を解析し、マークダウン形式で出力します。
allowed-tools: Read, Grep, Glob
---
# 仕様読み込みスキル
このスキルは、バイナリ形式のExcelファイルを直接読む代わりに、Pythonスクリプトを介してMarkdown形式のテキストに変換し、その内容を解析します。
## 前提条件
以下のライブラリがインストールされている必要があります。
- pandas
- openpyxl
- tabulate
## 手順
1. 仕様書の解析
```bash
python scripts/parser.py
```
### 📂 JSON出力先
出力先: `output`
ファイル名形式: `spec_analysis.md`
## 完了時の出力
1. 生成したマークダウンのファイルパス
4. 次のステップ（JSON生成）への案内
実装：カスタムスラッシュコマンド
カスタムスラッシュコマンドを配置すると以下のようなディレクトリ構成になります。
my-project/
├── .claude/
│ ├── commands/ # カスタムスラッシュコマンド
│ │ └── generate-json.md
│ │
│ └── skills/
│ ├── spec-analyzer/
│ │ ├── SKILL.md
│ │ ├── parser.py
│ │ └── examples.md
│ │
│ ├── json-generator/
│ │ ├── SKILL.md
│ │ ├── reference.md
│ │ └── templates/
│ │ └── base.json
│ │
│ └── json-validator/
│ ├── SKILL.md
│ ├── validate_schema.py
│ └── reference.md
│
├── input_specs/
└── output
実際に作成したカスタムスラッシュコマンドの定義ファイル（Markdown）です。
---
allowed-tools: Skill
description: 仕様書をもとにルールに従ったJSONを生成します
---
# JSON生成コマンド
このコマンドは、仕様書からルールに従ったJSONを**Claude Skills**を使って段階的に生成します。
## 使用方法
```shell
/generate-json [仕様書マークダウンファイルパス]
```
## 処理フロー
このコマンドは、以下の3つのSkillを順番に実行します：
1. **spec-analyzer** - 仕様書を解析
2. **json-generator** - JSON生成
3. **json-validator** - バリデーション
## あなたのタスク
### STEP 1: 仕様書の解析
`Skill`を使って `spec-analyzer` を実行し、仕様書のマークダウン化を行ってください。
（※中略：Excel解析結果を読み込み、構造化データを生成する指示）
### STEP 2: JSONの生成
`Skill` を使って、 `json-generator` を実行し、ルールに従ったJSONを生成してください。
（※中略：STEP1のデータとJSON生成ルールを紐付ける指示）
### STEP 3: JSONのバリデーション
`Skill`を使って `json-validator` スキルを実行します：
（※中略：問題点を報告し、修正案を出す指示）
## エラー処理
各Skillの実行中にエラーが発生した場合：
1. エラー内容を明確に報告
2. ユーザーに対処方法を提案
3. 必要に応じて該当Skillを再実行
実行結果
ターミナルかVscodeなどでコマンドを叩くだけです。
/generate-json /path/to/specification.md
実行ログ（イメージ）：
Claude Code: 「了解しました。まずは仕様書の解析を行います...」
> Running spec-analyzer... (完了)
Claude Code: 「次にJSON生成ルールを適用してJSONを生成します...」
> Running json-generator... (完了)
Claude Code: 「最後に生成されたJSONのバリデーションを行います...」
> Running json-validator... (完了)
完了報告: ✅ 生成完了
📄 JSON: output/generated_data.json
感動です。見てるだけで仕事が終わりました。
以前は手動でリカバリーしながら数十分かかっていた作業が、一度も止まることなく数分で完結するようになりました。
技術的な推しポイント（工夫した点）
1. 「コンテキスト汚染」の防止
巨大な生成ルールは各Skill内に隠蔽されているため、メインのチャットコンテキストは常にクリーンです。これにより、後半の工程になってもAIが「ボケる（ハルシネーション）」現象を防げました。
2. 人間によるレビュー負荷の軽減
「このフィールドは必須か？」といった思考プロセスはSkill内で完結します。
人間は最終的に出力された「バリデーション済みのJSON」だけをレビューすれば良いため、認知負荷が段違いに下がりました。
3. 自律的なエラーリカバリー
定義に「エラー処理」を明記したことで、例えばバリデーションエラーが発生しても、「ルールを確認し修正案を適用しました」と勝手に自己修復して進んでくれます。これが本当に強い。
まとめ
Claude CodeのSkills機能を使うことで、複雑なJSON生成プロセスを分割し、トークン制限を回避しつつ高精度な自動化を実現できました。
Claude CodeにはSkills以外にも「サブエージェント」を使って並列処理を進める機能もあるので、今後も業務効率化のために色々試していきたいと思います。