optimize-prompt - SKILL.md Agent Skill

name: optimize-prompt description: "Optimize Claude Code and LLM prompts for token efficiency, prefix caching compliance, positional recall, and execution correctness. Use when writing/reviewing prompts, debugging agent errors/failures, managing context windows, selecting effort levels, choosing MCP vs CLI tools, designing subagents, or editing CLAUDE.md. Triggers - optimize my prompt, prompt is too expensive, agent keeps reading wrong files, how should I structure this prompt, context window filling up, how to use Plan Mode, when to use subagents, MCP vs CLI, effort level, prompt structure, high-signal prompt, /clear vs /compact, CLAUDE.md best practices, audit prompt, review prompt, optimize skill, check caching, prompt design check, token usage, reduce tokens, optimize context, API costs, context window, prompt compression, token efficiency, cache strategy, LTL, symbolic language, caveman mode, hybrid caching, AtomicRAG, Claw Compactor."

Optimize Prompt & Review Skill

This skill provides workflow guidance and automated tooling to audit, analyze, compress, and optimize LLM prompts, instructions, and Claude Code environments for maximum token efficiency and reasoning accuracy.

Delineate prompts with XML tags, enforce append-only prefix caching alignment, select iterative effort levels, utilize symbolic abbreviations/protocols, and implement Prism Prompting constraints.

1. Quick Decision Tree

What do you need?
├── Fix a bug → Bug Triage Protocol (references/prompt-framework.md)
├── Add a feature → Incremental First-Step pattern (references/examples.md)
├── Explore large codebase → Subagent delegation (references/subagents-and-scaling.md)
├── Session is getting slow/expensive → Context hygiene (references/context-management.md)
├── Agent ignoring instructions → Context decay recovery (references/edge-cases.md)
├── Run Heuristic Auditor → Run python tool (scripts/audit_prompt.py)
├── Analyze Token Usage → Run python tool (scripts/analyze_token_usage.py)
└── Compress Prompt/Code → Run python tool (scripts/compress_prompt.py)

2. Quick Start Workflow

To analyze and optimize a prompt:

Run Automated Heuristic Audit: Execute the Python auditor on the prompt string, stdin, or file:
```
python scripts/audit_prompt.py <path/to/prompt.txt>
```
For SKILL.md files, the auditor validates:
- Frontmatter presence and structure (required --- markers)
- Required fields: name and description
- Proper YAML syntax (unquoted colons in values will trigger a failure)
- Name format (lowercase kebab-case)
Analyze Token/Session Cost: Analyze token distribution of files or conversation history files (.json):
```
python scripts/analyze_token_usage.py <path/to/prompt.txt_or_history.json>
```
Compress Prompt / Apply Shorthand: Compress prompt text by removing filler words, pleasantries (Caveman Mode), and optionally applying symbolic Less-Token-Language (LTL):
```
python scripts/compress_prompt.py <path/to/prompt.txt> --symbolic --caveman
```
Apply Automated Corrections: Use the --fix parameter to programmatically clean up politeness, persona placebo, and caching order:
```
python scripts/audit_prompt.py <path/to/prompt.txt> --fix <path/to/optimized_prompt.txt>
```
Validate Bounded Context: Ensure the prompt uses @file:line for targeting and !command for diagnostic output instead of prose.

3. Reference Documentation Index

For details on API configurations, token economics, and LLM constraints, read these references:

knowledge.md: Attention dilution, lost-in-the-middle positioning bias, prefix caching, and tokenization fertility.
examples.md: Copy-pasteable good/bad prompt layouts, Outlines CFGs, Pydantic AI models, Zod schemas, and vLLM/LMCache configurations.
prompt-framework.md: Five-pillar templates, bug triage protocols, XML tags, effort levels, context operators, and CLAUDE.md/MCP/commands structures.
context-management.md: Token budgets, slash commands (/clear, /compact), CLAUDE.md size rules, compaction, and session reset guidelines.
subagents-and-scaling.md: Subagent delegation config, horizontal project scaling, and MCP vs CLI token cost benchmarks.
edge-cases.md: Context decay symptoms, lossy compaction, and sync conflicts.
symbolic-languages.md: Mathematical operators, LTL (Less-Token-Language), Hieratic shorthand, Caveman protocol, and Wenyan-lang mode.
algorithmic-compression.md: Secondary model prompt compression (LLMLingua), Dynamic Memory Sparsification (DMS), and AST-aware Claw Compactor.
architectural-patterns.md: Core architectural patterns for token efficiency including AtomicRAG, Spine Architecture, Subagent Forking, and Modular Context Loading.
data-formats.md: Token density comparison across Markdown, YAML, JSON, XML, and TOON (Token-Oriented Object Notation).
caching-strategies.md: Ephemeral prefix caching, semantic caching with embeddings, VectorQ adaptive thresholds, and hybrid multi-layer caching.

Developers must use this schema to verify cache alignments and format outputs before execution.