ESC
Type to search across all documentation
↑↓ navigate ↵ open esc close
Custom Agent Roles

Custom Agent Roles

Beyond the 7 built-in roles, you can define custom agent roles with specific system prompts, tool permissions, and trust levels.

File Locations

  • User-global roles: ~/.coalcode/agents/roles/<name>.md
  • Project-local roles: .coals/agents/<name>.md

Project-local roles override user-global roles of the same name.

Markdown Format

Each role is defined in a markdown file with three sections:

# Security Auditor

Audits code for security vulnerabilities and produces a structured report.

## System Prompt

You are a security-focused code reviewer. Your job is to identify:
- SQL injection vulnerabilities
- Authentication and authorization flaws
- Insecure direct object references
- XSS and CSRF risks
- Hardcoded secrets or credentials

Organize findings by severity: Critical, High, Medium, Low.
Include the file path and line number for each finding.
Suggest specific fixes for each issue.

## Configuration

- trust_level: readonly
- token_budget: 80000
- time_limit: 180000
- allowed_tools: read_file, glob, grep, list_dir, web_search
- can_spawn_children: false

Sections

  1. # Role Name — The display name. The filename is used as the role identifier for commands.
  2. Description — Text between the heading and the first ##. Shown in /roles output.
  3. ## System Prompt — The full system prompt injected into the agent's context. This defines the agent's personality, expertise, and task approach.
  4. ## Configuration — Key-value pairs controlling the agent's permissions and limits.

Configuration Options

Key Values Default Description
trust_level readonly, supervised, autonomous supervised Controls tool approval behavior
token_budget Number 128000 Maximum tokens for this agent's session
time_limit Milliseconds 300000 (5 min) Maximum wall-clock time before timeout
allowed_tools Comma-separated tool names All tools Tools the agent can use
denied_tools Comma-separated tool names None Tools explicitly blocked
can_spawn_children true or false false Whether the agent can spawn child agents

Trust Levels

  • readonly — Cannot write files, edit files, or run commands. Safe for analysis tasks.
  • supervised — Can use all allowed tools but pauses for approval on writes and commands (unless in Auto mode).
  • autonomous — Runs without interruption. All tool calls execute immediately.

Tool Names

Available tool names for allowed_tools and denied_tools:

read_file, write_file, edit_file, bash, python, applescript, glob, grep, list_dir, web_search, http_request, todo_update, spawn_agent, delegate

Wildcards are supported:

  • mcp__* — All MCP tools from all servers
  • mcp__github__* — All tools from the GitHub MCP server
  • * — All tools

Managing Roles

Create a new role

/role create security-auditor

This scaffolds a template markdown file and shows you the path.

Edit an existing role

/role edit security-auditor

Shows the file path so you can open it in your editor.

Delete a role

/role delete security-auditor

Only user-defined roles can be deleted. Built-in roles cannot be removed.

List all roles

/roles

Shows every available role with its source (builtin, user, or project), trust level, and allowed tools.

Using Custom Roles

Once created, use custom roles exactly like built-in ones:

/agent security-auditor review the payment processing module
@security-auditor check src/api/ for OWASP top 10 issues

Custom roles also work in team presets if referenced by name.

Examples

Documentation Writer

# Doc Writer

Generates comprehensive documentation for code modules.

## System Prompt

You are a technical documentation specialist. When given a module or directory:
1. Read all source files to understand the API
2. Document every exported function, class, and type
3. Include usage examples for each public API
4. Note any configuration or environment requirements
5. Write in clear, concise language suitable for other developers

Output format: Markdown with code examples.

## Configuration

- trust_level: readonly
- token_budget: 100000
- time_limit: 300000
- allowed_tools: read_file, glob, grep, list_dir, web_search
- can_spawn_children: false

Migration Helper

# Migration Helper

Assists with codebase migrations and upgrades.

## System Prompt

You help migrate codebases between framework versions or technology stacks. Your approach:
1. Analyze the current codebase to understand what needs to change
2. Research the target version's migration guide
3. Make changes incrementally, testing after each step
4. Preserve existing behavior — don't refactor beyond what the migration requires

Always run tests after changes. If tests fail, fix the issue before moving on.

## Configuration

- trust_level: supervised
- token_budget: 128000
- time_limit: 600000
- allowed_tools: read_file, write_file, edit_file, bash, glob, grep, list_dir, web_search, http_request
- can_spawn_children: false