---
name: add-agent
description: "Add a new Claude agent definition to ~/.claude/agents/ and an accompanying skill to ~/.pi/agent/skills/. Use when creating new specialized agents."
---

# Add Agent

When the user wants to create a new specialized Claude agent:

## Agent File Convention

Create a `.md` file in `~/.claude/agents/` with this structure:

```markdown
---
name: agent_name
description: One-line description of what the agent does
tools: Read, Bash[, Edit, Write]  # include only what's needed
model: sonnet | opus
---

You are an [role]. [1-2 sentence description of purpose].

Available tools:
- read: Read file contents
- bash: Execute bash commands
- edit: Make surgical edits to files        # if applicable
- write: Create or overwrite files           # if applicable

Guidelines:
- Use bash for file operations: prefer `rg` over grep, `fd` over find, glob patterns for batch file matching
- Use read to examine files [before editing]  # adapt phrasing
- [Agent-specific guidelines]
- When summarizing your actions, output plain text directly - do NOT use cat or bash to display what you did
- Be concise in your responses
- Show file paths clearly when working with files
```

## Key Rules

1. **`name`** in frontmatter must match what skills reference as `agent: "name"`
2. **`tools`** — only include tools the agent actually needs. Read-only agents use `Read, Bash`
3. **`model`** — `sonnet` for execution/review, `opus` for strategic/advisory work
4. **Always include** the "output plain text directly" guideline — agents without it tend to use `cat`/`echo` instead of responding directly
5. **Bash guideline** should read: `prefer \`rg\` over grep, \`fd\` over find, glob patterns for batch file matching`
6. **Bash tool description** should be: `Execute bash commands`

## Skill File Convention

Create `~/.pi/agent/skills/<skill-name>/SKILL.md`:

```markdown
---
name: skill-name
description: "What triggers this skill. Use when [condition]."
---

# Skill Title

When [trigger condition]:

## What to include in the prompt

1. **[Section 1]** — description
2. **[Section 2]** — description
...

The `agent_name` agent has `Tool1` and `Tool2` tools only — [what it can/can't do].

## How to call

\```
ask_claude({
  agent: "agent_name",
  question: "Specific instruction for the agent.",
  prompt: `
## Section 1
[Template]

## Section 2
[Template]
`
})
\```

## After the review

- [What to do with the agent's output]
- [How to summarize for the user]
- [When to loop back or escalate]
```

## Skill Key Rules

1. **Skill `name`** should be kebab-case (e.g., `claude-debug`, not `claude_debug`)
2. **Description** must be in quotes if it contains special characters
3. **`agent:` in `ask_claude()`** must match the agent's `name:` exactly
4. **Include a "What to include" section** — gives the calling agent a template
5. **Include a "How to call" section** — with a concrete `ask_claude()` example
6. **Include an "After the review" section** — what to do with the output

## Existing Agents (for reference)

| Agent | Model | Tools | Purpose |
|-------|-------|-------|---------|
| `minimal` | sonnet | Read, Bash, Edit, Write | General coding |
| `code_review` | sonnet | Read, Bash, Edit, Write | Review & fix code |
| `plan_review` | opus | Read, Bash | Review plans |
| `debug` | sonnet | Read, Bash | Trace bugs |
| `oracle` | opus | Read, Bash | Strategic guidance |