content-optimization

Content Optimization Skill

Purpose

Systematically enhance any type of content using research-backed techniques and best practices. This skill:

• Automatically detects content type
• Applies domain-specific optimization techniques
• Provides step-by-step approval workflow (especially for prompts)
• Measures improvement with confidence scores
• Supports multiple optimization modes (conservative, moderate, aggressive)

When to Use

• AI Prompts: Improve clarity, add reasoning chains, optimize for better responses
• Code: Refactor for performance, readability, error handling
• Database Queries: Optimize performance, suggest indexes, enable caching
• Commit Messages: Clarify intent, follow conventional format
• Documentation: Improve structure, add examples, enhance clarity
• Communication: Refine tone, improve call-to-action, enhance effectiveness

The Problem

Without systematic optimization:

• Prompts to AI models are vague, leading to poor responses
• Code is written without considering performance
• Database queries are inefficient, causing slowdowns
• Commit messages lack clarity about changes
• Documentation is unclear for readers
• Communications miss the mark

With this skill:

• Prompts generate 45-115% better responses (research-backed)
• Code is performant and maintainable
• Queries execute faster with proper indexes
• Commit history is clear and navigable
• Documentation is clear and helpful
• Communications are more effective

Supported Content Types

Type	Purpose	Techniques
prompt	AI prompt optimization	Expert personas, step-by-step reasoning, stakes language, challenge framing
code	Source code improvement	Performance, readability, error handling, best practices
query	Database/search query	Indexes, execution plans, caching, pagination
commit	Git commit messages	Conventional commits, clarity, intent description
docs	Documentation	Structure, examples, clarity, accessibility
email	Communication	Tone, clarity, call-to-action, effectiveness

Prompt Optimization Techniques

1. Expert Persona Assignment

Assigns detailed expert role with relevant background.

Instead of: "Help me debug this"
Optimized: "As a senior backend engineer with 10 years of experience debugging distributed systems..."

Impact: +60% accuracy (Kong et al., 2023)

2. Step-by-Step Reasoning

Instructs systematic analysis approach.

"Take a deep breath and think step by step. First, identify the symptoms..."

Impact: +46% accuracy (Yang et al., 2023)

3. Stakes Language

Frames importance and consequences.

"This is critical for production. Incorrect analysis could cause service outage."

Impact: +45% quality (Bsharat et al., 2023)

4. Challenge Framing

Positions as difficult problem worth solving.

"This is a tricky optimization problem. I bet you can't find the perfect balance."

Impact: +115% on hard tasks (Li et al., 2023)

5. Self-Evaluation

Requests confidence ratings and uncertainty identification.

"Rate your confidence in this solution (0.0-1.0) and identify any uncertainties."

Impact: +10% calibration

Usage Examples

Optimize AI Prompts

/optimize "Help me debug auth" --prompt
# Interactive approval workflow:
# - Shows detected domain (security)
# - Suggests optimization steps
# - Asks approve/reject/modify for each step
# - Calculates expected improvement

/optimize "Help me debug auth" --prompt --verbose
# Detailed walkthrough with reasoning for each optimization

/optimize "Help me debug auth" --prompt --mode=aggressive
# Apply maximum optimization (more aggressive than default)

/optimize "Help me debug auth" --prompt --mode=conservative
# Minimal changes, preserve original intent

# Skip optimization
/optimize "! Help me debug auth" --prompt
# Exclamation mark prefix bypasses optimization

Optimize Source Code

/optimize src/auth.js --code
# Suggests: performance improvements, readability, error handling

/optimize src/auth.js --code --preview
# Show changes before applying

/optimize src/auth.js --code --apply
# Automatically apply optimizations

/optimize src/auth.js --code --mode=aggressive
# Maximum optimization (may add complexity)

Optimize Database Queries

/optimize "SELECT * FROM users WHERE status = 'active'" --query
# Suggests: add indexes, pagination, caching, execution plan

/optimize "SELECT * FROM users WHERE status = 'active'" --query --preview
# Preview query optimization without applying

Optimize Commit Messages

/optimize "fix: resolve login bug" --commit
# Suggests: add scope, detail, follow conventional commits

/optimize "fix: resolve login bug" --commit --apply
# Apply optimized message

Optimize Documentation

/optimize "README.md" --docs
# Suggests: structure improvements, add examples, clarify sections

/optimize "README.md" --docs --interactive
# Ask clarifying questions about audience and purpose

Optimize Communication

/optimize "Hey, can you review my code?" --email
# Suggests: professional tone, clear request, timeline

/optimize "Hey, can you review my code?" --email --apply
# Apply professional version

Auto-Detect Content Type

/optimize "help me optimize this database query"
# Automatically detects as prompt, applies optimization
# (Or specify --type if auto-detection fails)

Options

Option	Description	Values	Default
--type <type>	Content type	prompt/code/query/commit/docs/email	auto
--mode <mode>	Optimization intensity	conservative/moderate/aggressive	moderate
--preview	Show changes before applying	flag	false
--apply	Apply optimizations automatically	flag	false
--interactive	Ask clarifying questions	flag	false
--verbose	Show detailed process	flag	false
--force	Apply without confirmation	flag	false
--output <file>	Save to file instead of stdout	path	stdout
--source <sources>	Research sources	anthropic/openai/opencode/all	all

Interactive Approval Workflow (Prompts)

When optimizing prompts, you get step-by-step approval:

Step 1: Analysis

Domain detected: Security (authentication/debugging)
Complexity: Medium (moderate ambiguity)
Suggested techniques:
  ✓ Expert Persona (security engineer with 10yr exp)
  ✓ Step-by-Step Reasoning (systematic debugging approach)
  ✓ Stakes Language (production impact)
  ✓ Self-Evaluation (confidence rating)

Step 2: Approval

For each technique, choose:
  [A] Approve     - Use this technique
  [R] Reject      - Skip this technique
  [M] Modify      - Change the wording
  [E] Edit        - Full edit mode
  [C] Cancel      - Don't optimize

Step 3: Result

Original: "Help me debug auth"

Optimized: "As a senior security engineer with 10 years of experience 
debugging distributed authentication systems, help me systematically 
debug this login issue. This is production-critical - incorrect analysis 
could cause service outage. Walk through your reasoning step by step. 
Rate your confidence (0.0-1.0) and identify any uncertainties."

Expected improvement: +78% response quality
Confidence: 0.92

Code Optimization Techniques

• Performance: Reduce complexity, optimize algorithms, cache results
• Readability: Better variable names, extract functions, add comments
• Error Handling: Add try-catch, validate inputs, handle edge cases
• Best Practices: Follow language conventions, use idioms, avoid antipatterns

Query Optimization Techniques

• Indexes: Suggest missing indexes on WHERE/JOIN columns
• Execution Plans: Show query plan analysis and bottlenecks
• Pagination: Add LIMIT/OFFSET for large result sets
• Caching: Identify cacheable queries
• Joins: Optimize join strategies and order

Quality Metrics

After optimization, receive:

Metric	Range	Interpretation
Improvement Score	0-100	Expected % improvement
Confidence	0-1.0	Certainty in optimization
Risk Level	Low/Medium/High	Potential for introducing issues
Estimated Impact	Brief	What users will notice

Configuration

Conservative Mode

• Minimal changes to original
• Preserve original intent strongly
• Lower risk of side effects
• Useful when preserving style is important

Moderate Mode (Default)

• Balance improvement with preservation
• Standard optimization techniques
• Medium risk, good reward
• Recommended for most cases

Aggressive Mode

• Maximum optimization
• May add significant complexity
• Higher risk of unintended changes
• Useful for exploratory optimization

Step-by-Step Process

Phase 1: Analysis

1. Detect content type (or use specified type)
2. Assess current quality
3. Identify improvement opportunities
4. Plan optimization approach

Phase 2: Optimization (varies by type)

For Prompts:

• Analyze domain and complexity
• Select applicable techniques
• Generate optimization plan
• Present for interactive approval

For Code/Queries/Docs/Etc:

• Apply domain-specific techniques
• Generate optimized version
• Show before/after comparison
• Ask for approval (or auto-apply if --apply flag)

Phase 3: Review & Feedback

• Show improvement metrics
• Identify any risks
• Offer refinements
• Save optimized version

Integration with Other Skills

This skill wraps and extends:

• incentive-prompting: Core prompt optimization techniques
• prompt-refinement: For clarifying vague prompts before optimizing

Used together:

1. Use prompt-refinement to clarify intent (Phase 0)
2. Use content-optimization to enhance (Phase 1)
3. Execute optimized content (Phase 2)

Error Handling

Simple Prompts (auto-skip)

Prompt detected: "debug auth"
Simplicity: Very high (2 words, clear intent)
Action: Skip optimization, proceed with original

Unclear Content Type (ask for help)

Content type unclear. Assume:
  [P] Prompt
  [C] Code
  [Q] Query
  [D] Docs
  [E] Email
Select type [P/C/Q/D/E]:

Unsafe Changes (flag for review)

⚠️  Warning: Proposed changes remove error handling
    Original: try { ... } catch { ... }
    Optimized: ... (no error handling)
    Action: Proceed? [Y/N]

Success Metrics

After using this skill:

• ✓ Prompts generate 45-115% better responses
• ✓ Code is more performant and readable
• ✓ Queries execute faster
• ✓ Commit history is clearer
• ✓ Documentation is more helpful
• ✓ Communications are more effective

Common Use Cases

Before Code Review

/optimize src/newfeature.js --code --preview
# Preview improvements before submitting PR

Before Shipping

/optimize "SELECT users FROM..." --query --apply
# Ensure queries are optimized before production

Onboarding Documentation

/optimize "README.md" --docs --interactive
# Get suggestions specific to new team members

Prompt Experimentation

/optimize "help me" --prompt --verbose --mode=aggressive
# See aggressive techniques to learn from

Tips & Tricks

1. Preview first: Use --preview before --apply to review changes
2. Start conservative: Try --mode=conservative to see minimal changes
3. Be specific: More specific prompts yield better optimizations
4. Ask interactively: Use --interactive to guide optimization
5. Chain with refinement: Use prompt-refinement skill first, then optimize
6. Learn from aggressive: See --mode=aggressive output to understand patterns

Confidence in Optimization

How to interpret confidence scores:

• 0.9-1.0: Very confident, safe to apply automatically
• 0.7-0.9: Confident, review before applying
• 0.5-0.7: Somewhat confident, test thoroughly
• 0.0-0.5: Low confidence, manual review required

When to Avoid

• Unique styles: If code style is intentionally different
• Performance-critical paths: Review aggressive optimizations carefully
• Legal/compliance text: Don't optimize without domain expert review
• Tested algorithms: Don't change working code without good reason

Advanced: Custom Optimization

For power users, extend with custom techniques:

• Reference research papers for inspiration
• Add domain-specific patterns
• Create team optimization standards
• Share optimized templates

This skill provides the framework; you customize the techniques.

Anti-Rationalization Table

Excuse	Counter
"The original is fine, no need to optimize"	Good enough is the enemy of great. Systematic optimization catches missed opportunities.
"Aggressive optimization changes too much"	Conservative mode exists for a reason. Start gentle, increase aggressiveness as needed.
"I'll optimize after the first draft"	Optimization during creation prevents compounding bad patterns.
"The confidence score is high enough"	High confidence does not mean perfect. Review before applying any optimization.
"This content type doesn't need optimization"	Every content type has domain-specific improvements. Apply the right techniques.