Fluff Detector

Fluff Detector

Purpose

Verify that agents, commands, and skills are written for LLM consumption, not human readers. Every token should improve execution, not provide comfort or credibility.

When to Use

• Creating new agents, commands, or skills
• Reviewing PRs that add/​modify LLM artifacts
• Quality gate before merge
• Auditing existing artifacts for token waste

Fluff Categories

1. Attribution Signals

Content that establishes credibility for humans but has no LLM value.

Exception: Names that define a style (e.g., "DHH-style Rails") are functional, not attribution.

Detection pattern:

(inspired by|based on|according to|as recommended by|following|using|applying)\s+[A-Z][a-z]+('s)?

2. Decorative Quotes

Inspirational or philosophical quotes that add no functional value.

Detection pattern:

^>\s*[""].*[""].*[-—]\s*[A-Z]
[""][^""]{20,}[""][\s]*[-—]

3. Persona Fluff

Role descriptions that tell the LLM what it "is" instead of what to do.

Detection pattern:

^(You are|As an?|I am|Acting as)\s+(a |an |the )?[a-z]+(ly)?\s+(and\s+[a-z]+\s+)?

4. Redundant Explanations

Explaining what LLMs already know or can infer.

Detection pattern:

(this (agent|skill|command) (is used|helps|allows|enables))
(the following (section|content|instructions))
(as (shown|described|mentioned) (above|below|previously))

5. Marketing Language

Promotional or sales-oriented language inappropriate for LLM instructions.

Detection pattern:

(best-in-class|world-class|cutting-edge|state-of-the-art|revolutionary|game-chang|next-gen|highly efficient|extremely powerful|ensures? (perfect|optimal)|guarantee)

6. Hedging Language

Uncertainty markers that add no value.

Detection pattern:

\b(try to|attempt to|consider\s+(using|adding|implementing)|you (might|may|could) want to|perhaps|maybe)\b

7. Filler Phrases

Zero-information phrases that pad content.

Detection pattern:

(it('s| is) (important|worth|crucial) to (note|mention|remember)|please (keep in mind|note|remember)|goes without saying|needless to say|in order to|due to the fact|at this point in time|as a matter of fact|for all intents and purposes)

Usage

Validate Single File

./​scripts/​detect-fluff.sh path/​to/​file.md

Validate All Agents

for agent in plugins/​*/​agents/​**/​*.md; do
  ./​scripts/​detect-fluff.sh "$agent"
done

CI Integration

- name: Detect Fluff
  run: |
    find plugins -name "*.md" -path "*/​agents/​*" -o -name "*.md" -path "*/​skills/​*" -o -name "*.md" -path "*/​commands/​*" | while read f; do
      .claude/​skills/​fluff-detector/​scripts/​detect-fluff.sh "$f" || exit 1
    done

Output Format

Analyzing: plugins/​majestic-engineer/​agents/​qa/​test-reviewer.md

[WARN] Line 12: Attribution signal
  > "Based on Kent Beck's TDD principles"
  Suggestion: Remove attribution or rephrase as pattern name

[WARN] Line 45: Persona fluff
  > "You are an expert test reviewer with deep knowledge"
  Suggestion: Delete - LLM doesn't need identity statements

[WARN] Line 78: Filler phrase
  > "It's important to note that tests should be isolated"
  Suggestion: "Tests should be isolated"

Summary: 3 fluff instances found

Severity Levels

False Positive Handling

Some patterns have legitimate uses:

The script uses context analysis to reduce false positives.

Error Codes