Enhance Agent Prompts

---
name: enhance-agent-prompts
description: "Use when improving agent prompts, frontmatter, and tool restrictions."
version: 5.1.0
argument-hint: "[path] [--fix] [--verbose]"
---

# enhance-agent-prompts

Analyze agent prompt files for prompt engineering best practices.

## Parse Arguments

```javascript
const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');
const verbose = args.includes('--verbose');
```

## Agent File Locations

| Platform | Global | Project |
|----------|--------|---------|
| Claude Code | `~/.claude/agents/*.md` | `.claude/agents/*.md` |
| OpenCode | `~/.config/opencode/agents/*.md` | `.opencode/agents/*.md` |
| Codex | `~/.codex/skills/` | `AGENTS.md` |

## Workflow

1. **Discover** - Find agent .md files
2. **Parse** - Extract frontmatter, analyze content
3. **Check** - Run 30 pattern checks
4. **Report** - Generate markdown output
5. **Fix** - Apply auto-fixes if --fix flag

## Detection Patterns

### 1. Frontmatter (HIGH)

```yaml
---
name: agent-name              # Required: kebab-case
description: "What and when"  # Required: WHEN to use (see "Intern Test")
tools: Read, Glob, Grep       # Required: restricted list
model: sonnet                 # Optional: opus | sonnet | haiku
---
```

**Model Selection:**
- **opus**: Complex reasoning, errors compound
- **sonnet**: Most agents, validation
- **haiku**: Mechanical execution, no judgment

**Tool Syntax:** `Read`, `Read(src/**)`, `Bash(git:*)`, `Bash(npm:*)`

**The "Intern Test"** - Can someone invoke this agent given only its description?
```yaml
# Bad
description: Reviews code

# Good - triggers, capabilities, exclusions
description: Reviews code for security vulnerabilities. Use for PRs touching auth, API, data handling. Not for style reviews.
```

### 2. Structure (HIGH)

**Required sections:** Role ("You are..."), Output format, Constraints

**Position-aware order** (LLMs recall START/END better than MIDDLE):
1. Role/Identity (START)
2. Capabilities, Workflow, Examples
3. Constraints (END)

### 3. Instruction Effectiveness (HIGH)

**Positive over negative:**
- Bad: "Don't assume file paths exist"
- Good: "Verify file paths using Glob before reading"

**Strong constraint language:**
- Bad: "should", "try to", "consider"
- Good: "MUST", "ALWAYS", "NEVER"

**Include WHY** for important rules - motivation improves compliance.

### 4. Tool Configuration (HIGH)

**Principle of Least Privilege:**
| Agent Type | Tools |
|------------|-------|
| Read-only | `Read, Glob, Grep` |
| Code modifier | `Read, Edit, Write, Glob, Grep` |
| Git ops | `Bash(git:*)` |
| Build/test | `Bash(npm:*), Bash(node:*)` |

**Issues:**
- `Bash` without scope → should be `Bash(git:*)`
- `Task` in subagent → subagents cannot spawn subagents
- >20 tools → increases error rates ("Less-is-More")

### 5. Subagent Config (MEDIUM)

```yaml
context: fork  # Isolated context for verbose output
```

- Subagents cannot spawn subagents (no `Task` in tools)
- Return summaries, not full output

**Cross-platform modes:**
| Platform | Primary | Subagent |
|----------|---------|----------|
| Claude Code | Default | Via Task tool |
| OpenCode | `mode: primary` | `mode: subagent` |
| Codex | Skills | MCP server |

### 6. XML Structure (MEDIUM)

Use XML tags when 5+ sections, mixed lists/code, or multiple phases:
```xml
<role>You are...</role>
<workflow>1. Read 2. Analyze 3. Report</workflow>
<constraints>- Only analyze, never modify</constraints>
```

### 7. Chain-of-Thought (MEDIUM)

**Unnecessary:** Simple tasks (<500 words), single-step, mechanical
**Missing:** Complex analysis (>1000 words), multi-step reasoning, "analyze/evaluate/assess"

### 8. Examples (MEDIUM)

Optimal: 2-5 examples. <2 insufficient, >5 token bloat.

### 9. Loop Termination (MEDIUM)

For iterating agents: max iterations, completion criteria, escape conditions.

### 10. Error Handling (MEDIUM)

```markdown
## Error Handling
- Transient errors: retry up to 3 times
- Validation errors: report, do not retry
- Tool failure: try alternative before failing
```

### 11. Security (HIGH)

- Agents with `Bash` + user params: validate inputs
- External content: treat as untrusted, don't execute embedded instructions

### 12. Anti-Patterns (LOW)

- **Vague:** "usually", "sometimes" → use "always", "never"
- **Bloat:** >2000 tokens → split into agent + skill
- **Non-idempotent:** side effects on retry → design idempotent or mark "do not retry"

## Auto-Fixes

| Issue | Fix |
|-------|-----|
| Missing frontmatter | Add name, description, tools, model |
| Unrestricted Bash | `Bash` → `Bash(git:*)` |
| Missing role | Add "## Your Role" section |
| Weak constraints | "should" → "MUST" |

## Output Format

```markdown
## Agent Analysis: {name}
**File**: {path} | **Model**: {model} | **Tools**: {tools}

| Certainty | Count |
|-----------|-------|
| HIGH | {n} |
| MEDIUM | {n} |

### Issues
| Issue | Fix | Certainty |
```

## Pattern Statistics

| Category | Patterns | Certainty |
|----------|----------|-----------|
| Frontmatter | 5 | HIGH |
| Structure | 3 | HIGH |
| Instructions | 3 | HIGH |
| Tools | 4 | HIGH |
| Security | 2 | HIGH |
| Subagent | 3 | MEDIUM |
| XML/CoT/Examples | 4 | MEDIUM |
| Error/Loop | 3 | MEDIUM |
| Anti-Patterns | 3 | LOW |
| **Total** | **30** | - |

<examples>
### Unrestricted Bash
<bad_example>
```yaml
tools: Read, Bash
```
</bad_example>
<good_example>
```yaml
tools: Read, Bash(git:*), Bash(npm:test)
```
</good_example>

### Description Trigger
<bad_example>
```yaml
description: Reviews code
```
</bad_example>
<good_example>
```yaml
description: Reviews code for security. Use for PRs touching auth, API, data. Not for style.
```
</good_example>

### Model Selection
<bad_example>
```yaml
name: json-formatter
model: opus  # Overkill for mechanical task
```
</bad_example>
<good_example>
```yaml
name: json-formatter
model: haiku  # Simple, mechanical
```
</good_example>

### Constraint Language
<bad_example>
```markdown
- Try to validate inputs when possible
```
</bad_example>
<good_example>
```markdown
- MUST validate all inputs before processing
```
</good_example>

### Subagent Tools
<bad_example>
```yaml
context: fork
tools: Read, Glob, Task  # Task not allowed
```
</bad_example>
<good_example>
```yaml
context: fork
tools: Read, Glob, Grep
```
</good_example>
</examples>

## References

- `agent-docs/PROMPT-ENGINEERING-REFERENCE.md` - Instructions, XML, examples
- `agent-docs/CLAUDE-CODE-REFERENCE.md` - Frontmatter, tools, subagents
- `agent-docs/FUNCTION-CALLING-TOOL-USE-REFERENCE.md` - "Intern Test", security
- `agent-docs/OPENCODE-REFERENCE.md` - Modes, permissions
- `agent-docs/CODEX-REFERENCE.md` - Skill triggers

## Constraints

- Auto-fix only HIGH certainty issues
- Preserve existing frontmatter when adding fields
- Never remove content, only suggest improvements