Custom agents are persistent subagent definitions stored as Markdown files in .agent/agents/. We use “custom agents” here to distinguish file-based, reusable definitions from the temporary subagents the agent spawns dynamically for one-off tasks. Both are configured the same way; the difference is persistence and intent.
Each agent gets its own system prompt, tool set, model selection, and permission mode. When you or the agent invokes an agent, it runs in its own context with only the capabilities you’ve defined.
Creating an agent
Using /agents (recommended)
Run /agents in your AI coding agent to create, edit, and manage agents interactively. Choose “Create new agent” → select scope (Personal or Project) → describe what the agent should do. The agent generates the configuration.
Manual file creation
Create a Markdown file in .agent/agents/ (project) or ~/.agent/agents/ (personal):
---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
tools: Read, Glob, Grep
model: standard
---
You are a senior code reviewer. Analyze code for:
- Security vulnerabilities
- Performance issues
- Readability and maintainability
- Test coverage gaps
Provide specific, actionable feedback with code examples.Supported frontmatter fields
| Field | Required | Description |
|---|---|---|
name | Yes | Unique identifier (lowercase, hyphens) |
description | Yes | When the agent should delegate to this agent |
tools | No | Tools the agent can use (inherits all if omitted) |
disallowedTools | No | Tools to deny |
model | No | standard, capable, fast, or inherit |
permissionMode | No | default, acceptEdits, plan, auto, dontAsk, bypassPermissions |
maxTurns | No | Maximum agentic turns before stopping |
isolation | No | Set to worktree for isolated file system |
color | No | Background color in the UI |
memory | No | user, project, or local for persistent memory |
skills | No | Skills loaded into the agent’s context |
mcpServers | No | MCP servers available to this agent |
hooks | No | Lifecycle hooks scoped to this agent |
effort | No | Thinking effort level: low, medium, high, max |
background | No | Run the agent in the background |
initialPrompt | No | First prompt sent automatically when the agent starts |
Agent scope and priority
| Location | Scope | Priority |
|---|---|---|
| Managed settings | Organization-wide | Highest |
--agents CLI flag | Current session only | High |
.agent/agents/ | Current project | Medium |
~/.agent/agents/ | All your projects | Lower |
| Plugin agents/ | Where plugin is enabled | Lowest |
When multiple agents share the same name, the higher-priority location wins.
Launching agents
From the CLI:
agent --agent code-reviewerDuring a session, run /agents to see available agents or ask the agent directly — it delegates based on the agent’s description.
For one-off agent definitions without saving files:
agent --agents '{"reviewer": {"description": "Code reviewer", "prompt": "You review code.", "tools": ["Read", "Grep"], "model": "standard"}}'Custom agents vs subagents
| Custom Agents | Subagents | |
|---|---|---|
| Defined in | .agent/agents/*.md files | Spawned dynamically by the agent |
| Persistence | Permanent, version-controlled | Temporary, single-task |
| Configuration | Full frontmatter (tools, model, hooks, MCP) | Inherited from parent with optional overrides |
| Use case | Recurring roles (reviewer, debugger, architect) | One-off parallel investigations |
Example agents
Read-only analyst
---
name: analyst
description: Analyzes code patterns and architecture without making changes
tools: Read, Glob, Grep, Bash
model: fast
---
You are a read-only code analyst. Never suggest edits directly.
Analyze patterns, dependencies, and architecture. Report findings clearly.Build validator
---
name: build-validator
description: Validates that the project builds and tests pass
tools: Bash, Read
model: standard
---
Run the build and test suite. Report any failures with file paths and line numbers.
Do not fix issues — only report them.
Commands to run:
1. npm run build
2. npm testSecurity auditor
---
name: security-auditor
description: Scans code for security vulnerabilities
tools: Read, Glob, Grep
model: capable
permissionMode: plan
---
You are a security auditor. Scan for OWASP Top 10 vulnerabilities:
- SQL injection, XSS, CSRF
- Hardcoded secrets and credentials
- Insecure dependencies
- Missing input validation
Report severity (Critical/High/Medium/Low) with specific file locations.Tips
- Start with read-only agents (restrict tools to Read, Glob, Grep) for safety.
- Use
model: fastfor quick agents that don’t need deep reasoning. - Set
isolation: worktreewhen agents need to make experimental changes. - Check project agents into version control so the whole team benefits.
- Write clear descriptions — the agent uses them to decide when to delegate.