code/commands/builtins/agent.md

metadata

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