creating-claude-agents

Claude Code エージェントの作成 — エキスパートスキル

Claude Code エージェントを作成または改善するときに、このスキルを使用します。エージェントの構造、スキーマ検証、長時間稼働する AI アシスタントの構築に関するベストプラクティスを包括的に説明します。

このスキルを使用する場面

次の場合にこのスキルを有効にします。

• ユーザーが新しい Claude Code エージェントの作成を依頼した
• ユーザーが既存のエージェントの改善を希望している
• ユーザーがエージェントのフロントマターや構造についてサポートを必要としている
• ユーザーがエージェントの検証エラーを解決しようとしている
• ユーザーがエージェントのフォーマット要件を理解したい
• ユーザーがエージェント、スキル、スラッシュコマンドの違いについて質問している

クイックリファレンス

エージェントのファイル構造

---
name: agent-name
description: When and why to use this agent
allowed-tools: Read, Write, Bash
model: sonnet
agentType: agent
---

# 🔍 Agent Display Name

You are [persona definition - describe the agent's role and expertise].

## Instructions

[Clear, actionable guidance on what the agent does]

## Process

[Step-by-step workflow the agent follows]

## Examples

[Code samples and use cases demonstrating the agent's capabilities]

ファイルの場所

必須のパス：

.claude/agents/*.md

エージェントは、.claude/agents/ ディレクトリに Markdown ファイルとして配置する必要があります。

フロントマターの要件

必須フィールド

フィールド	型	説明	例
name	文字列	エージェント識別子（小文字とハイフンのみ）	code-reviewer
description	文字列	機能とユースケースの簡単な概要	Reviews code for best practices and potential issues

任意フィールド

フィールド	型	説明	値
allowed-tools	文字列	使用可能なツールのカンマ区切りリスト	Read, Write, Bash, WebSearch
model	文字列	使用する Claude モデル	sonnet, opus, haiku, inherit
agentType	文字列	フォーマット保持を明示するマーカー	agent

検証ルール

Name フィールド：

• パターン：^[a-z0-9-]+$（小文字、数字、ハイフンのみ）
• 最大長：64 文字
• 例：✅ code-reviewer ❌ Code_Reviewer

Description フィールド：

• 最大長：1024 文字
• エージェントを使用する場面を明確に説明する必要があります
• 「レビューします…」「分析します…」「…を支援します」など、動作を表す言葉で始めます

Allowed Tools： 有効なツール：Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Task, Skill, SlashCommand, TodoWrite, AskUserQuestion

Model の値：

• sonnet - バランスがよく、ほとんどのエージェントに適しています（デフォルト）
• opus - 複雑な推論やアーキテクチャ上の判断に適しています
• haiku - 高速で、単純なタスクに適しています
• inherit - 親の会話で使用しているモデルを使います

コンテンツのフォーマット要件

H1 見出し（必須）

コンテンツの最初の行は、エージェントの表示タイトルとなる H1 見出しにする必要があります。

# 🔍 Code Reviewer

ベストプラクティス：

• 視覚的に区別しやすいよう、絵文字アイコンを含めます
• タイトルケースを使用します
• 簡潔にまとめます（2～5 語）
• 説明的で覚えやすい名前にします

ペルソナの定義（エージェントには必須）

H1 の直後に、「You are...」形式でエージェントのペルソナを定義します。

You are an expert code reviewer with deep knowledge of software engineering principles and security best practices.

ガイドライン：

• 「You are...」で始めます
• 役割と専門知識を明確に定義します
• エージェントの能力に関する期待を設定します
• エージェントのアプローチと口調を定めます

コンテンツの構成

# 🔍 Agent Name

You are [persona definition].

## Instructions

[What the agent does and how it approaches tasks]

## Process

1. [Step 1]
2. [Step 2]
3. [Step 3]

## Examples

[Code samples showing good/bad patterns]

## Guidelines

- [Best practice 1]
- [Best practice 2]

スキーマ検証

エージェントは、次の JSON スキーマに準拠する必要があります。 https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-agent.schema.json

スキーマの構造

{
  "frontmatter": {
    "name": "string (required)",
    "description": "string (required)",
    "allowed-tools": "string (optional)",
    "model": "enum (optional)",
    "agentType": "agent (optional)"
  },
  "content": "string (markdown with H1, persona, instructions)"
}

よくある検証エラー

エラー	原因	修正方法
必須フィールド 'name' がありません	Frontmatter に name フィールドがありません	name: agent-name を追加
必須フィールド 'description' がありません	Frontmatter に description がありません	description: ... を追加
名前のパターンが無効です	名前に大文字または特殊文字が含まれています	小文字とハイフンのみを使用してください
名前が長すぎます	名前が64文字を超えています	名前を短くしてください
モデルの値が無効です	モデルが列挙型に含まれていません	sonnet、opus、haiku、inherit のいずれかを使用してください
H1 見出しがありません	コンテンツが # で始まっていません	1行目に # Agent Name を追加してください

ツールの設定

すべてのツールを継承する

allowed-tools フィールドを省略すると、親の会話からすべてのツールを継承します。

---
name: full-access-agent
description: Agent needs access to everything
# No allowed-tools field = inherits all
---

特定のツールのみ

必要最小限の権限を付与します。

---
name: read-only-reviewer
description: Reviews code without making changes
allowed-tools: Read, Grep, Bash
---

Bash ツールの制限

コマンドパターンを使用して、Bash へのアクセスを制限します。

---
name: git-helper
description: Git operations only
allowed-tools: Bash(git *), Read
---

構文：

• Bash(git *) - git コマンドのみ
• Bash(npm test:*) - npm のテストスクリプトのみ
• Bash(git status:*)、Bash(git diff:*) - 複数の特定コマンド

モデル選択ガイド

Sonnet（ほとんどのエージェント）

用途：

• コードレビュー
• デバッグ
• データ分析
• 一般的な問題解決

model: sonnet

Opus（複雑な推論）

用途：

• アーキテクチャの決定
• 複雑なリファクタリング
• 詳細なセキュリティ分析
• 新しい問題の解決

model: opus

Haiku（速度が重要な場合）

用途：

• 構文チェック
• 簡単なフォーマット
• 迅速な検証
• 低レイテンシが求められる場合

model: haiku

Inherit（状況に応じて選択）

用途：

• エージェントにユーザーのモデル選択を反映させる場合
• コストを重視する場合

model: inherit

よくある間違い

間違い	問題	解決策
名前に _ を使う	パターンの制約に違反します	ハイフンを使います：code_reviewer ではなく code-reviewer
名前に大文字を使う	パターンの制約に違反します	小文字のみを使います：Debugger ではなく debugger
ペルソナがない	エージェントの役割が定義されていません	H1 の後に「あなたは…です」を追加します
H1 見出しがない	コンテンツ形式が無効です	コンテンツを # Agent Name で始めます
説明が曖昧	エージェントが正しく起動しません	使用する状況を具体的に記述します
ツールが多すぎる	セキュリティリスクがあり、最小権限の原則に違反します	必要なツールのみを付与します
agentType フィールドがない	変換時にタイプ情報が失われる可能性があります	agentType: agent を追加します
汎用的なエージェント名	競合が生じたり、目的が不明確になったりします	具体的で説明的な名前を使います

ベストプラクティス

1. 明確で具体的な説明を書く

説明によって、Claude がエージェントを自動的に呼び出すタイミングが決まります。

✅ 良い例：

description: Reviews code changes for quality, security, and maintainability issues

❌ 悪い例：

description: A helpful agent # Too vague

2. 明確なペルソナを定義する

H1 の直後に、専門知識とアプローチを明示します。

# 🔍 Code Reviewer

You are an expert code reviewer specializing in TypeScript and React, with 10+ years of experience in security-focused development. You approach code review systematically, checking for security vulnerabilities, performance issues, and maintainability concerns.

3. 手順を段階的に示す

エージェントのワークフローを明確に示します。

## Review Process

1. **Read the changes**
   - Get recent git diff or specified files
   - Understand the context and purpose

2. **Analyze systematically**
   - Check each category (quality, security, performance)
   - Provide specific file:line references
   - Explain why something is an issue

3. **Provide actionable feedback**
   - Categorize by severity
   - Include fix suggestions
   - Highlight positive patterns

4. 例を含める

良いパターンと悪いパターンの両方を示します。

## Examples

When reviewing error handling:

❌ **Bad - Silent failure:**
\`\`\`typescript
try {
await fetchData();
} catch (error) {
console.log(error);
}
\`\`\`

✅ **Good - Proper error handling:**
\`\`\`typescript
try {
await fetchData();
} catch (error) {
logger.error('Failed to fetch data', error);
throw new AppError('Data fetch failed', { cause: error });
}
\`\`\`

5. H1 にアイコンを使って視覚的に区別する

エージェントの目的を表す絵文字を選びます。

• 🔍 コードレビュー担当
• 🐛 デバッガー
• 📊 データサイエンティスト
• 🔒 セキュリティ監査担当
• ⚡ パフォーマンス最適化担当
• 📝 ドキュメント作成担当
• 🧪 テスト生成担当

6. 単一責任を維持する

各エージェントは、1 つの特定のタスクに優れているべきです:

✅ 良い例:

• code-reviewer - コードの品質とセキュリティをレビューする
• debugger - 根本原因の分析と最小限の修正

❌ 悪い例:

• code-helper - レビュー、デバッグ、テスト、リファクタリング、ドキュメント作成 (範囲が広すぎる)

7. 最小限のツールアクセスを付与する

最小権限の原則に従ってください:

# Read-only analysis agent
allowed-tools: Read, Grep

# Code modification agent
allowed-tools: Read, Edit, Bash(git *)

# Full development agent
allowed-tools: Read, Write, Edit, Bash, Grep, Glob

8. ラウンドトリップ変換のために agentType を含める

フォーマット変換中に型情報を保持するため、frontmatter に常に agentType: agent を含めてください:

---
name: code-reviewer
description: Reviews code for best practices
agentType: agent
---

エージェントテンプレートの例

最小限のエージェント

---
name: simple-reviewer
description: Quick code review for common issues
allowed-tools: Read, Grep
model: haiku
agentType: agent
---

# 🔍 Simple Code Reviewer

You are a code reviewer focused on catching common mistakes quickly.

## Instructions

Review code for:

- Syntax errors
- Common anti-patterns
- Missing error handling
- Console.log statements

Provide concise feedback with file:line references.

包括的なエージェント

---
name: security-auditor
description: Deep security vulnerability analysis for code changes
allowed-tools: Read, Grep, WebSearch, Bash(git *)
model: opus
agentType: agent
---

# 🔒 Security Auditor

You are a security expert specializing in application security, with expertise in OWASP Top 10, secure coding practices, and threat modeling. You perform thorough security analysis of code changes.

## Review Process

1. **Gather Context**
   - Read changed files
   - Review git history for context
   - Identify data flows and trust boundaries

2. **Security Analysis**
   - Input validation and sanitization
   - Authentication and authorization
   - SQL injection risks
   - XSS vulnerabilities
   - CSRF protection
   - Secrets exposure
   - Cryptography usage
   - Dependency vulnerabilities

3. **Threat Assessment**
   - Rate severity (Critical/High/Medium/Low)
   - Assess exploitability
   - Determine business impact
   - Provide remediation guidance

4. **Report Findings**
   Use structured format with CVE references where applicable.

## Output Format

**Security Score: X/10**

### Critical Issues (Fix Immediately)

- [Vulnerability] (file:line) - [Explanation] - [CVE if applicable] - [Fix]

### High Priority

- [Issue] (file:line) - [Explanation] - [Fix]

### Medium Priority

- [Concern] (file:line) - [Explanation] - [Recommendation]

### Best Practices

- [Positive security pattern observed]

**Recommendation:** [Approve/Request Changes/Block]

## Examples

### SQL Injection Check

❌ **Vulnerable:**
\`\`\`typescript
const query = \`SELECT \* FROM users WHERE id = \${userId}\`;
db.query(query);
\`\`\`

✅ **Safe:**
\`\`\`typescript
const query = 'SELECT \* FROM users WHERE id = $1';
db.query(query, [userId]);
\`\`\`

検証チェックリスト

エージェントを完成させる前に:

• 名前は小文字とハイフンのみ
• 名前は 64 文字以下
• 説明は、いつこのエージェントを使うべきかを明確に説明している
• 説明は 1024 文字以下
• コンテンツは H1 見出し (絵文字アイコン付き) で始まる
• ペルソナは「You are...」形式で定義されている
• プロセスまたは指示が明確に概説されている
• 例が含まれている (良い/悪いパターンを示す)
• ツールアクセスは最小限かつ具体的である
• モデルの選択はタスクの複雑さに適している
• agentType フィールドが "agent" に設定されている
• ファイルが .claude/agents/ ディレクトリに保存されている
• エージェントが実際のタスクでテストされている
• エッジケースが考慮されている

スキーマリファレンス

公式スキーマ URL:

https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-agent.schema.json

ローカルスキーマパス:

/Users/khaliqgant/Projects/prpm/app/packages/converters/schemas/claude-agent.schema.json

関連ドキュメント

• agent-builder スキル - 効果的なサブエージェントの作成
• slash-command-builder スキル - よりシンプルなコマンドベースのプロンプト向け
• creating-skills スキル - コンテキスト対応のリファレンスドキュメント向け
• Claude Code ドキュメント: https://docs.claude.com/claude-code

エージェント vs スキル vs コマンド

エージェントを使うべき場合:

• ✅ 永続的なコンテキストを持つ長時間実行のアシスタント
• ✅ 複雑なマルチステップのワークフロー
• ✅ 専門的な専門知識が必要
• ✅ ツールアクセスが必要
• ✅ 品質基準を伴う反復可能なプロセス

スキルを使うべき場合:

• ✅ コンテキスト対応の自動アクティベーション
• ✅ リファレンスドキュメントとパターン
• ✅ チームの標準化
• ✅ 永続的な状態が不要

スラッシュコマンドを使うべき場合:

• ✅ シンプルで焦点を絞ったプロンプト
• ✅ 素早い手動呼び出し
• ✅ 個人の生産性ショートカット
• ✅ 単一ファイルのプロンプト

デシジョンツリー:

Need specialized AI assistant?
├─ Yes → Needs tools and persistent context?
│         ├─ Yes → Use Agent
│         └─ No → Quick invocation?
│                 ├─ Yes → Use Slash Command
│                 └─ No → Use Skill
└─ No → Just documentation? → Use Skill

トラブルシューティング

エージェントがアクティベートされない

問題: 期待したときにエージェントが呼び出されない

解決策:

1. ユースケースに合うように説明をより具体的にする
2. ファイルが .claude/agents/*.md にあることを確認する
3. frontmatter の構文エラーをチェックする
4. 明示的に要求する: 「[agent-name] エージェントを使って」

検証エラー

問題: エージェントファイルがスキーマに対して検証されない

解決策:

1. 名前のパターンをチェックする (小文字、ハイフンのみ)
2. 必須フィールド (name、description) を確認する
3. コンテンツが H1 見出しで始まることを確認する
4. model の値が enum に含まれていることを検証する
5. allowed-tools の綴りと大文字・小文字をチェックする

ツールの権限が拒否される

問題: エージェントが必要なツールにアクセスできない

解決策:

1. frontmatter の allowed-tools にツールを追加する
2. 正しい大文字・小文字を使用する (例: read ではなく Read)
3. Bash の制限にはパターン構文を使用する: Bash(git *)
4. すべてのツールを継承するには allowed-tools フィールドを省略する

エージェントのパフォーマンスが低い

問題: エージェントが一貫性のない、または低品質な結果を生成する

解決策:

1. ペルソナの定義を強化する
2. より具体的なプロセス手順を追加する
3. 良い/悪いパターンの例を含める
4. 明示的な出力フォーマットを定義する
5. より強力なモデル (opus) の使用を検討する
6. 複雑なエージェントを専門特化したものに分割する

覚えておいてください: 優れたエージェントとは、明確なペルソナ、ステップバイステップのプロセス、最小限のツールアクセスを備えた専門特化したエキスパートです。各エージェントは、測定可能な成果を伴って 1 つのことを卓越して行うことに集中させましょう。