enhance-agent-prompts

Analyze agent prompt files for prompt engineering best practices.

Parse Arguments

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

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)

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

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

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)

context: fork  # Isolated context for verbose output

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

Cross-platform modes:

6. XML Structure (MEDIUM)

Use XML tags when 5+ sections, mixed lists/code, or multiple phases:

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

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

Output Format

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

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

### Issues
| Issue | Fix | Certainty |

Pattern Statistics

description: Reviews code

description: Reviews code for security. Use for PRs touching auth, API, data. Not for style.

name: json-formatter
model: opus  # Overkill for mechanical task

name: json-formatter
model: haiku  # Simple, mechanical

- Try to validate inputs when possible

- MUST validate all inputs before processing

context: fork
tools: Read, Glob, Task  # Task not allowed

context: fork
tools: Read, Glob, Grep