Prose Editing skill for Claude Code

#!/usr/bin/env python3
"""Flag common prose problems in Markdown or plain text. Standard library only.

Usage:
  python3 prose_lint.py FILE [FILE ...] [--long 30] [--max-issues 0] [--quiet]

Checks (skips fenced code blocks, inline code, URLs, and front matter):
  filler     words that add nothing (just, simply, very, basically, actually ...)
  wordy      phrases with shorter equivalents (in order to -> to, utilize -> use ...)
  hedge      weasel words (arguably, somewhat, quite, fairly, it seems ...)
  passive    likely passive voice (be-verb + past participle); heuristic
  long       sentences over --long words
  repeat     the same word twice in a row ("the the")
  hype       marketing words (seamless, robust, leverage, cutting-edge ...)
Prints per-line findings, then sentence stats and a Flesch reading ease estimate.
Exit 1 when findings exceed --max-issues (default 0), 2 on usage errors.
"""
import argparse
import re
import sys
from pathlib import Path

FILLER = r"just|simply|very|really|basically|actually|literally|obviously|clearly|of course|totally|quite simply|needless to say"
HEDGE = r"arguably|somewhat|fairly|rather|quite|perhaps|it seems|sort of|kind of|more or less|to some extent"
HYPE = r"seamless(?:ly)?|robust|leverag(?:e|es|ed|ing)|cutting-edge|game-?changer|best-in-class|world-class|revolutionary|delve|unlock|elevate|supercharge|blazing(?:ly)? fast|next-gen"
WORDY = {
    r"in order to": "to",
    r"due to the fact that": "because",
    r"at this point in time": "now",
    r"in the event that": "if",
    r"for the purpose of": "to / for",
    r"has the ability to": "can",
    r"is able to": "can",
    r"utiliz(?:e|es|ed|ing)": "use",
    r"a number of": "some / several / <the number>",
    r"prior to": "before",
    r"in spite of the fact that": "although",
    r"with regard to|with respect to": "about",
    r"it is important to note that|please note that|note that": "(cut)",
    r"make a decision": "decide",
    r"provide assistance": "help",
    r"in terms of": "(rephrase)",
}
BE = r"(?:am|is|are|was|were|be|been|being)"
IRREGULAR = r"built|done|made|written|given|taken|seen|known|shown|sent|held|kept|left|lost|paid|put|read|run|set|told|thrown|brought|bought|caught|chosen|drawn|driven|eaten|fallen|found|forgotten|got|gotten|hidden|hit|hurt|led|meant|met|sold|shut|spent|split|spread|stolen|struck|taught|understood|won|worn"
PASSIVE = re.compile(rf"\b{BE}\s+(?:\w+ly\s+)?(\w+ed|{IRREGULAR})\b", re.I)
WORD = re.compile(r"[A-Za-z][A-Za-z'-]*")


def clean_lines(text):
    """Yield (line_no, text) with code, front matter, URLs, and HTML removed."""
    in_fence = False
    lines = text.splitlines()
    start = 0
    if lines and lines[0].strip() == "---":
        for i in range(1, len(lines)):
            if lines[i].strip() == "---":
                start = i + 1
                break
    for i, line in enumerate(lines[start:], start + 1):
        if re.match(r"^\s*(```|~~~)", line):
            in_fence = not in_fence
            continue
        if in_fence or re.match(r"^\s{4,}\S", line) or line.lstrip().startswith("|---"):
            continue
        line = re.sub(r"`[^`]*`", " ", line)
        line = re.sub(r"\]\([^)]*\)", "]", line)
        line = re.sub(r"https?://\S+", " ", line)
        line = re.sub(r"<[^>]+>", " ", line)
        yield i, line


def syllables(word):
    w = word.lower().strip("'")
    if len(w) <= 3:
        return 1
    w = re.sub(r"(?:[^laeiouy]es|ed|[^laeiouy]e)$", "", w)
    w = re.sub(r"^y", "", w)
    return max(1, len(re.findall(r"[aeiouy]{1,2}", w)))


def lint(path, long_limit):
    text = path.read_text(encoding="utf-8")
    findings = []
    prose = []
    for n, line in clean_lines(text):
        prose.append(line)
        checks = [
            ("filler", re.compile(rf"\b(?:{FILLER})\b", re.I), None),
            ("hedge", re.compile(rf"\b(?:{HEDGE})\b", re.I), None),
            ("hype", re.compile(rf"\b(?:{HYPE})\b", re.I), None),
        ]
        for kind, rx, _ in checks:
            for m in rx.finditer(line):
                findings.append((n, kind, m.group(0), ""))
        for pat, repl in WORDY.items():
            for m in re.finditer(rf"\b(?:{pat})\b", line, re.I):
                findings.append((n, "wordy", m.group(0), f"-> {repl}"))
        for m in PASSIVE.finditer(line):
            findings.append((n, "passive", m.group(0), "name the actor?"))
        for m in re.finditer(r"\b(\w+)\s+\1\b", line, re.I):
            if not m.group(1).isdigit():
                findings.append((n, "repeat", m.group(0), ""))

    # headings, list markers and table rows are not sentences; end them so they do not merge
    parts = []
    for line in prose:
        if re.match(r"^\s*#+\s", line) or line.lstrip().startswith("|"):
            continue
        line = re.sub(r"^\s*(?:[-*+]|\d+\.)\s+", "", line).strip()
        if line:
            parts.append(line if re.search(r"[.!?:]$", line) else line + ".")
    body = " ".join(parts)
    sentences = [s for s in re.split(r"(?<=[.!?])\s+(?=[A-Z\"'(])", body) if WORD.search(s)]
    lengths = []
    for s in sentences:
        words = WORD.findall(s)
        lengths.append(len(words))
        if len(words) > long_limit:
            snippet = " ".join(words[:8]) + " ..."
            findings.append((0, "long", f"{len(words)} words", snippet))

    words = WORD.findall(body)
    stats = {}
    if words and sentences:
        syl = sum(syllables(w) for w in words)
        stats = {
            "sentences": len(sentences),
            "avg_words": sum(lengths) / len(lengths),
            "max_words": max(lengths),
            "flesch": 206.835 - 1.015 * (len(words) / len(sentences)) - 84.6 * (syl / len(words)),
        }
    return findings, stats


def main():
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("files", nargs="+")
    p.add_argument("--long", type=int, default=30, help="flag sentences longer than this")
    p.add_argument("--max-issues", type=int, default=0)
    p.add_argument("--quiet", action="store_true", help="only print the summary")
    a = p.parse_args()

    total = 0
    for f in a.files:
        path = Path(f)
        if not path.is_file():
            print(f"error: {f} not found", file=sys.stderr)
            return 2
        findings, stats = lint(path, a.long)
        total += len(findings)
        print(f"== {path}")
        if not a.quiet:
            for n, kind, text, note in sorted(findings, key=lambda x: (x[0], x[1])):
                loc = f"L{n}" if n else "--"
                print(f"  {loc:<6}{kind:<8}{text}  {note}".rstrip())
        counts = {}
        for _, kind, _, _ in findings:
            counts[kind] = counts.get(kind, 0) + 1
        print(f"  findings: {len(findings)} " + (str(counts) if counts else ""))
        if stats:
            print(f"  sentences: {stats['sentences']}, avg {stats['avg_words']:.1f} words, "
                  f"longest {stats['max_words']}, Flesch reading ease ~{stats['flesch']:.0f} "
                  f"(60-70 plain English; technical docs often 40-60)")
    return 1 if total > a.max_issues else 0


if __name__ == "__main__":
    sys.exit(main())