custom-agent-design

Custom Agent Design Skill

Design domain-specific agents using Claude Agent SDK patterns.

Purpose

Guide the design of custom agents that solve domain-specific problems with full SDK control over Context, Model, Prompt, and Tools.

When to Use

• Building a new custom agent
• Converting generic workflow to specialized agent
• Designing domain-specific automation
• Creating repeatable agent patterns

Prerequisites

• Clear understanding of the domain problem
• Access to Claude Agent SDK documentation
• Understanding of when custom agents are appropriate (see @agent-evolution-path.md)

Design Process

Step 1: Define Agent Purpose

Answer these questions:

• What specific problem does this agent solve?
• What domain expertise does it need?
• What is the single purpose? (One agent, one purpose)
• Who are the stakeholders?

Output: Purpose statement (2-3 sentences)

Step 2: Select Model

Choose based on task complexity:

Task Type	Model	Why
Simple transformations	Haiku	Fast, cheap
Balanced tasks	Sonnet	Good trade-off
Complex reasoning	Opus	Highest quality

Decision factors:

• Speed requirements
• Quality requirements
• Cost constraints
• Task complexity

Step 3: Design System Prompt

Choose architecture:

Override (system_prompt=...)

• When: Building a new product
• Result: NOT Claude Code anymore
• Full control over behavior

Append (append_system_prompt=...)

• When: Extending Claude Code
• Result: Enhanced Claude Code
• Adds capabilities

System Prompt Template:

# [Agent Name]

## Purpose
[Identity and role definition - 2-3 sentences]

## Instructions
[Core behaviors - bullet list]
- Behavior 1
- Behavior 2

## Constraints
[What the agent must NOT do]

## Examples (if needed)
[Input/Output pairs]

Step 4: Configure Tool Access

Questions to answer:

• What tools does this agent need?
• What tools should be blocked?
• Are custom tools required?

Tool configuration:

# Whitelist approach
allowed_tools=["Read", "Write", "Bash"]

# Blacklist approach
disallowed_tools=["WebFetch", "WebSearch", "TodoWrite"]

# No default tools
disallowed_tools=["*"]

# Custom tools
mcp_servers={"domain": custom_mcp_server}
allowed_tools=["mcp__domain__tool1", "mcp__domain__tool2"]

Step 5: Add Governance (Optional)

If security/governance required:

hooks = {
    "PreToolUse": [
        HookMatcher(matcher="Read", hooks=[block_sensitive_files]),
        HookMatcher(hooks=[log_all_tool_usage]),
    ]
}

Step 6: Select Deployment Form

Form	Use When
Script	One-off automation, ADWs
Terminal REPL	Interactive tools
Backend API	UI integration
Data Stream	Real-time processing
Multi-Agent	Complex workflows

Step 7: Create Configuration

Assemble the ClaudeAgentOptions:

options = ClaudeAgentOptions(
    # Context
    system_prompt=load_system_prompt("agent_system.md"),

    # Model
    model="opus",

    # Tools
    allowed_tools=["Read", "Write", "custom_tool"],
    disallowed_tools=["WebFetch", "WebSearch"],

    # Custom Tools (if needed)
    mcp_servers={"domain": domain_mcp_server},

    # Governance (if needed)
    hooks=security_hooks,

    # Session (if needed)
    resume=session_id,
)

Output Format

When designing a custom agent, provide:

## Custom Agent Design

**Name:** [agent-name]
**Purpose:** [1-2 sentences]
**Domain:** [area of expertise]

### Configuration

**Model:** [haiku/sonnet/opus] - [reason]

**System Prompt Architecture:**
- Type: [Override/Append]
- Reason: [why this choice]

**Tool Access:**
- Allowed: [list]
- Disallowed: [list]
- Custom: [list if any]

**Governance:**
- Hooks: [list if any]
- Security: [considerations]

**Deployment:**
- Form: [script/repl/api/stream/multi-agent]
- Reason: [why this form]

### System Prompt

[Full system prompt content]

### Implementation Notes

[Any special considerations]

Design Checklist

• Purpose is specific and clear
• Model matches task complexity
• System prompt architecture chosen (override vs append)
• System prompt follows template
• Tool access is minimal (only what's needed)
• Governance hooks added if security required
• Deployment form selected
• Configuration assembled

Anti-Patterns

Avoid	Why	Instead
Competing with Claude Code	Can't beat general agent	Specialize instead
Generic system prompts	No domain advantage	Domain-specific
Too many tools	Context overhead	Minimal tool set
Missing governance	Security risk	Add hooks
Override when append works	Loses Claude Code benefits	Use append

Cross-References

• @agent-evolution-path.md - When to build custom agents
• @core-four-custom.md - Core Four configuration
• @system-prompt-architecture.md - Override vs append
• @custom-tool-patterns.md - Tool creation
• @model-selection skill - Model selection guidance

Version History

• v1.0.0 (2025-12-26): Initial release

---

Last Updated

Date: 2025-12-26 Model: claude-opus-4-5-20251101