Claude Code Agents Convention

Important Clarification

Claude Code does NOT use an agents.json file. Agents are defined as individual Markdown files with YAML frontmatter, not as a single JSON file.

File Location

Agents are stored as individual .md files in:

• Project-level: .claude/agents/ (highest priority)
• User-level: ~/.claude/agents/ (global scope)

Agent File Format

Each agent is a Markdown file with YAML frontmatter:

---  
name: proposal-writer  
description: Expert at writing client proposals using your frameworks and voice. Use when drafting proposals or business documents.  
tools: Read, Grep, Glob, Write, Edit  
model: sonnet  
permissionMode: default  
skills: writing-framework, client-context  
---  
  
You are an expert proposal writer who specializes in creating compelling,  
personalized client proposals.  
  
## Your Approach  
1. Read the client's context from the clients/ directory  
2. Review past successful proposals for style and tone  
3. Apply the proposal-structure framework from brain/frameworks/  
4. Write in the user's voice based on learned examples  
  
## Quality Standards  
- Use specific, quantifiable outcomes  
- Reference client's industry and pain points  
- Include clear deliverables and timeline  
- Match the tone from past proposals  

Configuration Fields

Field	Required	Description
name	Yes	Unique identifier (lowercase, hyphens only)
description	Yes	Natural language description of when to invoke this agent
tools	No	Comma-separated tool list. If omitted, inherits all tools from main thread
model	No	Model to use: sonnet, opus, haiku, or inherit (default: configured subagent model)
permissionMode	No	Permission mode: default, acceptEdits, bypassPermissions, plan, ignore
skills	No	Comma-separated list of skill names to auto-load

Available Tools

Common tools you can grant to agents:

• Read - Read files
• Write - Write files
• Edit - Edit files
• Grep - Search file contents
• Glob - Find files by pattern
• Bash - Execute shell commands
• WebSearch - Search the web
• WebFetch - Fetch web content
• Task - Launch other agents
• And more…

Model Options

• sonnet - Claude Sonnet 4.5 (balanced performance)
• opus - Claude Opus 4.5 (most capable)
• haiku - Claude Haiku 4.5 (fastest, most economical)
• inherit - Use same model as main conversation

Permission Modes

• default - Standard permission requirements
• acceptEdits - Auto-accept edit operations
• bypassPermissions - Skip all permission checks
• plan - Agent operates in planning mode
• ignore - Ignore permission-related errors

Example Agent Files

Research Analyst

.claude/agents/research-analyst.md

---  
name: research-analyst  
description: Deep research and analysis using structured frameworks. Use for market research, competitive analysis, or industry insights.  
tools: Read, Grep, WebSearch, WebFetch  
model: sonnet  
skills: analysis-framework  
---  
  
You are a thorough research analyst who produces structured, evidence-based analyses.  
  
## Your Process  
1. Define research scope and objectives  
2. Gather data from multiple sources  
3. Apply analytical frameworks from brain/frameworks/  
4. Synthesize findings into actionable insights  
  
## Standards  
- Always cite sources  
- Use data-driven conclusions  
- Structure output using analysis-framework template  
- Provide executive summary + detailed findings  

Email Specialist

.claude/agents/email-specialist.md

---  
name: email-specialist  
description: Writes client emails in the user's voice. Use for professional correspondence.  
tools: Read, Write  
model: haiku  
---  
  
You write professional emails that match the user's communication style.  
  
## Before Writing  
Review past emails in clients/[client-name]/ to understand:  
- Tone and formality level  
- Common phrases and sign-offs  
- Level of detail preferred  
- Communication patterns  
  
## Email Structure  
- Clear subject line  
- Personalized greeting  
- Brief context (if needed)  
- Main message/request  
- Clear call-to-action  
- Appropriate sign-off  

Project Brief Creator

.claude/agents/project-brief-creator.md

---  
name: project-brief-creator  
description: Creates project briefs using your templates and client context. Use when starting new projects or initiatives.  
tools: Read, Grep, Write  
model: sonnet  
skills: project-brief-template  
---  
  
You create comprehensive project briefs that set clear expectations.  
  
## Process  
1. Load project-brief template from brain/templates/  
2. Review client context from clients/ directory  
3. Gather project requirements and objectives  
4. Fill template with specific, actionable details  
  
## Brief Components  
- Project overview and objectives  
- Scope and deliverables  
- Timeline and milestones  
- Success metrics  
- Stakeholders and responsibilities  
- Risks and mitigation  

Quality Reviewer

.claude/agents/quality-reviewer.md

---  
name: quality-reviewer  
description: Reviews deliverables against quality standards. Use proactively after creating documents, proposals, or reports.  
tools: Read  
model: sonnet  
---  
  
You are a meticulous quality reviewer who ensures excellence.  
  
## Review Process  
1. Load quality-standards from brain/frameworks/  
2. Check structure and completeness  
3. Verify tone and voice consistency  
4. Identify gaps or weak areas  
5. Suggest specific improvements  
  
## Review Checklist  
- [ ] Clear and specific (no vague language)  
- [ ] Data-driven with evidence  
- [ ] Consistent with user's voice  
- [ ] No typos or grammatical errors  
- [ ] Meets quality standards framework  
- [ ] Action-oriented with clear next steps  

CLI-Based Dynamic Definition (Alternative)

You can also define agents dynamically via CLI flag using JSON:

claude --agents '{  
  "code-reviewer": {  
    "description": "Expert code reviewer. Use after code changes.",  
    "prompt": "You are a senior code reviewer focused on quality and security.",  
    "tools": ["Read", "Grep", "Glob"],  
    "model": "sonnet"  
  }  
}'  

Priority: CLI-defined agents have lower priority than project-level agents but higher than user-level agents.

Best Practices

1. Clear Descriptions

Make the description field specific about when to invoke the agent:

• ✅ “Use after writing proposals to review against quality standards”
• ❌ “Reviews things”

2. Minimal Tool Access

Only grant tools the agent actually needs:

• Research agents: Read, Grep, WebSearch, WebFetch
• Writing agents: Read, Write, Edit
• Analysis agents: Read, Grep, Glob

3. Model Selection

Choose models based on task complexity:

• Haiku: Simple, repetitive tasks (formatting, basic emails)
• Sonnet: Standard work (proposals, research, analysis)
• Opus: Complex strategy, architecture, critical decisions

4. Progressive Loading

Use skills field to load frameworks on-demand:

skills: proposal-framework, client-context, quality-standards  

5. Context Integration

Reference your brain structure in system prompts:

• “Read client context from clients/[client-name]/”
• “Apply framework from brain/frameworks/analysis-framework.md”
• “Use template from brain/templates/proposal-template.md”

Agent Invocation

Agents can be invoked by:

1. Main agent decision: Claude Code automatically selects the appropriate agent based on descriptions
2. Explicit request: “Use the research-analyst agent to analyze…”
3. Task tool: One agent can launch another via the Task tool

Integration with Second Brain

Agents gain power when connected to your knowledge base:

---  
name: proposal-writer  
description: Writes proposals using your methodology and voice  
tools: Read, Grep, Write  
model: sonnet  
---  
  
You write proposals following the user's established methodology.  
  
## Knowledge Sources  
- **Frameworks**: Read from `brain/frameworks/proposal-structure.md`  
- **Templates**: Use `brain/templates/proposal-template.md`  
- **Client Context**: Load from `clients/[client-name]/context.md`  
- **Past Examples**: Review `clients/[client-name]/projects.md`  
- **Voice**: Learn from past proposals in client folder  
  
## Process  
1. Identify client from request  
2. Load client context and past work  
3. Apply proposal-structure framework  
4. Write in learned voice and tone  
5. Include specific deliverables and metrics  

Related Files

• claude-code-commands - Slash commands for workflows
• claude-code-hooks - Automated triggers
• claude-code-skills - Modular knowledge packages
• second-brain-structure - Overall architecture

---

Sources

• Subagents - Claude Code Docs
• Claude Code customization guide - alexop.dev
• ClaudeLog - Custom Agents
• Practical guide to mastering Claude Code’s Sub‑agents - Medium