custom-agent-design

Design custom agents from scratch using Claude Agent SDK patterns. Use when building domain-specific agents, designing agents with full SDK control, or creating specialized agents with custom tools and prompts.

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for designing domain-specific agents using the Claude Agent SDK. It guides developers through the entire lifecycle of agent creation—from defining purpose and selecting models to architecting system prompts, configuring tool access, and implementing governance hooks—ensuring the development of robust, specialized, and secure AI agents.

Use Cases

  • Building domain-specific agents: Creating specialized AI assistants tailored for niche industries like legal, medical, or financial analysis with precise control over their knowledge and tools.
  • Architecting Multi-Agent Systems: Designing a network of specialized agents where each has a single purpose and specific tool permissions to solve complex, multi-step workflows.
  • Implementing Agent Governance: Adding security layers and hooks to monitor tool usage and prevent unauthorized actions in production environments through the Claude Agent SDK.
  • Optimizing Agent Performance: Selecting the right model (Haiku, Sonnet, or Opus) and prompt architecture (Override vs. Append) to balance cost, speed, and reasoning quality for specific use cases.
namecustom-agent-design
descriptionDesign custom agents from scratch using Claude Agent SDK patterns. Use when building domain-specific agents, designing agents with full SDK control, or creating specialized agents with custom tools and prompts.
allowed-toolsRead, Grep, Glob

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