Enhance Prompts

enhance-prompts

Analyze prompts for clarity, structure, examples, and output reliability.

Parse Arguments

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');

Differentiation from enhance-agent-prompts

| Skill | Focus | Use When | |-------|-------|----------| | enhance-prompts | Prompt quality (clarity, structure, examples) | General prompts, system prompts, templates | | enhance-agent-prompts | Agent config (frontmatter, tools, model) | Agent files with YAML frontmatter |

Workflow

1. Run Analyzer - Execute the JavaScript analyzer to get findings:

``bash node -e "const a = require('./lib/enhance/prompt-analyzer.js'); console.log(JSON.stringify(a.analyzeAllPrompts('.'), null, 2));" ` For a specific path: a.analyzeAllPrompts('./plugins/enhance') For a single file: a.analyzePrompt('./path/to/file.md')`

1. Parse Results - The analyzer returns JSON with summary and findings
2. Filter - Apply certainty filtering based on --verbose flag
3. Report - Format findings as markdown output
4. Fix - If --fix flag, apply auto-fixes from findings

The JavaScript analyzer (lib/enhance/prompt-analyzer.js) implements all detection patterns including AST-based code validation. The patterns below are reference documentation.

---

Prompt Engineering Knowledge Reference

System Prompt Structure

Effective system prompts include: Role/Identity, Capabilities & Constraints, Instruction Priority, Output Format, Behavioral Directives, Examples, Error Handling.

Minimal Template:

You are [ROLE]. [PURPOSE].
Key constraints: [CONSTRAINTS]
Output format: [FORMAT]
When uncertain: [HANDLING]

XML Tags (Claude-Specific)

Claude is fine-tuned for XML tags. Use: `, , , , , `

- Maximum response length: 500 words
- Use only Python 3.10+ syntax

Few-Shot Examples

• 2-5 examples is optimal (research-backed)
• Include edge cases and ensure format consistency
• Start zero-shot, add examples only if needed
• Show both good AND bad examples when relevant

Chain-of-Thought (CoT)

| Use CoT | Don't Use CoT | |---------|---------------| | Complex multi-step reasoning | Simple factual questions | | Math and logic problems | Classification tasks | | Code debugging | When model has built-in reasoning |

Key: Modern models (Claude 4.x, o1/o3) perform CoT internally. "Think step by step" is redundant.

Role Prompting

Helps: Creative tasks, tone/style, roleplay Doesn't help: Accuracy tasks, factual retrieval, complex reasoning

Better: "Approach systematically, showing work" vs "You are an expert"

Instruction Hierarchy

Priority: System > Developer > User > Retrieved Content

Include explicit priority in prompts with multiple constraint sources.

Negative Prompting

Positive alternatives are more effective than negatives:

| Less Effective | More Effective | |----------------|----------------| | "Don't use markdown" | "Use prose paragraphs" | | "Don't be vague" | "Use specific language" |

Structured Output

• Prompt-based: ~35.9% reliability
• Schema enforcement: 100% reliability
• Always provide schema example and validate output

Context Window Optimization

Lost-in-the-Middle: Models weigh beginning and end more heavily.

Place critical constraints at start, examples in middle, error handling at end.

Extended Thinking

High-level instructions ("Think deeply") outperform step-by-step guidance. "Think step-by-step" is redundant with modern models.

Anti-Patterns Quick Reference

| Anti-Pattern | Problem | Fix | |--------------|---------|-----| | Vague references | "The above code" loses context | Quote specifically | | Negative-only | "Don't do X" without alternative | State what TO do | | Aggressive emphasis | "CRITICAL: MUST" | Use normal language | | Redundant CoT | Wastes tokens | Let model manage | | Critical info buried | Lost-in-the-middle | Place at start/end |

---

Detection Patterns

1. Clarity Issues (HIGH Certainty)

Vague Instructions: "usually", "sometimes", "try to", "if possible", "might", "could"

Negative-Only Constraints: "don't", "never", "avoid" without stating what TO do

Aggressive Emphasis: Excessive CAPS (CRITICAL, IMPORTANT), multiple !!

2. Structure Issues (HIGH/MEDIUM Certainty)

Missing XML Structure: Complex prompts (>800 tokens) without XML tags

Inconsistent Sections: Mixed heading styles, skipped levels (H1→H3)

Critical Info Buried: Important instructions in middle 40%, constraints after examples

3. Example Issues (HIGH/MEDIUM Certainty)

Missing Examples: Complex tasks without few-shot, format requests without example

Suboptimal Count: Only 1 example (optimal: 2-5), more than 7 (bloat)

Missing Contrast: No good/bad labeling, no edge cases

4. Context Issues (MEDIUM Certainty)

Missing WHY: Rules without explanation

Missing Priority: Multiple constraint sections without conflict resolution

5. Output Format Issues (HIGH/MEDIUM Certainty)

Missing Format: Substantial prompts without format specification

JSON Without Schema: Requests JSON but no example structure

6. Anti-Patterns (HIGH/MEDIUM/LOW Certainty)

Redundant CoT (HIGH): "Think step by step" with modern models

Overly Prescriptive (MEDIUM): 10+ numbered steps, micro-managing reasoning

Prompt Bloat (LOW): Over 2500 tokens, redundant instructions

Vague References (HIGH): "The above code", "as mentioned"

---

Auto-Fix Implementations

1. Aggressive Emphasis

Replace CRITICAL→critical, !!→!, remove excessive caps

2. Negative-Only to Positive

Suggest positive alternatives for "don't" statements

---

Output Format

## Prompt Analysis: {prompt-name}

**File**: {path}
**Type**: {system|agent|skill|template}
**Token Count**: ~{tokens}

### Summary
- HIGH: {count} issues
- MEDIUM: {count} issues

### Clarity Issues ({n})
| Issue | Location | Fix | Certainty |

### Structure Issues ({n})
| Issue | Location | Fix | Certainty |

### Example Issues ({n})
| Issue | Location | Fix | Certainty |

---

Pattern Statistics

| Category | Patterns | Auto-Fixable | |----------|----------|--------------| | Clarity | 4 | 1 | | Structure | 4 | 0 | | Examples | 4 | 0 | | Context | 2 | 0 | | Output Format | 3 | 0 | | Anti-Pattern | 4 | 0 | | Total | 21 | 1 |

---

Example: Vague Instructions

You should usually follow best practices when possible.

Why it's bad: Vague qualifiers reduce determinism.

Follow these practices:
1. Validate input before processing
2. Handle null/undefined explicitly

Why it's good: Specific, actionable instructions.

Example: Negative-Only Constraints

- Don't use vague language
- Never skip validation

Why it's bad: Only states what NOT to do.

- Use specific, deterministic language
- Always validate input; return structured errors

Why it's good: Each constraint includes positive action.

Example: Redundant Chain-of-Thought

Think through this step by step:
1. First, analyze the input
2. Then, identify the key elements

Why it's bad: Modern models do this internally. Wastes tokens.

Analyze the input carefully before responding.

Why it's good: High-level guidance without micro-managing.

Example: Missing Output Format

Respond with a JSON object containing the analysis results.

Why it's bad: No schema or example.

## Output Format
{"status": "success|error", "findings": [{"severity": "HIGH"}]}

Why it's good: Concrete schema shows exact structure.

Example: Critical Info Buried

# Task
[task]
## Background
[500 words...]
## Important Constraints  

```markdown
# Task
## Critical Constraints  

---

## Constraints

- Only apply auto-fixes for HIGH certainty issues
- Preserve original structure and formatting
- Validate against embedded knowledge reference above

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [agent-sh](https://github.com/agent-sh)
- **Source:** [agent-sh/agentsys](https://github.com/agent-sh/agentsys)
- **License:** MIT
- **Homepage:** https://agent-sh.github.io/agentsys/

Install and usage instructions live in the source repository linked above.