Skip to main content
Tips

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.

custom-agentssubagentsclaude-codetips
Tip visual

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 .md file in ~/.claude/agents/, define the role in YAML frontmatter, and launch with claude --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

FieldRequiredDescription
nameYesUnique identifier (lowercase letters and hyphens)
descriptionYesWhen this agent should be used
toolsNoAllowed tools. Inherits all if omitted
disallowedToolsNoTools explicitly denied
modelNosonnet, opus, haiku, or inherit (default)
permissionModeNodefault, acceptEdits, dontAsk, plan, bypassPermissions
hooksNoAgent lifecycle hooks
memoryNouser, project, or local — persistent memory across sessions
skillsNoSkills preloaded into the agent's context
mcpServersNoMCP servers available to the agent
LocationScopePriority
--agents (CLI flag)Current session1 (highest)
.claude/agents/Project2
~/.claude/agents/Global (personal)3
Plugin's agents/ directoryWhere plugin is enabled4 (lowest)

Official docs: Create custom subagents