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

~/.claude/agents/*.md

.claude/agents/*.md

~/.config/opencode/agents/*.md

.opencode/agents/*.md

~/.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)

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

Read, Glob, Grep

Read, Edit, Write, Glob, Grep

Bash(git:*)

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)

context: fork  # Isolated context for verbose output

• Subagents cannot spawn subagents (no

  Task

  in tools)
• Return summaries, not full output

Cross-platform modes:

mode: primary

mode: subagent

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

Bash

Bash(git:*)

Output Format

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

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

### Issues
| Issue | Fix | Certainty |

Pattern Statistics

Description Trigger

<bad_example>

description: Reviews code

</bad_example> <good_example>

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

</good_example>

Model Selection

<bad_example>

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

</bad_example> <good_example>

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

</good_example>

Constraint Language

<bad_example>

- Try to validate inputs when possible

</bad_example> <good_example>

- MUST validate all inputs before processing

</good_example>

Subagent Tools

<bad_example>

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

</bad_example> <good_example>

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