111 lines
3.3 KiB
Markdown
111 lines
3.3 KiB
Markdown
---
|
|
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 |
|