// Use when improving agent prompts, frontmatter, and tool restrictions.
Use when coordinating multiple enhancers for /enhance command. Runs analyzers in parallel and produces unified report.
Use when improving CLAUDE.md or AGENTS.md project memory files.
Use when checking cross-file consistency: tools vs frontmatter, agent references, duplicate rules, contradictions.
Use when improving documentation structure, accuracy, and RAG readiness.
Use when reviewing hooks for safety, timeouts, and correct frontmatter.
Use when analyzing plugin structures, MCP tools, and plugin security patterns.
| name | enhance-agent-prompts |
| description | Use when improving agent prompts, frontmatter, and tool restrictions. |
| version | 5.1.0 |
| argument-hint | [path] [--fix] [--verbose] |
Analyze agent prompt files for prompt engineering best practices.
const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');
const verbose = args.includes('--verbose');
| Platform | Global | Project |
|---|---|---|
| Claude Code | ~/.claude/agents/*.md | .claude/agents/*.md |
| OpenCode | ~/.config/opencode/agents/*.md | .opencode/agents/*.md |
| Codex | ~/.codex/skills/ | AGENTS.md |
---
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:
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.
Required sections: Role ("You are..."), Output format, Constraints
Position-aware order (LLMs recall START/END better than MIDDLE):
Positive over negative:
Strong constraint language:
Include WHY for important rules - motivation improves compliance.
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 subagents20 tools → increases error rates ("Less-is-More")
context: fork # Isolated context for verbose output
Task in tools)Cross-platform modes:
| Platform | Primary | Subagent |
|---|---|---|
| Claude Code | Default | Via Task tool |
| OpenCode | mode: primary | mode: subagent |
| Codex | Skills | MCP server |
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>
Unnecessary: Simple tasks (<500 words), single-step, mechanical Missing: Complex analysis (>1000 words), multi-step reasoning, "analyze/evaluate/assess"
Optimal: 2-5 examples. <2 insufficient, >5 token bloat.
For iterating agents: max iterations, completion criteria, escape conditions.
## Error Handling
- Transient errors: retry up to 3 times
- Validation errors: report, do not retry
- Tool failure: try alternative before failing
Bash + user params: validate inputs| Issue | Fix |
|---|---|
| Missing frontmatter | Add name, description, tools, model |
| Unrestricted Bash | Bash → Bash(git:*) |
| Missing role | Add "## Your Role" section |
| Weak constraints | "should" → "MUST" |
## Agent Analysis: {name}
**File**: {path} | **Model**: {model} | **Tools**: {tools}
| Certainty | Count |
|-----------|-------|
| HIGH | {n} |
| MEDIUM | {n} |
### Issues
| Issue | Fix | Certainty |
| 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 | - |
<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>
<bad_example>
name: json-formatter
model: opus # Overkill for mechanical task
</bad_example> <good_example>
name: json-formatter
model: haiku # Simple, mechanical
</good_example>
<bad_example>
- Try to validate inputs when possible
</bad_example> <good_example>
- MUST validate all inputs before processing
</good_example>
<bad_example>
context: fork
tools: Read, Glob, Task # Task not allowed
</bad_example> <good_example>
context: fork
tools: Read, Glob, Grep
</good_example>
agent-docs/PROMPT-ENGINEERING-REFERENCE.md - Instructions, XML, examplesagent-docs/CLAUDE-CODE-REFERENCE.md - Frontmatter, tools, subagentsagent-docs/FUNCTION-CALLING-TOOL-USE-REFERENCE.md - "Intern Test", securityagent-docs/OPENCODE-REFERENCE.md - Modes, permissionsagent-docs/CODEX-REFERENCE.md - Skill triggers