| name | fluff-detector |
| description | Detect human-oriented content in LLM artifacts. Flags attribution, personas, redundant explanations, marketing language, and decorative elements that waste tokens without improving LLM behavior. |
| allowed-tools | Bash Read Glob Grep |
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.
| 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:
(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:
^>\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:
^(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:
(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:
(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:
\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:
(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
| Level | Action | Example |
|---|
| ERROR | Must fix | Persona statements, marketing language |
| WARN | Should fix | Attribution, hedging, fillers |
| INFO | Consider | Redundant explanations (may be intentional) |
False Positive Handling
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.
Error Codes
| Code | Meaning |
|---|
| 0 | No fluff detected |
| 1 | Warnings found (non-blocking) |
| 2 | Errors found (blocking) |
