fluff-detector

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

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

1. Attribution Signals

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

| Pattern | Example | Problem |

|---------|---------|---------|

| "Inspired by X" | "Inspired by DHH's approach" | LLM can't retrieve by author |

| "Based on X's methodology" | "Based on Martin Fowler's patterns" | Pure credibility signal |

| "According to X" | "According to industry experts" | Appeal to authority |

| "As recommended by" | "As recommended by Google" | No execution value |

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

Detection pattern:

```regex

(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.

| Pattern | Example |

|---------|---------|

| Epigraph quotes | "The best code is no code" - Someone |

| Philosophy | "In the spirit of simplicity..." |

| Motivation | "Great engineers always..." |

Detection pattern:

```regex

^>\s[""].[""].[-—]\s[A-Z]

[""][^""]{20,}[""][\s]*[-—]

```

3. Persona Fluff

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

| Pattern | Example | Better |

|---------|---------|--------|

| Identity statements | "You are a senior engineer" | (delete) |

| Capability claims | "You have deep expertise in..." | (delete) |

| Personality traits | "You are helpful and thorough" | (delete) |

| Self-reference | "As an AI assistant..." | (delete) |

Detection pattern:

```regex

^(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.

| Pattern | Example |

|---------|---------|

| Tool explanations | "The Read tool allows you to read files" |

| Obvious context | "This agent is used for..." |

| Meta-commentary | "The following section describes..." |

| Format explanations | "The output should be formatted as..." (when showing format) |

Detection pattern:

```regex

(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.

| Pattern | Example |

|---------|---------|

| Superlatives | "Best-in-class", "world-class", "cutting-edge" |

| Promises | "Ensures perfect results", "guarantees success" |

| Buzzwords | "Revolutionary", "game-changing", "next-gen" |

| Vague claims | "Highly efficient", "extremely powerful" |

Detection pattern:

```regex

(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.

| Pattern | Example | Better |

|---------|---------|--------|

| "Try to" | "Try to follow best practices" | "Follow best practices" |

| "Attempt to" | "Attempt to minimize errors" | "Minimize errors" |

| "Consider" | "Consider using X" | "Use X when Y" |

| "Maybe" | "Maybe add validation" | "Add validation if X" |

Detection pattern:

```regex

\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.

| Pattern | Delete |

|---------|--------|

| "It's important to note that" | ✓ |

| "Please keep in mind that" | ✓ |

| "It goes without saying" | ✓ |

| "Needless to say" | ✓ |

| "In order to" | Use "to" |

| "Due to the fact that" | Use "because" |

| "At this point in time" | Use "now" |

Detection pattern:

```regex

(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)

```

Validate Single File

```bash

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

```

Validate All Agents

```bash

for agent in plugins//agents//.md; do

./scripts/detect-fluff.sh "$agent"

done

```

CI Integration

```yaml

• 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

```

```

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

```

| Level | Action | Example |

|-------|--------|---------|

| ERROR | Must fix | Persona statements, marketing language |

| WARN | Should fix | Attribution, hedging, fillers |

| INFO | Consider | Redundant explanations (may be intentional) |

Some patterns have legitimate uses:

| Pattern | Legitimate Use |

|---------|----------------|

| "Based on" | "Based on user input" (not attribution) |

| "Consider" | In decision trees with conditions |

| Names | When defining a style (DHH, Warren Buffett) |

The script uses context analysis to reduce false positives.

| Code | Meaning |

|------|---------|

| 0 | No fluff detected |

| 1 | Warnings found (non-blocking) |

| 2 | Errors found (blocking) |