better-writing

Better Writing

An agent skill for prose that sounds clear, specific, and human.

Quick install

Any agent that reads skills (Claude Code, Codex, Cursor, and others):

npx skills add forjd/better-writing

Claude Code plugin:

/plugin marketplace add forjd/better-writing
/plugin install better-writing@forjd

More options are under Installation.

What it will not do

Beating AI detectors is explicitly a non-goal. Better Writing improves clarity, specificity, and voice fit. It does not lower AI-detector scores, and no edit can guarantee one. Detector scores are deliberately not a check in the evaluation harness — see why detector scores are not a check.

If you ask it to pass a detector, it runs the strict pass and says so in the change note, without evasion tricks such as synonym swaps, inserted typos, look-alike characters, or translation round-trips. They make the prose worse, and leading detectors are now trained on humaniser output. See Guardrails.

What it is

Better Writing is an agent skill for rewriting, drafting, and reviewing prose. Most de-slop skills delete AI tells and converge everything toward one generic "casual human" register. This one adds what those skip:

1. The writer's voice. A user-provided writing sample is the style source of truth, and per-genre dials (directness, warmth, density, polish) replace blanket rules. A board memo and a personal essay get different treatment.
2. Specificity without invention. "Make it concrete" prompts tempt models into fabricating numbers, anecdotes, and named experts. The guardrails and the preflight preservation check forbid that: missing facts become placeholders or questions, never inventions.
3. Context beats blanket rules. The same dash, hedge, or formal phrase can be a tell in one genre and correct in another. The audit looks for clusters of tells, with an explicit false-positive list so polished human writing survives the pass.

On top of that, it does the expected job well:

• AI-sounding patterns such as significance inflation, vague attribution, promotional padding, and formulaic conclusions
• slop structures such as throat-clearing, binary contrast, false agency, over-signposting, and manufactured drama
• confidence tiers and a near-conclusive-artefact check, so a single quirk never triggers an edit but leaked tool markup or an unfilled [Your Name] placeholder does
• a final preflight check before delivery

It also ships with an evaluation harness: fixtures seeded with known tells and known facts, a checker, and a runner that sends each fixture through a real model with the skill loaded.

Before and after

Each "after" is a hand-written target rewrite that passes the checker for its fixture. The inputs are in evals/fixtures/ and the rewrites in evals/examples/.

A launch email, de-slopped

Before:

I hope this email finds you well! We're thrilled to announce the launch of our groundbreaking new analytics dashboard, which goes live on Monday 15 June. This isn't just an update — it's a game-changer designed to transform your workflow. The dashboard replaces the weekly CSV export, and data now refreshes every hour instead of every seven days, empowering you to unlock deeper insights across teams, projects, and date ranges. To get started on this exciting journey, simply navigate to the Reports tab after logging in. Exciting times lie ahead!

After:

Our new analytics dashboard goes live on Monday 15 June. It replaces the weekly CSV export. Data refreshes every hour instead of every seven days, and you can view it across teams, projects, and date ranges. To start using it, log in and open the Reports tab.

Every fact survived: the date, the CSV export, the hourly refresh, the teams, projects, and date ranges, and the Reports tab. Everything else went.

A report paragraph, made specific without inventing anything

Before:

It is important to note that customer churn has become a significant challenge in today's competitive landscape, rising for the second consecutive quarter. Some internal observers suggest the March pricing change and onboarding drop-off may have contributed, underscoring the need for a proactive retention strategy moving forward. The implications are significant.

After:

Churn rose for the second quarter in a row [churn figure needed]. It has been suggested internally that the March pricing change and onboarding drop-off may have contributed. Both point to the need for a retention plan.

Note the placeholder. The skill will not invent a churn figure to make the paragraph sound concrete. If the figure exists in the source material, it goes in; if not, the gap is marked honestly.

A writer's draft, edited without flattening

Writer's draft:

I have rewritten this parser three times now, which is either dedication or a cry for help. Version three finally handles nested quotes, escaped backslashes, and the cursed Windows-1252 em dash that started this whole saga. I am not proud of the regex. It works.

What a generic humaniser pass produces:

After several iterations, the parser now robustly handles nested quotes, escaped backslashes, and Windows-1252 em dashes.

What this skill does: nothing. The draft has a voice, the details are specific, and "a cry for help" is a defendable quirk, not a tell. The skill's job here is to recognise that and leave it alone.

When to use it

Use this skill when an agent needs to improve:

• emails and messages
• essays, posts, and opinion drafts
• reports, proposals, and memos
• documentation and release notes
• marketing copy and product copy
• UI text and microcopy
• any draft that sounds too generic, verbose, evasive, salesy, or AI-written

Installation

The skills.sh CLI is the easiest way to install the skill.

With npx:

npx skills add forjd/better-writing

With bunx:

bunx skills add forjd/better-writing

You can also install from the full GitHub URL:

npx skills add https://github.com/forjd/better-writing
bunx skills add https://github.com/forjd/better-writing

For local development, install from this checkout:

npx skills add /path/to/better-writing
bunx skills add /path/to/better-writing

The CLI collects anonymous install telemetry by default. To opt out:

DISABLE_TELEMETRY=1 npx skills add forjd/better-writing
DISABLE_TELEMETRY=1 bunx skills add forjd/better-writing

Claude Code plugin

The repo is also a Claude Code plugin marketplace. In Claude Code:

/plugin marketplace add forjd/better-writing
/plugin install better-writing@forjd

Or from a shell:

claude plugin marketplace add forjd/better-writing
claude plugin install better-writing@forjd

Run /plugin marketplace update forjd to pick up new releases.

Manual install

You can also copy the folder into your agent skills directory if your agent runtime supports local skill discovery.

To pin a release rather than track main, clone its tag and copy that checkout:

git clone --branch v1.3.0 https://github.com/forjd/better-writing.git # x-release-please-version

The installed version is metadata.version in the SKILL.md frontmatter.

Install with you