はじめに

Claude Codeのエージェントやスキルを作成する際、「どんな権限設定にすべきか」「ファイル構成はどうすべきか」と毎回悩んでいませんか？

本記事では、エージェント/スキルを自動生成するエージェントを実装し、設計の属人化を解消した事例を紹介します。

目次

解決したい課題
実装したもの
アーキテクチャ
実装の詳細
使用例
実際に作成したエージェント
メリットと効果
ディレクトリ構造
まとめ

解決したい課題

従来の問題点

Claude Codeでエージェントやスキルを作成する際、以下のような課題がありました：

1. 設計の属人化

権限設定（permissionMode）の判断基準が不明確
ツールの選定（Read-Only / Editor / Full Access）が毎回異なる
YAML構文エラーに気づかず時間を浪費

2. 時間のロス

ゼロから設計すると30分〜1時間かかる
過去の実装例を探す時間がもったいない
テンプレートがないため毎回車輪の再発明

3. 品質のバラツキ

セキュリティ上の問題（権限過多）
ドキュメント不足で使い方が不明
テストケースがなく動作確認が不十分

目指した姿

10秒で設計完了: 「〇〇用のエージェントを作って」と言うだけで完全な設計書が出る
ベストプラクティス準拠: 最小権限の原則、セキュリティ、ドキュメント品質をすべて満たす
再現性の確保: 誰が作っても同じ品質のエージェント/スキルが生成される

実装したもの

以下の3つのコンポーネントを実装しました：

1. agent-skill-creator エージェント

役割: ユーザーの要求を分析し、最適なエージェント/スキルの設計書を自動生成

特徴:

Read-Only（安全性重視）
ベストプラクティスDBを参照
完全な実装コードを提供
テストケース付き

2. best-practices-database スキル

役割: エージェント/スキル設計のベストプラクティス集

内容:

3つの設計パターン（Read-Only Reviewer / Controlled Writer / Automated Assistant）
4つのアンチパターン
トラブルシューティングガイド
権限設定のガイドライン

3. 4種類のテンプレート

プロジェクトの特性に応じて使い分け：

agent-template-readonly.md - 分析/監査用
agent-template-writer.md - ドキュメント生成用
skill-template-process.md - プロセスガイド用
skill-template-reference.md - リファレンス用

アーキテクチャ

全体構成

┌─────────────────────────────────────────────────┐
│          ユーザーの要求                           │
│  「記事執筆を支援するエージェントを作って」          │
└───────────────┬─────────────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────────────┐
│     agent-skill-creator エージェント               │
│  - 要求の分析                                     │
│  - エージェント/スキルの判定                        │
│  - ベストプラクティスDBの参照                       │
└───────────────┬─────────────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────────────┐
│    best-practices-database スキル                 │
│  - 設計パターンの提供                              │
│  - テンプレートの選定                              │
│  - セキュリティガイドライン                         │
└───────────────┬─────────────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────────────┐
│              設計書の出力                          │
│  - 完全な実装コード（YAML + Markdown）              │
│  - ファイル配置手順                                │
│  - 使用例とテストケース                            │
└─────────────────────────────────────────────────┘

データフロー

Phase 1: 要件分析
- タスク種別の特定（コードレビュー/記事作成/セキュリティ監査等）
- エージェント vs スキルの判定
- 既存実装の類似パターン検索
Phase 2: ベストプラクティス調査
- best-practices-databaseスキルから該当パターンを取得
- 権限設定のガイドラインを参照
- テンプレートの選定
Phase 3: 設計
- 最小権限の原則に基づくツール選定
- YAML構文の検証
- ドキュメントの自動生成
Phase 4: 生成と提示
- 完全な実装コードの出力
- ファイル配置手順の提示
- テストケースの提供

実装の詳細

agent-skill-creator.md

エージェント本体の実装です。

権限設定:

tools:
  - Read
  - Grep
  - Glob

disallowedTools:
  - Edit
  - Bash

permissionMode: requestApproval

設計のポイント:

Read-Only: ファイルの読み取りのみ許可（安全性優先）
Edit/Bash禁止: 勝手にファイルを作成・編集しない
承認必須: すべての操作にユーザー承認を求める

実行フロー:

## 実行フロー

### Phase 1: 要件分析

**ステップ1: ヒアリング**
- 実現したいタスク
- 対象読者/利用者
- 期待される成果
- 制約条件（セキュリティ、権限等）

**ステップ2: 分類**
- エージェント vs スキル vs 両方
- 優先順位（必須 vs 拡張）
- 既存実装との関係

### Phase 2: ベストプラクティス調査

**ステップ3: 内部調査**
プロジェクト内の既存実装を探索

**ステップ4: パターンマッチング**
best-practices-database スキルを参照し、該当するパターンを特定

### Phase 3: 設計

**ステップ5: アーキテクチャ決定**
- ファイル名と配置パス
- 権限設定（最小権限の原則）
- 使用ツール
- permissionMode

**ステップ6: 安全性検証**
- 不要な権限がないか
- 危険な操作への警告があるか
- ユーザー承認プロセスは適切か

### Phase 4: 生成と提示

**ステップ7: 完全な実装生成**
YAMLフロントマター付きMarkdownファイルの完全な内容を生成

**ステップ8: 使用手順の作成**
- ファイル配置方法
- 動作確認方法
- 使用例

**ステップ9: テストケース提供**
実際の呼び出し例と期待される動作

best-practices-database スキル

ベストプラクティス集の実装です。

提供する設計パターン:

パターン1: Read-Only Reviewer

用途: コードレビュー、セキュリティ監査、品質分析

tools:
  - Read
  - Grep
  - Glob

disallowedTools:
  - Edit
  - Bash

permissionMode: requestApproval

メリット:

勝手にコードを書き換えるリスクゼロ
安全性が高い
承認プロセスが軽い

パターン2: Controlled Writer

用途: ドキュメント生成、コード生成、リファクタリング支援

tools:
  - Read
  - Edit
  - Grep
  - Glob

disallowedTools:
  - Bash

permissionMode: requestApproval

メリット:

ファイル編集が可能
危険なコマンド実行は不可
ユーザー承認で安全性確保

パターン3: Automated Assistant

用途: 定型作業の自動化、CI/CD統合（サンドボックス環境のみ）

tools:
  - Read
  - Edit
  - Bash
  - Grep
  - Glob

permissionMode: approveAll  # 注意: 慎重に使用

注意事項:

approveAllは信頼できる環境のみ
サンドボックス環境推奨
定期的な権限見直し

アンチパターン集:

本スキルには以下の失敗パターンも記載されています：

権限過多: すべてのツールを許可してしまう
曖昧なdescription: Claudeが適用タイミングを判断できない
ドキュメント不足: 使い方が不明
スキルの過剰な細分化: 管理コストが増大

テンプレートファイル群

4つのテンプレートを用意しています。

ディレクトリ構造:

.claude/skills/best-practices-database/
├── SKILL.md
└── templates/
    ├── agent-template-readonly.md
    ├── agent-template-writer.md
    ├── skill-template-process.md
    └── skill-template-reference.md

使い分けガイド:

テンプレート	用途	特徴
agent-template-readonly	分析・監査	Read-Only、安全性最優先
agent-template-writer	ドキュメント生成	Edit可、承認必須
skill-template-process	プロセスガイド	Gate/Phase構造
skill-template-reference	リファレンス	データベース的な参照用

使用例

例1: 記事執筆エージェントの作成

ユーザーの指示:

agent-skill-creatorを使って、記事執筆を支援するエージェントを作って

agent-skill-creatorの応答:

## 分析サマリー

- **タスク種別**: 記事作成支援
- **推奨実装**: エージェント + スキル（記事作成プロセスガイド）
- **優先度**: 高
- **類似実装**: なし（新規作成）

## 設計仕様

### ファイル情報
- **種別**: Agent
- **ファイル名**: `article-writer.md`
- **配置パス**: `.claude/agents/article-writer.md`

### 権限設定
- **model**: sonnet
- **permissionMode**: requestApproval
- **許可ツール**: Read, Edit, Write, Grep, Glob
- **禁止ツール**: Bash

### 理由
- 記事ファイルの編集が必要なため Edit/Write を許可
- コマンド実行は不要なため Bash を禁止
- ファイル保存前にユーザー確認を求める

生成された実装コード:

---
name: article-writer
description: |
  生成AI系技術記事（Claude Code / Antigravity / Gemini / ChatGPT等）を
  Gate 0-9の品質管理プロセスに従って作成する専門エージェントです。

model: sonnet
permissionMode: requestApproval

tools:
  - Read
  - Edit
  - Write
  - Grep
  - Glob

disallowedTools:
  - Bash

skills:
  - article_creation
  - article-templates
  - seo-report-analysis
---

# Article Writer Agent

あなたはSEO最適化された生成AI系技術記事を作成する専門エージェントです。

## ミッション

Gate 0-9の品質管理プロセスに従い、検索上位を狙える高品質な技術記事を作成します。

（以下略）

所要時間: 約10秒

例2: セキュリティ監査エージェントの作成

ユーザーの指示:

agent-skill-creatorを使って、セキュリティ監査を自動化したい

agent-skill-creatorの応答:

## 分析サマリー

- **タスク種別**: セキュリティ監査
- **推奨実装**: エージェント（Read-Only）
- **優先度**: 高
- **類似実装**: なし

## 設計仕様

### 権限設定
- **model**: sonnet
- **permissionMode**: requestApproval
- **許可ツール**: Read, Grep, Glob
- **禁止ツール**: Edit, Bash

### 理由
- コードを読み取るのみで編集は不要
- 最小権限の原則に基づき Read-Only に設定
- セキュリティ監査は慎重に行うべきため承認必須

生成された実装コード:

---
name: security-auditor
description: |
  コードベース全体をスキャンし、セキュリティリスクを検出・報告します。

model: sonnet
permissionMode: requestApproval

tools:
  - Read
  - Grep
  - Glob

disallowedTools:
  - Edit
  - Bash
---

# Security Auditor Agent

あなたはセキュリティ専門家として、コードベースの脆弱性を検出します。

## ミッション

以下の観点でセキュリティリスクを網羅的に検査します：

1. 機密情報の漏洩（APIキー、トークン、パスワード等）
2. 危険な関数の使用（eval, exec, innerHTML等）
3. 依存関係の脆弱性
4. 権限設定の問題

（以下略）

実際に作成したエージェント

この仕組みを使って、以下のエージェントを実際に作成しました：

article-writer エージェント

目的: Gate 0-9のプロセスに従い、SEO最適化された技術記事を作成

使用スキル:

article_creation - 記事作成の全工程ガイド
article-templates - プラットフォーム別テンプレート
seo-report-analysis - SEOデータ提供

主な機能:

Qiita/Zenn/note向けの記事生成
文字数・見出し数の自動調整
SEOキーワードの最適配置
プラットフォーム別の文体変換

作成にかかった時間: 約10秒（設計） + 2分（カスタマイズ）

従来との比較:

従来: 30分〜1時間（設計から実装まで）
今回: 2分10秒（90%以上の時短）

メリットと効果

1. 時間短縮

設計時間:

従来: 30分〜1時間
現在: 10秒〜2分
短縮率: 95%以上

品質確認時間:

従来: 10〜20分（手動レビュー）
現在: 0分（ベストプラクティス準拠が保証される）

2. 品質向上

セキュリティ:

最小権限の原則が自動適用
危険な権限設定を自動検出
アンチパターンを回避

ドキュメント:

使用例・テストケースが自動生成
トラブルシューティングガイド付き
ベストプラクティスに基づく構成

3. 再現性の確保

誰が作っても同じ品質:

テンプレートベースで一貫性を保証
ベストプラクティスDBが常に参照される
アンチパターンを自動回避

レビューコストの削減:

設計レビューが不要（ベストプラクティス準拠が保証）
セキュリティレビューが簡略化
ドキュメント品質のバラツキがゼロ

ディレクトリ構造

実際のプロジェクト構造は以下のようになっています（個人情報は省略）：

Antigravity/
└── .claude/
    ├── agents/
    │   ├── agent-skill-creator.md      ← エージェント生成エージェント
    │   └── article-writer.md           ← 実際に作成したエージェント
    └── skills/
        ├── best-practices-database/
        │   ├── SKILL.md                ← ベストプラクティス集
        │   └── templates/
        │       ├── agent-template-readonly.md
        │       ├── agent-template-writer.md
        │       ├── skill-template-process.md
        │       └── skill-template-reference.md
        ├── article_creation/
        │   ├── SKILL.md
        │   ├── gate0_planning.md
        │   ├── gate1_research.md
        │   └── ... (gate2-9)
        ├── article-templates/
        │   └── SKILL.md
        └── seo-report-analysis/
            └── SKILL.md

ファイル数の推移

実装前:

エージェント: 0個
スキル: 3個（article_creation, article-templates, seo-report-analysis）

実装後:

エージェント: 2個（agent-skill-creator, article-writer）
スキル: 4個（+ best-practices-database）
テンプレート: 4個

導入方法

1. エージェントの配置

以下のファイルを作成してください：

.claude/agents/agent-skill-creator.md

---
name: agent-skill-creator
description: |
  ユーザーのやりたいことを分析し、最適なClaude Codeエージェントとスキルを設計・生成します。
  最新のベストプラクティスに基づいた設定ファイルを完全な形で提案します。

model: sonnet
permissionMode: requestApproval

tools:
  - Read
  - Grep
  - Glob

disallowedTools:
  - Edit
  - Bash
---

（以下、本記事で紹介した内容）

2. スキルの配置

.claude/skills/best-practices-database/SKILL.md

ベストプラクティス集を配置します。

3. テンプレートの配置

.claude/skills/best-practices-database/templates/

4つのテンプレートを配置します。

4. 動作確認

agent-skill-creatorを使って、コードレビュー用のエージェントを作って

上記のように指示すると、完全な設計書が生成されます。

応用例

1. チーム全体で活用

Before: 各メンバーが独自にエージェント/スキルを作成

品質のバラツキが大きい
レビューコストが高い
属人化が進む

After: agent-skill-creatorで統一

一貫した品質
レビューコストがほぼゼロ
誰でも同じ品質を実現

2. ベストプラクティスの蓄積

運用フロー:

新しいパターンが見つかったら best-practices-database に追加
アンチパターンを発見したら警告を追加
テンプレートを改善
チーム全体に即座に反映

3. ドメイン特化エージェントの量産

事例: RAGシステム開発

rag-file-generator - RAGファイル生成
document-analyzer - ドキュメント分析
chunking-optimizer - チャンク最適化
quality-validator - 品質検証

すべて agent-skill-creator で10秒以内に設計完了。

注意点

1. Read-Onlyの制約

agent-skill-creator自体はRead-Onlyです。

理由:

勝手にファイルを作成・編集しない（安全性優先）
ユーザーが内容を確認してから保存できる

ファイル作成の手順:

agent-skill-creatorに設計書を生成させる
内容を確認
通常のClaude Codeモード（Write権限あり）で保存

2. 既存実装の探索

agent-skill-creatorは既存のエージェント/スキルを探索します。

注意点:

作業ディレクトリを正しく設定すること
VSCodeでプロジェクトフォルダを開くこと

3. カスタマイズの余地

生成された設計書はあくまでベースです。

推奨フロー:

agent-skill-creatorで設計書を生成（10秒）
プロジェクト固有の要件を追加（2〜5分）
テストケースで動作確認（2〜3分）

まとめ

実現したこと

エージェント/スキルの設計時間を95%短縮
- 従来: 30分〜1時間
- 現在: 10秒〜2分
ベストプラクティス準拠を自動化
- 最小権限の原則
- セキュリティガイドライン
- ドキュメント品質
再現性の確保
- 誰が作っても同じ品質
- レビューコストがほぼゼロ
- アンチパターンを自動回避

今後の展開

ベストプラクティスDBの拡充
- より多くの設計パターンを追加
- ドメイン特化パターン（RAG/データ分析/セキュリティ等）
- チーム固有のパターン
テンプレートの多様化
- 言語別テンプレート（Python/TypeScript/Rust等）
- フレームワーク別テンプレート（React/Vue/Django等）
- CI/CD統合テンプレート
コミュニティでの共有
- GitHub等でのテンプレート公開
- ベストプラクティスのコミュニティ駆動更新
- 事例集の充実

参考情報

検証日: 2026-01-21
Claude Code バージョン: 最新版
検証環境: Windows 11, VSCode
プロジェクト: Antigravity（記事生成システム）

関連記事

本記事と合わせて読むとより理解が深まります：

Claude Codeのスキル・エージェントが見えない問題の原因と解決方法
Claude Codeで記事作成を自動化する仕組み
SEO最適化記事をAIで量産する方法

おわりに

「エージェントを作るエージェント」という一見メタな仕組みですが、実際に運用してみると設計時間の大幅短縮と品質の安定化を同時に実現できることがわかりました。

特に、チーム開発においては「属人化の解消」「レビューコストの削減」「ベストプラクティスの共有」といった副次的な効果も大きく、導入する価値は非常に高いと感じています。

Claude Codeでエージェント/スキルを頻繁に作成する方は、ぜひこの仕組みを試してみてください。

Happy Coding!

謝辞

本記事の作成にあたり、Claude Code公式ドキュメントおよびコミュニティの知見を参考にさせていただきました。

ライセンス

本記事で紹介したコード・テンプレートは自由に利用可能です（MIT License相当）。

お問い合わせ

質問・フィードバックは記事のコメント欄またはX (Twitter)でお気軽にどうぞ。