--- 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 You are... 1. Read 2. Analyze 3. Report - Only analyze, never modify ``` ### 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** | - | ### Unrestricted Bash ```yaml tools: Read, Bash ``` ```yaml tools: Read, Bash(git:*), Bash(npm:test) ``` ### Description Trigger ```yaml description: Reviews code ``` ```yaml description: Reviews code for security. Use for PRs touching auth, API, data. Not for style. ``` ### Model Selection ```yaml name: json-formatter model: opus # Overkill for mechanical task ``` ```yaml name: json-formatter model: haiku # Simple, mechanical ``` ### Constraint Language ```markdown - Try to validate inputs when possible ``` ```markdown - MUST validate all inputs before processing ``` ### Subagent Tools ```yaml context: fork tools: Read, Glob, Task # Task not allowed ``` ```yaml context: fork tools: Read, Glob, Grep ``` ## 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

enhance-agent-prompts

Scan your own AI components