Prompt Brevity Review

Prompt Brevity Review

Overview

AI prompts (skills, CLAUDE.md files, slash commands) are consumed by language models with token limits. Verbose prompts waste context window space and reduce comprehension. This skill identifies unnecessary verbosity and suggests concise alternatives while preserving essential information and clarity.

When to Use

• Reviewing new or updated skill files (.claude/skills/)
• Evaluating CLAUDE.md project instructions
• Assessing slash command prompts (.claude/commands/)
• Auditing system prompts or agent instructions
• Optimizing prompt performance and token usage

Process

1. Identify Core Information

Extract the essential message:

• What: What is the instruction or knowledge?
• When: When should it be applied?
• How: How should it be executed?
• Why: Why does this matter? (optional, only if critical)

2. Detect Verbosity Patterns

Common bloat indicators:

Redundancy

• Restating the same point multiple times
• Overlapping examples that demonstrate the same concept
• Repetitive phrasing across sections

Fluff Words

• "It's important to note that..."
• "You should definitely make sure to..."
• "Please be aware that..."
• "Keep in mind that..."

Over-Explanation

• Explaining obvious concepts
• Excessive background context
• Unnecessary justifications

Ceremonial Language

• "In order to" → "To"
• "Due to the fact that" → "Because"
• "At this point in time" → "Now"

3. Apply Brevity Techniques

Use Active Voice

• ❌ "The file should be read by the agent"
• ✅ "Read the file"

Remove Hedge Words

• ❌ "Generally, you might want to consider using..."
• ✅ "Use..."

Use Direct Commands

• ❌ "You should try to validate the input"
• ✅ "Validate the input"

Eliminate Redundant Qualifiers

• ❌ "Completely eliminate all unnecessary words"
• ✅ "Eliminate unnecessary words"

Convert Prose to Lists

• ❌ Paragraph explaining multiple steps
• ✅ Numbered or bulleted list

Use Concrete Examples Over Abstract Explanation

• ❌ "When dealing with situations where authentication might be compromised..."
• ✅ "Example: SQL injection in login form"

4. Preserve Critical Information

Don't remove:

• Specificity: Exact file paths, commands, patterns
• Disambiguation: Clarifications that prevent misinterpretation
• Context boundaries: When/when not to apply the skill
• Edge cases: Important exceptions or caveats
• Examples: Concrete demonstrations (if not redundant)

5. Measure Impact

Calculate improvement:

• Token reduction: Count before/after tokens (rough: 4 chars = 1 token)
• Clarity gain: Is the message clearer or more ambiguous?
• Information loss: Did we remove anything essential?
• Target: 30-50% token reduction without information loss

Examples

Example 1: Verbose Skill Introduction

Before (92 tokens):

## Overview

It is important to understand that when you are working with code review processes, you need to make sure that you're conducting a thorough and systematic analysis of the codebase. This skill will help you learn how to effectively review code by providing you with a structured approach that you can follow in order to ensure that you don't miss any important issues or concerns that might exist in the code being reviewed.

After (28 tokens):

## Overview

Conduct systematic code reviews using a structured approach to catch issues and improve code quality.

Improvement: 70% token reduction, message is clearer and more actionable

Example 2: Over-Explained Process Step

Before (68 tokens):

1. First, you should make sure to carefully read through the pull request description so that you can get a good understanding of what the developer was trying to accomplish with their changes. It's really important that you take the time to understand the context before you start looking at the actual code changes themselves.

After (15 tokens):

1. Read PR description to understand change goals and context

Improvement: 78% token reduction, action is clear

Example 3: Redundant Examples

Before (145 tokens):

## Examples

Here are some examples of how to use this skill:

- Example 1: You can use this when reviewing a pull request that adds new features
- Example 2: You might want to use this when examining code that fixes bugs
- Example 3: This is useful when looking at refactoring changes
- Example 4: You could apply this when checking security updates
- Example 5: This works well for performance optimization reviews

After (31 tokens):

## Examples

Use when reviewing:
- New features
- Bug fixes
- Refactoring
- Security updates
- Performance optimizations

Improvement: 79% token reduction, same information preserved

Example 4: Fluff-Heavy Instruction

Before (47 tokens):

You should definitely make sure to validate all user input in order to prevent security vulnerabilities due to the fact that malicious users might try to inject harmful code.

After (13 tokens):

Validate all user input to prevent injection attacks.

Improvement: 72% token reduction, more direct

Anti-patterns

• ❌ Don't: Remove necessary context that prevents misinterpretation

  • ✅ Do: Remove only redundant or obvious information

• ❌ Don't: Make prose cryptic by over-abbreviating

  • ✅ Do: Use clear, direct language that's still readable

• ❌ Don't: Cut concrete examples that demonstrate concepts

  • ✅ Do: Cut redundant examples that show the same pattern

• ❌ Don't: Remove edge cases and important exceptions

  • ✅ Do: State exceptions concisely (e.g., "Except when X, then Y")

• ❌ Don't: Strip personality from prompts entirely

  • ✅ Do: Keep minimal tone/personality that aids comprehension

Brevity Checklist

Use this checklist when reviewing prompts:

• Remove "it's important to note", "please be aware", "keep in mind"
• Convert passive voice to active voice
• Replace "in order to" with "to"
• Remove hedge words ("generally", "typically", "usually")
• Eliminate redundant qualifiers ("completely", "totally", "very")
• Convert paragraph explanations to lists
• Combine overlapping examples
• Remove obvious explanations
• Replace verbose phrases with concise alternatives
• Verify all specific details (paths, commands) are preserved

Testing This Skill

Test Scenario 1: Skill File Review

1. Read an existing skill file from .claude/skills/
2. Apply brevity techniques to each section
3. Calculate token reduction percentage
4. Success: 30%+ reduction with no information loss

Test Scenario 2: CLAUDE.md Optimization

1. Review project CLAUDE.md instructions
2. Identify verbose sections
3. Suggest concise alternatives
4. Success: Clearer instructions in fewer tokens

Test Scenario 3: Command Prompt Review

1. Examine a slash command prompt
2. Apply brevity checklist
3. Verify command still functions correctly
4. Success: Faster execution with maintained accuracy

Common Verbose → Concise Patterns

Related Skills

• creating-skills - Creating well-structured skills from the start
• code-review - Reviewing code for similar clarity issues
• writing-commit-messages - Concise, information-dense writing

Remember: Every token counts. Clear and concise beats verbose and redundant.