Custom Agent Foundry

Your meta-agent for designing and building highly effective custom agents tailored to specific development tasks, roles, or workflows — producing production-ready agent configurations with proper prompt engineering.

When to Use This Agent

Choose Custom Agent Foundry when:

• Designing new custom agents for specific project needs
• Creating agent system prompts with proper structure and guard rails
• Building agent workflows that integrate with specific tools and MCP servers
• Optimizing existing agent prompts for better accuracy and reliability
• Generating agent templates for common development patterns

Consider alternatives when:

• You need to install existing community agents — use an Agent Installer agent
• You need the agent to actually do the work — use the appropriate domain agent
• You need multi-agent orchestration — use a Multi-Agent Coordinator

Quick Start

Copy
# .claude/agents/custom-agent-foundry.yml
name: Custom Agent Foundry
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Agent design specialist for creating custom Claude Code agents with optimized prompts, tool selection, and guard rails

Example invocation:

claude "Design a custom agent for our React Native project that handles component scaffolding, navigation setup, and state management following our team's conventions"

Core Concepts

Agent Design Template

Copy
# Agent configuration template
name: "[Descriptive Agent Name]"
model: claude-sonnet
tools:
  - Read       # Always include for codebase awareness
  - Write      # For creating new files
  - Edit       # For modifying existing files
  - Bash       # For running commands
  - Glob       # For file discovery
  - Grep       # For code search

# System prompt structure
system_prompt: |
  ## Identity & Role
  You are a [role] specializing in [domain].

  ## Capabilities
  - [What you can do]
  - [Tools you have access to]

  ## Constraints
  - [What you should NOT do]
  - [Safety boundaries]

  ## Workflow
  1. [Step 1: Understand the request]
  2. [Step 2: Gather context]
  3. [Step 3: Implement solution]
  4. [Step 4: Verify results]

  ## Output Format
  [Expected response structure]

Agent Quality Dimensions

Dimension	Indicator	Optimization
Accuracy	Correct outputs, no hallucination	Domain grounding, verification steps
Consistency	Same input → similar output	Clear workflow, explicit formatting
Safety	No unintended side effects	Guard rails, confirmation prompts
Efficiency	Minimal unnecessary steps	Focused scope, direct workflows
Helpfulness	Actionable, complete responses	Examples, context, explanations

Configuration

Parameter	Description	Default
agent_complexity	Design complexity (simple, standard, advanced)	standard
tool_scope	Tool access level (read-only, read-write, full)	read-write
guard_rail_level	Safety constraint strictness (minimal, standard, strict)	standard
output_template	Agent config output format (yaml, json, markdown)	yaml
include_tests	Generate test scenarios for the agent	true

Best Practices

1. Define the agent's identity in the first line of the system prompt. "You are a [specific role] specializing in [specific domain]" immediately grounds the agent's behavior. Vague identities like "You are a helpful assistant" produce generic, unfocused output.

2. Include explicit negative constraints alongside capabilities. "You do NOT modify test files" or "Never delete code without confirmation" prevents common failure modes. Agents without explicit boundaries will attempt anything the user asks, even when it's outside their expertise.

3. Provide concrete examples in the system prompt. Abstract instructions are interpreted inconsistently. Include 2-3 examples of "given this input, produce this output" to anchor the agent's behavior to your expectations.

4. Design the workflow as numbered steps. Sequential workflow instructions (1. Read the relevant files, 2. Analyze the pattern, 3. Generate the solution, 4. Verify the output) produce more reliable behavior than unstructured instructions.

5. Test the agent against edge cases before deployment. Create test scenarios for ambiguous requests, missing context, conflicting instructions, and requests outside the agent's scope. A well-designed agent handles these gracefully with clarifying questions or explicit scope-boundary responses.

Common Issues

Agent takes actions outside its intended scope. Without explicit scope boundaries, agents will attempt to help with any request. Add a "When to decline" section to the system prompt that lists request types the agent should redirect to other agents.

Agent hallucinate domain knowledge it doesn't have. Ground the agent with reference documentation, project-specific patterns, or MCP tools that provide real data. Include "If you're not sure, ask for clarification rather than guessing" in the system prompt.

Agent produces inconsistent output formats. Without explicit formatting instructions, the agent's output varies between runs. Include an "Output Format" section with a template or example that defines the expected structure, headings, and content of every response.