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