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