BIG pi update with claude chat

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

@@ -0,0 +1,110 @@
+---
+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 |