Create Custom Agents with --agent for Scoped Sessions
Custom agents are one of Claude Code's most overlooked features. Think of them as git branches for your Claude sessions: each one launches with a specific system prompt, tool restrictions, and context.
Create an agent by adding a markdown file to .claude/agents/:
# .claude/agents/ReadOnly.md
---
name: ReadOnly
description: Read-only agent restricted to the Read tool only
color: blue
tools: Read
---
You are a read-only agent that cannot edit files or run bash.
Your job is to review code and answer questions about the codebase.
Then launch it:
claude --agent=ReadOnly
This is powerful because you can create purpose-built agents for different tasks. A reviewer agent that can only read. A test agent that can only run tests and read files. A documentation agent with a specific writing style baked into its system prompt.
The tools field in the frontmatter restricts which tools the agent can use, so a ReadOnly agent literally cannot edit your files even if you ask it to.
Some practical agents worth creating:
- Reviewer: Read-only, focused on code review
- TestRunner: Can run bash and read, but cannot edit files
- Documenter: Can read and edit, with a system prompt enforcing your doc style
Custom agents keep sessions focused and prevent Claude from doing things outside the task scope.
One CLI, many specialists.
via @vinhnx
Log in to leave a comment.
When Claude writes error messages, button labels, validation text, or onboarding flows, it defaults to generic developer-speak. Add a "Users" section to your CLAUDE.md describing who your actual users are — their technical level, industry jargon, and what they care about — so Claude writes copy that makes sense to THEM, not to developers.
Every project has traps — the billing module that silently fails if you forget to queue the job, the legacy table with column names that don't match the model, the config value that must be set before tests run. Document these gotchas in your CLAUDE.md so Claude avoids the same mistakes your team spent days debugging.
Stop passing the same flags every time you launch Claude Code. Use claude config to set your preferred model, permission mode, and other defaults — at user level for personal preferences or project level for team-wide settings that everyone inherits automatically.