agentsys 5.0.0

package/plugins/enhance/skills/enhance-prompts/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: enhance-prompts
+description: "Use when improving general prompts for structure, examples, and constraints."
+version: 5.0.0
+argument-hint: "[path] [--fix]"
+---
+
+# enhance-prompts
+
+Analyze prompts for clarity, structure, examples, and output reliability.
+
+## Parse Arguments
+
+```javascript
+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')`
+
+2. **Parse Results** - The analyzer returns JSON with `summary` and `findings`
+3. **Filter** - Apply certainty filtering based on --verbose flag
+4. **Report** - Format findings as markdown output
+5. **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:**
+```xml
+<system>
+You are [ROLE]. [PURPOSE].
+Key constraints: [CONSTRAINTS]
+Output format: [FORMAT]
+When uncertain: [HANDLING]
+</system>
+```
+
+### XML Tags (Claude-Specific)
+
+Claude is fine-tuned for XML tags. Use: `<role>`, `<constraints>`, `<output_format>`, `<examples>`, `<instructions>`, `<context>`
+
+```xml
+<constraints>
+- Maximum response length: 500 words
+- Use only Python 3.10+ syntax
+</constraints>
+```
+
+### 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
+
+```markdown
+## 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** |
+
+---
+
+<examples>
+### Example: Vague Instructions
+
+<bad_example>
+```markdown
+You should usually follow best practices when possible.
+```
+**Why it's bad**: Vague qualifiers reduce determinism.
+</bad_example>
+
+<good_example>
+```markdown
+Follow these practices:
+1. Validate input before processing
+2. Handle null/undefined explicitly
+```
+**Why it's good**: Specific, actionable instructions.
+</good_example>
+
+### Example: Negative-Only Constraints
+
+<bad_example>
+```markdown
+- Don't use vague language
+- Never skip validation
+```
+**Why it's bad**: Only states what NOT to do.
+</bad_example>
+
+<good_example>
+```markdown
+- Use specific, deterministic language
+- Always validate input; return structured errors
+```
+**Why it's good**: Each constraint includes positive action.
+</good_example>
+
+### Example: Redundant Chain-of-Thought
+
+<bad_example>
+```markdown
+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.
+</bad_example>
+
+<good_example>
+```markdown
+Analyze the input carefully before responding.
+```
+**Why it's good**: High-level guidance without micro-managing.
+</good_example>
+
+### Example: Missing Output Format
+
+<bad_example>
+```markdown
+Respond with a JSON object containing the analysis results.
+```
+**Why it's bad**: No schema or example.
+</bad_example>
+
+<good_example>
+```markdown
+## Output Format
+{"status": "success|error", "findings": [{"severity": "HIGH"}]}
+```
+**Why it's good**: Concrete schema shows exact structure.
+</good_example>
+
+### Example: Critical Info Buried
+
+<bad_example>
+```markdown
+# Task
+[task]
+## Background
+[500 words...]
+## Important Constraints  <- buried at end
+```
+**Why it's bad**: Lost-in-the-middle effect.
+</bad_example>
+
+<good_example>
+```markdown
+# Task
+## Critical Constraints  <- at start
+[constraints]
+## Background
+```
+**Why it's good**: Critical info at start where attention is highest.
+</good_example>
+</examples>
+
+---
+
+## Constraints
+
+- Only apply auto-fixes for HIGH certainty issues
+- Preserve original structure and formatting
+- Validate against embedded knowledge reference above