practitioner tip
Turn Your Whole Session Into a Specialized Agent with --agent
AIErudit angle: Reusable, role-scoped agents are how teams standardize AI work — a reviewer, a debugger, a deployer, each with its own prompt, tool allowlist, and model. Defining agents as versioned Markdown files turns tribal prompting habits into shareable delivery infrastructure.
Published: Mar 10, 2026 Updated: 2026-04-28
Original: https://wmedia.es/en/tips/claude-code-create-custom-agents
Claude Code lets you create specialized agents as Markdown files with YAML frontmatter. Each agent has its own system prompt, restricted tools, and model. When you launch a session with claude --agent <name>, the entire conversation transforms — it's not a delegated subagent, it's your main session operating with a different persona and rules.
Think of it as having multiple versions of Claude Code, each one tailored for a specific role: reviewer, debugger, deployer, or whatever you need.
TL;DR Create a
.mdfile in~/.claude/agents/, define the role in YAML frontmatter, and launch withclaude --agent name. Your entire session becomes that specialized agent.
Result — a ready-to-use code review agent:
# ~/.claude/agents/reviewer.md
You are a senior code reviewer. When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Provide feedback organized by priority:
- Critical (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
Include specific examples of how to fix each issue.
Setup
1. Create the agent file
Create a .md file in one of these locations:
# Global — available across all your projects
~/.claude/agents/reviewer.md
# Project — shared with your team via git
.claude/agents/reviewer.md
2. Launch the session as the agent
claude --agent reviewer
Claude Code starts with the system prompt, tools, and model you defined. You won't see the default prompt — you're inside the agent.
3. Use the interactive wizard
If you'd rather not write the file manually:
claude
# Inside the session:
/agents
Select "Create new agent", choose the scope (user or project), and Claude guides you step by step — it can even generate the system prompt for you.
4. Define ephemeral agents from the CLI (optional)
To test without creating a file, use --agents (plural) with inline JSON:
claude --agents '{
"reviewer": {
"description": "Expert code reviewer",
"prompt": "You are a senior code reviewer. Focus on quality and security.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
}
}'
Note: --agent (singular) transforms your main session into an existing agent. --agents (plural) defines ephemeral subagents that Claude can delegate to during the session.
Reference
| Field | Required | Description |
|---|---|---|
name | Yes | Unique identifier (lowercase letters and hyphens) |
description | Yes | When this agent should be used |
tools | No | Allowed tools. Inherits all if omitted |
disallowedTools | No | Tools explicitly denied |
model | No | sonnet, opus, haiku, or inherit (default) |
permissionMode | No | default, acceptEdits, dontAsk, plan, bypassPermissions |
hooks | No | Agent lifecycle hooks |
memory | No | user, project, or local — persistent memory across sessions |
skills | No | Skills preloaded into the agent's context |
mcpServers | No | MCP servers available to the agent |
| Location | Scope | Priority |
|---|---|---|
--agents (CLI flag) | Current session | 1 (highest) |
.claude/agents/ | Project | 2 |
~/.claude/agents/ | Global (personal) | 3 |
Plugin's agents/ directory | Where plugin is enabled | 4 (lowest) |
Official docs: Create custom subagents