dotfiles/pi/.pi/agent/skills/add-agent/SKILL.md

name, description

name	description
add-agent	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:

---
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:

---
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