code/commands/builtins/agent.md

---
name: agent
description: Create, use, list, show, delete, or reset custom AI agents
argument-hint: create <description> | use <name> | list | show <name> | delete <name> | reset
---
# Custom Agent Command

The user invoked `/agent` with arguments: `$ARGUMENTS`

## Parse the arguments and follow the matching branch

### If arguments start with `create ` (i.e. `/agent create <description>`)
You are creating a custom agent definition based on the user's natural-language description. Follow the AGENT_GENERATION_PROMPT (which is included below) to author an AGENT.md file, then use `write_file` to save it under `.sonicoder/agents/<name>/AGENT.md` in the workspace.

After saving, briefly tell the user the agent's name and that they can activate it with `/agent use <name>` or by clicking it in the Agents panel of the Agent tab.

The description provided by the user is:
**$ARGUMENTS** (everything after `/agent create ` — strip the leading word "create")

Use the AGENT_GENERATION_PROMPT exactly. Write only the AGENT.md file — no other files.

### If arguments start with `use ` (i.e. `/agent use <name>`)
Tell the user that the agent has been set as active for subsequent prompts. Mention the agent's name and description (if known). Note: actual activation is performed by the backend when this command is dispatched; just acknowledge it.

### If arguments are `list`
List all available agents by reading the `.sonicoder/agents/` directory (use `list_dir` or `glob`) plus the built-in agents (which you cannot read but you know exist: `code-reviewer`, `test-writer`). Present a table:

| Name | Description | Author | Tools |
|------|-------------|--------|-------|

### If arguments start with `show ` (i.e. `/agent show <name>`)
Read the file `.sonicoder/agents/<name>/AGENT.md` from the workspace and display it to the user verbatim in a markdown code block. If the file does not exist, tell the user the agent was not found and suggest `/agent list`.

### If arguments start with `delete ` (i.e. `/agent delete <name>`)
Tell the user that the agent has been queued for deletion. Actual deletion is performed by the backend. Just acknowledge.

### If arguments are `reset` (or empty)
Tell the user that the active agent has been reset to the default SoniCoder agent. Subsequent prompts will use the base persona.

### Otherwise (unknown subcommand or no arguments)
Print a short help message:
```
Usage:
  /agent create <natural-language description>   # AI generates a new agent
  /agent use <name>                              # Activate a saved agent
  /agent list                                    # List all agents
  /agent show <name>                             # Show an agent's full definition
  /agent delete <name>                           # Delete a user agent
  /agent reset                                   # Reset to default SoniCoder
```

## AGENT_GENERATION_PROMPT (use this when subcommand is `create`)

You are creating a custom agent definition for SoniCoder.

Based on the user's description, generate a complete AGENT.md file that defines a specialized agent persona.

### Available Tools (pick a subset, or all)
read_file, write_file, edit_file, multi_edit, list_dir, glob, grep, bash, todo_read, todo_write, todo_update

### Available Built-in Skills (pick zero or more)
frontend-design, feature-dev, code-review, debugging, fullstack-scaffold, commit-workflow

### Output Format
Use the `write_file` tool to save exactly ONE file with this content:

Path: `.sonicoder/agents/<kebab-case-name>/AGENT.md`

```
---
name: <kebab-case-name>
description: <one-line description, max 200 chars>
tools: <comma-separated subset of available tools>
skills: <comma-separated skill names, or empty>
temperature: <float 0.0-1.0 — lower for precise tasks, higher for creative>
max_iterations: <int 4-20>
tags: <comma-separated tags>
author: AI-generated
created: <today's date YYYY-MM-DD>
---

# <Agent Name in Title Case>

<Full system prompt extension. Include:>
<- Persona description (who the agent is)>
<- Core responsibilities>
<- Workflow / step-by-step approach>
<- Output format expectations>
<- Critical rules and constraints>
```

### Rules
- The agent name MUST be kebab-case (lowercase, hyphens only).
- Pick tools that match the agent's purpose — don't give a read-only reviewer `write_file`.
- The body should be 150-400 words, specific and actionable.
- Do NOT include any other files. Just the one AGENT.md.
- After writing the file, briefly tell the user they can activate the agent with `/agent use <name>`.

### User's Description
$ARGUMENTS