enhance-agent-prompts

# enhance-agent-prompts

Analyze agent prompt files for prompt engineering best practices.

## Agent File Locations

| Platform | Global | Project |
|----------|--------|---------|
| Claude Code | `~/.claude/agents/*.md` | `.claude/agents/*.md` |
| OpenCode | `~/.opencode/agents/*.md` | `.opencode/agent/*.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 impro