⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v2.1.0

better-writing

forjd@forjd⭐ 56 stars· last commit 14d ago· 0 open issues

Rewrite, draft, and review prose so it is clear, specific, human, and fits its context. Use when improving emails, reports, documentation, marketing copy, UI text, or posts that sound generic, AI-written, verbose, salesy, or formulaic, and when the user asks to humanise/humanize, de-AI, fix text that sounds like ChatGPT, light edit, copy edit, proofread, or keep my voice. Covers voice calibration, anti-slop audits, and preflight checks.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 56 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Better Writing

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

Agent Skill License: MIT skills.sh

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.

Use one method, not both. Claude Code loads each install separately, so with both you get the skill twice.

Manual install

You can also copy skills/better-writing/ into your agent skills directory if your agent runtime supports local skill discovery. Copy that folder only, not the whole repo.

To pin a release rather than track main, clone it

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md7.8 KBupstream ↗
    ---
    name: better-writing
    description: Rewrite, draft, and review prose so it is clear, specific, human, and fits its context. Use when improving emails, reports, documentation, marketing copy, UI text, or posts that sound generic, AI-written, verbose, salesy, or formulaic, and when the user asks to humanise/humanize, de-AI, fix text that sounds like ChatGPT, light edit, copy edit, proofread, or keep my voice. Covers voice calibration, anti-slop audits, and preflight checks.
    license: MIT
    metadata:
      version: "1.3.0" # x-release-please-version
    ---
    
    # Better Writing
    
    Use this skill to make prose stronger without flattening the writer. The goal is not to make everything casual or punchy. The goal is to make the text fit its audience, purpose, and medium while removing generic AI tells, filler, fake authority, and formulaic structure.
    
    ## Core workflow
    
    1. Read the brief before editing.
       - Identify the genre/medium (=channel), audience, relationship, stakes, outcome (=purpose), and constraints (length, requested dialect, house style, exact wording).
       - Preserve required facts, citations, constraints, legal wording, quoted text, and formatting.
       - If the user gives a voice sample, audit it against the tell lists first; if it scores high, ask before treating it as the style source of truth.
       - For a draft from scratch, collect the substance before writing: the point, the facts, the writer's position, and any example or number they have. Draft by default and mark each missing fact with a gap marker such as `[example needed: a customer who hit this]`. Ask first only when the point itself is missing. Cutting tells cannot add missing content, and a brief with no facts produces generic prose however clean the sentences are.
       - If the brief says light edit, copy edit, proofread, or keep my voice, switch to light-edit mode. Every word starts as kept. A change needs a failure you can name: a grammar or spelling error, an ambiguity, a factual inconsistency, a house-style rule the brief gives, or filler that says nothing the sentence does not already say ("it is important to note that", a closer with no content). Being on a tell list is not a failure, and neither is a word you would not have chosen: "delve" carries its sentence's meaning, so it is a word choice, not filler. On the second read, put back every change you cannot justify that way.
    
    2. Set the writing read.
       - Form this line for internal reasoning, and output it only if the user asked for a plan: "Reading this as: [genre] for [audience], with [tone], optimising for [outcome]."
       - Choose dials for directness, warmth, personality, density, evidence, and polish. See `references/voice-and-context.md`.
       - If there is a voice sample, record its profile (sentence lengths, openers, contractions, person, hedges, punctuation, recurring words) before editing and recompute it after. The procedure is under Voice calibration in `references/voice-and-context.md`.
    
    3. Audit the text.
       - For AI-writing tells, use `references/ai-writing-patterns.md`.
       - For slop phrases and formulaic structures, use `references/structures-and-phrases.md`.
       - For genre-specific fingerprints and exemptions, use `references/genre-tells.md`.
       - Work in order: scan for near-conclusive artefacts first; then count clustered tells in context; then apply genre exemptions. Never edit on a single feature of any tier; near-conclusive artefacts defined in `references/ai-writing-patterns.md` are the sole single-instance exception.
       - Look for clusters of tells, not isolated quirks. The most durable tell is uniform tone that never adapts to audience or genre. Do not destroy valid style just because it is polished.
    
    4. Rewrite. Each bullet below is a target illustrated by a preferred versus dispreferred pair; the ban lists in `references/` are for the audit, not for the rewrite.
       - Keep the meaning and coverage unless the user asks for cuts.
       - When a sentence carries two or more tells, rebuild its structure instead of swapping the flagged word for a synonym. A synonym swap leaves the rhythm and shape that readers notice. Keep the source's facts, its hedge words, and any phrasing that is not a tell. Single-tell sentences, light edits, and edits against a voice sample keep the smallest fix.
       - Prefer actor, object, and evidence for factual claims. "The compiler rejects a renamed column at build time", not "type safety is improved". When the source is vague and gives no fact to name, keep it vague or mark the gap. Keeping it vague keeps the claim's strength, not its faceless-authority noun: "some internal observers suggest" becomes "it has been suggested internally", never "the finance team suggests". A vague feature stays vague too: "powerful search" does not become "search covers everything you have written". A concrete-sounding claim the source does not contain is worse than a vague one. Greetings, thanks, apologies, opinions, and questions are not factual claims and need no actor or evidence.
       - Default to sentences that say what happens, in the order it happens, with the doer as subject. "The loader parses the file", not "the file is parsed". Keep passive or system-as-subject where the actor is unknown, irrelevant, or legally sensitive, or where the genre expects it; see the documentation section in `references/voice-and-context.md` and the academic section in `references/genre-tells.md`.
       - Sentence length follows the idea: a short sentence for the point, a longer one for the reasoning behind it. "It works. The regex that makes it work took three rewrites and a Friday evening."
       - For short pieces and emails, the first sentence makes the point and the last sentence is the strongest fact already in the source, or the user-requested next action. When cutting a flourish leaves no closing fact, end on the previous sentence; do not write a new one. "The migration runs on Saturday 12 July", not "I wanted to reach out about the migration". For long documents apply this per section, and exempt specs and runbooks.
       - The literal phrase wins over the figurative one. "Three services call the same endpoint", not "a symphony of microservices".
       - Subtract and surface. Never add. Cut the tells, then let what the source already holds show through. Never invent facts, voice, a next step, a claim about what has or has not happened, a joke or aside in the writer's manner, a sensory detail, a typo, slang, or a contraction the source lacks. Genre-required register shifts (contractions and second person in chat or email) and a user-requested next action are allowed additions, not fabrications. A hedge the genre requires (academic, legal, medical) is flagged in a note, not added. Where a gap needs filling, mark it or ask. Inflation is cut or restated at its true strength, in about as many words as the source's clause, and never converted into a fact: "paving the way for a rollout" does not become "the rollout is under way", and "underscores the importance of planning" does not become "planning made the difference".
       - In light-edit mode, change only what is wrong. A lone word or punctuation mark from a tell list, such as one "delve" or a single em dash, is the writer's choice and stays. "Trying to delve into why the export failed" keeps "delve"; "right when the backup locked the table" keeps its dash. A light edit that finds nothing wrong returns the text unchanged, and that is a correct result. Keep the writer's contractions or lack of them, first-person sentences, and hedges unless you can quote the clarity failure; compare before-and-after counts per `references/preflight.md`, and report them only if they moved (see Default output).
    
    5. Self-audit and revise.
       - Ask: "What still sounds generic, evasive, or AI-written?" and "Does every sentence add information this reader, in this conversation, didn't already have?" For conversational venues (PR and issue comments, review replies, chat threads), the test reaches the surroun
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/forjd-better-writing.md

// REPO STATS

56 stars
0 open issues
Last commit: 14d ago