defluffisizer

messy draft in -> clear human copy out

Strip AI sounding fluff from docs, decks, PDFs, and notes while keeping the facts, the structure, and the strongest human signal. Works as an agent skill (Claude Code, Codex, Cursor, and any harness that reads project rules) and as a standalone CLI.

This repo packages defluffisizer in the same general shape as paper2code: a root README, a canonical skills/defluffisizer/ install path, stage based skill instructions, helper scripts, guardrails, knowledge files, and worked examples.

Why this exists

The problem: a lot of AI assisted writing is padded, abstract, over transitioned, and too even in tone, even when every fact in it checks out. It reads like a system trying to be helpful. It rarely reads like a person who means something specific.

What naive rewriting gets wrong: many tools just paraphrase the fluff. They swap one set of vague phrases for another, smooth over real tension, and sometimes delete facts to make the text shorter.

What defluffisizer does differently:

1. Starts from deletion, not paraphrase
2. Preserves facts, numbers, names, dates, and caveats
3. Restores human signal such as stakes, asymmetry, and chosen detail
4. Uses format aware workflows for decks, documents, PDFs, and text
5. Validates rewrites with a lint pass instead of trusting surface polish

Install

Install the skill straight from GitHub:

npx skills add p-tequila/defluffisizer/skills/defluffisizer

Or install the CLI globally from npm:

npm install -g defluffisizer

Usage

These are skill invocations for a skill aware agent (Claude Code, Codex, or Cursor), not raw shell commands. Ask the agent to run them, or type them if your harness treats a leading / as a skill trigger. For a harness with no native skill loader, paste skills/defluffisizer/prompts/append_system_prompt.txt in as its system prompt or project rules instead.

Full rewrite

/defluffisizer path/to/report.docx

Review only

/defluffisizer path/to/memo.md --mode review

Compress a long draft

/defluffisizer path/to/brief.pdf --mode compress

Retitle a slide deck

/defluffisizer path/to/deck.pptx --mode retitle

Generate a real rewritten PowerPoint

/defluffisizer path/to/deck.pptx --mode rewrite

Apply a prepared PowerPoint replacement map

/defluffisizer path/to/deck.pptx --mode apply_only

Rewrite a PDF and choose where the output goes

/defluffisizer path/to/report.pdf --output-dir ~/Desktop/clean

With no --output-dir, the output lands next to the source: path/to/report_defluffed.pdf (same format in, same format out; e.g. deck_defluffed.pptx for a .pptx source). PDF output is built from HTML via headless Chrome: plain rewritten text becomes a clean, simple page by default, or hand it a styled .html file as the rewritten content for a closer visual match to the source's design. Add --output-dir DIR to change only the directory, or name an exact file with --output DIR/name.ext.

What it can operate on

• .pptx — pure Python, no extra tools, works anywhere
• .txt, .md, .csv, .tsv — pure Python, no extra tools, works anywhere
• .doc, .docx, .odt, .rtf, .html — needs macOS's built-in textutil; no equivalent shipped for Linux or Windows yet
• .pdf — extraction needs pdftotext from poppler (brew install poppler on macOS, apt install poppler-utils on Debian/Ubuntu); writing a .pdf back out needs Google Chrome or Chromium installed, for headless rendering. Neither is bundled. Missing either fails with a clear error instead of silently doing nothing.

What you get

• rewritten copy in the original format when a writer exists
• extracted text or JSON when layout preserving writeback is not available
• optional lint output comparing before and after
• worked examples and review notes

What this skill will not do

• invent missing facts to make prose sound more human
• add fake informality, slang, or typos
• rewrite formulas or spreadsheet math unless asked
• claim layout preservation for formats where the writer does not exist yet

CLI

The npm package exposes a defluffisizer command:

defluffisizer prompt
defluffisizer probe path/to/file.pdf
defluffisizer extract path/to/deck.pptx --out editable.json

# writes path/to/deck_defluffed.pptx, next to the source, by default
defluffisizer apply path/to/deck.pptx editable.json

# --output-dir keeps the default name, changes the directory
defluffisizer apply path/to/deck.pptx editable.json --output-dir ~/Desktop/out

# --output overrides both name and directory
defluffisizer apply path/to/deck.pptx editable.json --output final/deck.pptx

defluffisizer lint --before before.txt --after after.txt