/human-writing

name: human-writing
description: "MUST be used for any request to draft, write, compose, or reword text another person will read, including 'draft a message', 'draft a reply', 'draft a Slack message', 'write an email', 'draft a PR description', 'write a GitHub issue', 'write a Jira ticket', 'draft a card', 'draft an announcement', 'write release notes', 'draft an RFC', 'write a README'. Covers Slack, email, PR bodies, GitHub issues, Jira tickets, code review comments, bug reports, agendas, Reddit posts, and persisted project documents (READMEs, specs, RFCs, ADRs, design and planning docs, runbooks); for documents, use this skill for the drafting even when a documentation-writing skill also applies. Applies plain, literal writing with per-format conventions, then routes persisted project documents to the cold-reader review. Not for review-only requests on an existing document; use cold-reader alone for those."
allowed-tools: Read(~/.config/human-writing/personal-voice.md)

Human Writing

Write in plain high-school English. State the point directly.

---

Start here: read the format reference

Before writing any draft, read the reference for its format with the Read tool. Do this for every new draft, including when this skill is already loaded from an earlier draft in the conversation: the sections below are shared across formats, and the reference holds the rules for this one.

You MUST read the whole reference file with the Read tool. You MUST NOT read it with `cat`, `grep`, `head`, `sed`, or any other shell command, or bundle it into a shell call with other commands. Each reference is under 40 lines, so the full file fits in context, and a filtered or combined shell read drops rules the draft needs.

| If the user asked for | Read | |---|---| | A Slack message | [`references/slack.md`](references/slack.md) | | An email (internal or external) | [`references/email.md`](references/email.md) | | A pull request body / description | [`references/pull-requests.md`](references/pull-requests.md) | | A GitHub issue (bug report or feature request) | [`references/github-issues.md`](references/github-issues.md) | | A Jira ticket (creating, rewriting, or rescoping one) | [`references/jira-tickets.md`](references/jira-tickets.md) | | A Reddit post or reply | [`references/reddit.md`](references/reddit.md) | | A meeting agenda | [`references/meeting-agendas.md`](references/meeting-agendas.md) | | A persisted project document: docs, README, spec, RFC, ADR, design or discovery doc, planning doc, proposal, runbook, or reference material | [`references/docs.md`](references/docs.md) |

If no row matches, apply the rules in this file. Where a reference and the voice file disagree, follow the voice file.

---

Natural phrasing

Use contractions, fragments, conjunction openers, and varied sentence lengths only when they fit the supplied text and the requested tone. Do not force variation to make the draft seem human.

Core voice

• Use plain high-school English. Prefer common words.
• Join related facts into one sentence with connecting words (*before*, *because*, *which*, *so that*, *after*). Split into separate sentences only when the ideas are independent.
• Use literal language. State the mechanism or behavior without metaphor, idiom, analogy, or wordplay. Standard technical terms are fine.
• Use concrete names, verbs, and numbers. Introduce an unfamiliar system by saying what it does.
• Link every ticket key, pull request, issue, or dashboard page to its URL. A bare ID or "the PR" with no link is unfinished.
• State facts and dependencies without telling the reader how important they are.
• Include what the reader needs for an accurate picture. Leave out unrelated detail.
• Hedge only when the evidence is incomplete.
• Remove filler qualifiers such as *actually*, *obviously*, *essentially*, and *simply*.
• State each point once; do not restate it more grandly as a conclusion.
• Use *I* when the user is the actor. Do not invent stylistic quirks on the user's behalf.

Content fidelity

For text written on the user's behalf, match their tone and phrasing without adding content. The user must have supplied or approved every claim, commitment, and opinion. If a required fact is missing, ask before drafting. If the user requests a best-effort draft, omit the missing fact. Never invent content or add editorial opinion.

Do not add:

• Commitments ("I'll add a note to CLAUDE.md", "I'll follow up next week")
• Apologies or fault-taking ("that one's on me")
• Opinions or editorial beyond the points discussed and agreed to by the user
• Promises of future work, even ones recommended earlier in the conversation.

Personal voice (optional)

The user's voice file, loaded when this skill loads. Empty output means no voice file exists; skip this section.

!`cat ~/.config/human-writing/personal-voice.md 2>/dev/null || true`

Apply the voice file to every draft. Where it and a format reference disagree, follow the voice file. If the line above shows an unexecuted command instead of file contents, shell execution is disabled for skills; read `~/.config/human-writing/personal-voice.md` with the Read tool before drafting, and skip this section if the file does not exist.

To set up a voice file, copy [`templates/personal-voice.md`](templates/personal-voice.md) to that path and fill it in.

Lint the draft

A Vale configuration ships with this skill and matches the fixed-phrase subset of Banned forms. Before delivering any draft, write it to a temporary Markdown file, then run:

vale --config="${CLAUDE_PLUGIN_ROOT}/skills/human-writing/assets/.vale.ini" --output=JSON "<draft.md>"

If `${CLAUDE_PLUGIN_ROOT}` is unset, resolve `assets/.vale.ini` relative to this SKILL.md's directory.

Triage the alerts by severity:

• **error:** the phrase is banned outright. Fix every one.
• **warning:** banned in a specific position (a message opener, a message closer) or relaxable by the personal voice file.