agentsys system prompt

--- name: enhance-prompts description: "Use when improving general prompts for structure, examples, and constraints." version: 5.1.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

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