clean-prose

Rewrites markdown, comments, and identifiers to remove filler, coined terms, and restatement.

Updated Jun 30, 2026
One-click install
npx skills add https://github.com/bsamiee/Rasm --skill clean-prose-bsamiee
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: clean-prose
Source: https://github.com/bsamiee/Rasm/tree/main/.claude/skills/clean-prose
Command: npx skills add https://github.com/bsamiee/Rasm --skill clean-prose-bsamiee

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires msgspec, regex, wcwidth, and includes scripts (resource) and references (resource) components.

What problem does it solve? Project documentation, comments, and messages accumulate filler words, coined metaphors, restated facts, and inconsistent structure that obscure meaning and inflate files. This Skill enforces a deterministic house style so every sentence states one fact in its owning section. ## Core Features & Use Cases - Terminology enforcement: Replaces coined terms (ship, payload, strata) with real vocabulary from current language and tool documentation, and renames identifiers through language tooling. - Structural rewriting: Deletes connectives, hedges, and restatements, rebuilds joined sentences, and normalizes headings, tables, lists, and comments to one fact per line. - Deterministic checking: Ships a Python script (prose.py check|fix) that lexes markdown and source comments into blocks, applies mechanical fixes, and reports findings as path:line: message. - Use Case: Before committing a README rewrite, run the check command over the docs directory to list every fixable block and remaining finding, then run fix to write the mechanical corrections. ## Quick Start Ask the agent to review and rewrite the markdown files in your docs folder using the clean-prose rules, then run the prose script's check command to verify compliance.

Frequently Asked Questions about clean-prose

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check markdown files for style violations?▼

Run `uv run --script scripts/prose.py check <path>...` to print one finding per line as `path:line: message`, plus a count of fixable blocks. Run the same command with `fix` to write the mechanical corrections and list what remains.

How to remove filler words from technical documentation?▼

Delete words in the word map's deletion categories (hedges, intensifiers, connectives, meta phrases) and reread the sentence; keep the remainder when nothing of value is lost. Replacement rows substitute plainer verbs like use, start, and stop.

What file types does the prose checker support?▼

The script lints markdown files and comments in Python, shell, TOML, Nix, YAML, TypeScript, C#, JSONC, SQL, and Lua sources. It lexes each file into blocks such as headings, tables, entries, dividers, and comments before applying rules.

Does the fix command change code or only comments?▼

The script rewrites only text spans in markdown blocks and comment or divider lines in source files; code blocks stay untouched. Identifier renames in code go through language tooling separately so every reference, test, and file name updates.

Why does the checker report lines it cannot fix automatically?▼

Reports cover judgments a mechanical transform cannot make, such as dead relative links, articles opening sentences, enumeration words counting visible items, and dividers repeating or opening empty sections. A reader decides each reported line by hand.