laurigates/custom-agent-definitions

Custom Agent Definitions

Expert knowledge for defining and configuring custom agents in Claude Code.

When to Use This Skill

| Use this skill when... | Use agent-teams instead when... | |---|---| | Authoring a new .md agent definition file in .claude/agents/ | Spawning multiple already-defined agents that need to coordinate via TeamCreate | | Configuring a single agent's model, allowed-tools, or context: fork | Setting up a lead/teammate architecture with a shared task list | | Constraining tool access for a specialised read-only or write-restricted agent | Sequencing parallel work across worktrees (see parallel-agent-dispatch) | | Writing the system prompt that defines what one agent does | Auditing existing agent definitions for security or completeness (see meta-audit) |

Core Concepts

Custom Agents allow you to define specialized agent types beyond the built-in ones (Explore, Plan, Bash, etc.). Each custom agent can have its own model, tools, and context configuration.

Agent Definition Schema

Custom agents are defined in .claude/agents/ or via plugin agent directories.

Basic Structure

---
name: my-custom-agent
description: What this agent does
model: sonnet
allowed-tools: Bash, Read, Grep, Glob
---

# Agent System Prompt

Instructions and context for the agent...

Context Forking

The context field controls how the agent's context relates to the parent conversation:

| Value | Behavior | |-------|----------| | fork | Creates an independent context copy - agent sees parent history but changes don't affect parent | | (default) | Agent shares context with parent and can see/modify conversation state |

Example: Isolated Research Agent

---
name: research-agent
description: Research questions without modifying main context
model: sonnet
context: fork
allowed-tools: WebSearch, WebFetch, Read
---

# Research Agent

You are a research specialist. Search for information and provide findings.
Your research doesn't affect the main conversation context.

When to use context: fork:

• Exploratory research that shouldn't pollute main context
• Parallel investigations with potentially conflicting approaches
• Isolated experiments or testing
• Background tasks that run independently

Agent Field for Delegation

The agent field specifies which agent type to use when delegating via the Agent tool:

---
name: code-review-workflow
description: Comprehensive code review
agent: security-auditor
allowed-tools: Read, Grep, Glob, TodoWrite
---

This allows commands and skills to specify a preferred agent type for delegation.

Disallowed Tools (Restrictions)

The disallowedTools field explicitly prevents an agent from using certain tools:

---
name: read-only-explorer
description: Explore codebase without modifications
model: haiku
allowed-tools: Bash, Read, Grep, Glob
disallowedTools: Write, Edit, NotebookEdit
---

# Read-Only Explorer

Explore and analyze code. Do not make any modifications.

Disallowed Tools vs Allowed Tools:

| Field | Purpose | Behavior | |-------|---------|----------| | allowed-tools | Whitelist of permitted tools | Agent can ONLY use these tools | | disallowedTools | Blacklist of forbidden tools | Agent can use all tools EXCEPT these |

When to use disallowedTools:

• Creating read-only agents that can explore but not modify
• Restricting dangerous capabilities (Bash execution)
• Sandboxing agents for specific tasks
• Security-sensitive contexts

Complete Example

---
name: security-auditor
description: Security-focused code review agent
model: sonnet
context: fork
allowed-tools: Read, Grep, Glob, WebSearch, TodoWrite
disallowedTools: Bash, Write, Edit
created: 2026-01-20
modified: 2026-01-20
reviewed: 2026-01-20
---

# Security Auditor Agent

You are a security auditor. Analyze code for vulnerabilities.

## Capabilities
- Read and analyze source code
- Search for security patterns
- Research known vulnerabilities
- Track findings in todo list

## Restrictions
- Cannot execute code (no Bash)
- Cannot modify files (no Write/Edit)
- Work in isolated context

## Focus Areas
1. SQL injection vulnerabilities
2. XSS vulnerabilities
3. Authentication/authorization flaws
4. Secrets/credentials in code
5. Insecure dependencies

Defining Agents in Plugins

Plugins can define custom agents in their agents/ directory:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   ├── security-auditor.md
│   ├── performance-analyzer.md
│   └── accessibility-checker.md
└── skills/
    └── ...

Each agent file follows the same YAML frontmatter + markdown body structure.

Using Custom Agents

Via Task Tool

Agent tool with subagent_type="security-auditor" for security analysis.

Via Delegation

/delegate Audit auth module for security issues

The delegation system matches tasks to appropriate custom agents.

Best Practices

1. Principle of Least Privilege

Only grant tools the agent actually needs:

# Good: Minimal tools for the task
allowed-tools: Read, Grep, Glob

# Avoid: Overly permissive
allowed-tools: Bash, Read, Write, Edit, Grep, Glob, WebSearch, WebFetch

2. Use Context Forking for Isolation

# Good: Isolated exploratory work
context: fork

3. Combine Allowed and Disallowed

# Explicit whitelist with safety blacklist
allowed-tools: Bash, Read, Grep
disallowedTools: Write, Edit

4. Clear Agent Descriptions

description: |
  Security auditor for identifying vulnerabilities in authentication
  and authorization code. Reports findings without modifying code.

5. Model Selection

| Use Case | Model | Model ID | |----------|-------|----------| | Simple/mechanical tasks | haiku | claude-haiku-4-5 | | Development workflows | sonnet | claude-sonnet-4-6 | | Deep reasoning/analysis | opus | claude-opus-4-7 |

6. Report failures loudly

A dispatched agent that hits a wall must say so in its final message — never a one-word summary like Terminal. / Done. / Stopped. On a blocker, the agent should commit and push its in-progress work, open a draft PR, and state exactly what stopped it and which tools were denied. A one-word surrender is indistinguishable from success to the orchestrator, so the work is silently cleaned up and lost (issue #1422). See parallel-agent-dispatch → "Loud-failure contract" for the dispatch-prompt form every brief should carry.

Agent Configuration Fields Reference

| Field | Type | Description | |-------|------|-------------| | name | string | Agent identifier | | description | string | What the agent does | | model | string | Model to use (haiku, sonnet, opus) | | context | string | Context mode: fork or default | | permissionMode | string | default, acceptEdits, dontAsk, bypassPermissions, or plan | | maxTurns | number | Maximum agentic turns before agent stops | | background | bool | Set true to always run as a background task | | memory | string | Persistent memory scope: user, project, or local | | skills | list | Skill names to preload into agent context at startup | | mcpServers | list | MCP server names available to this agent | | tools | list | Tools the agent can use (in agents/ dir; use allowed-tools in skills) | | disallowedTools | list | Tools the agent cannot use | | created | date | Creation date | | modified | date | Last modification date | | reviewed | date | Last review date |

Common Patterns

Read-Only Research Agent

context: fork
allowed-tools: Read, Grep, Glob, WebSearch, WebFetch
disallowedTools: Bash, Write, Edit

Safe Code Executor

allowed-tools: Bash, Read
disallowedTools: Write, Edit

Documentation Writer

allowed-tools: Read, Write, Edit, Grep, Glob
disallowedTools: Bash

Full-Power Developer

allowed-tools: Bash, Read, Write, Edit, Grep, Glob, TodoWrite

Agentic Optimizations

| Context | Configuration | |---------|---------------| | Exploratory research | context: fork, model: haiku | | Security analysis | context: fork, disallowedTools: Bash, Write, Edit | | Quick lookups | model: haiku, minimal tools | | Complex implementation | model: sonnet, full tools |

Quick Reference

Context Modes

| Mode | Isolation | Use Case | |------|-----------|----------| | (default) | Shared | Normal workflows | | fork | Isolated | Research, experiments |

Tool Restriction Patterns

| Pattern | Fields | |---------|--------| | Whitelist only | allowed-tools: Tool1, Tool2 | | Blacklist only | disallowedTools: Tool1, Tool2 | | Combined | Both fields specified |