jackson2w/claude-code-skills / clarity
clarity
VerifiedDraft, rewrite, or review reader-facing prose so it is specific, useful, and recognizably the author's without inventing facts or performing humanness. Use for essays, articles, newsletters, documentation, talks, launch copy, and other important prose that feels generic, hollow, or AI-shaped. Supports co-write, rewrite, review, and lint modes.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 7.5 KB |
| references/edit.md | markdown | 7.1 KB |
| references/interview.md | markdown | 3.2 KB |
| references/longform.md | markdown | 4.9 KB |
| references/medium.md | markdown | 3.4 KB |
| references/review.md | markdown | 2.7 KB |
| scripts/prose_stats.pyexecutable | script | 14.1 KB |
| scripts/strip_markdown.pyexecutable | script | 2.4 KB |
references/longform.md
View on GitHub# Authored long-form
Use this for essays, articles, newsletters, talks, narrative, fiction, and evocative writing.
It turns Clarity's public writing principles into an editing pass. It does not override factual
fidelity, the author's supplied voice, the medium, or the user's brief.
## Decide what the reader carries away
Picture one reader and distinguish what they already know from what they still need. The gap
sets the piece's scope. Choose one intended takeaway appropriate to the register:
- an argument needs a supported position someone could dispute;
- an explanation needs a mechanism the reader can understand;
- an evocation needs an image or feeling it can honestly produce;
- a narrative needs events and a reason to continue;
- a talk needs a thought a listener can retain without rereading.
State or establish that takeaway early enough to orient the reader. Do not force a thesis onto
a piece whose job is wonder, remembrance, description, or story.
## Make the attention pay
Read each sentence against the one before it. It should add a fact, image, mechanism, example,
qualification, consequence, or useful change in pressure. Cut throat-clearing, duplicated
explanation, and conclusions that exist only because the form seems to require one. Let the
piece be as short as its job permits.
Prefer the plain accurate word. Break a sentence when it asks the reader to hold unrelated
ideas at once or loses its subject. Keep a long cumulative sentence when one visible subject
carries the clauses and the accumulation creates momentum. Length is a prompt to listen, not a
verdict.
## Give the opening one job
The first sentence should make the intended reader willing to read the second while beginning
the actual work of the piece. A supported fact, number, scene, image, question, or claim can do
that. A generic definition, historical panorama, announcement of intent, or summary of the
topic usually cannot.
Do not manufacture a startling fact or scene to improve a lead. When the source contains no
honest opening material, start plainly or ask the author for it.
## Make the piece develop
Each paragraph should answer something the previous paragraph raised, complicate it, show it,
or make the next paragraph necessary. Name a load-bearing relation—because, although, once, if,
so, which—when adjacency only imitates reasoning. Keep a clean juxtaposition when sequence,
surprise, or speed is the point.
For arguments, state the author's leaning and give the strongest real limitation or objection
enough room to matter. Answer it or concede it. Do not invent a weak opponent merely to defeat
one. Other registers do not owe a debate.
## Keep the author in the prose
Use the author's sample and supplied language to decide vocabulary, formality, contractions,
first or second person, punctuation, and rhythm. Ask whether the author would comfortably say
the sentence to the intended reader. That test catches borrowed erudition, fake humility, and
formality with no communicative purpose; it does not require every written sentence to sound
like an unedited transcript.
Protect real asides, mixed feelings, trade language, deliberate repetition, jokes, and unusual
details. Never insert those features as evidence of humanness.
## Put positive craft back
An edit that only subtracts often leaves colder prose. After cutting, inspect the passage that
needs the most weight:
- **Image:** Can the reader see, hear, or feel anything? Sensory specificity and verifiable
specificity are different; use the kind the piece needs and the source supports.
- **Stance:** What does the author want, prefer, fear, enjoy, doubt, or refuse? Neutrality can be
right for reference prose, but in authored work it should be a choice rather than residue.
- **Rhythm:** Let syntax carry a relation or an experience, never missing reasoning. An earned
series, fragment, long sentence, or short landing line may be exactly right.
- **Warmth:** Restore humor, curiosity, generosity, unease, or delight when the draft supplied
it and the edit erased it.
- **Memorable line:** Keep one the preceding material earned. Flatten a line whose cadence is
performing profundity the piece did not build.
Do not invent an image, attitude, or personal reaction for the author. Ask or leave `[TK]` when
positive craft requires source material that is missing.
## Rewrite, then listen
Real rewriting may move the third paragraph to the opening, combine two sections, remove the
writer's favorite passage, or uncover the plain sentence buried inside a polished one. Make
those changes only within the scope the user authorized. Smoothing every rough edge is not
rewriting when the rough edge carries the thought.
Before delivery, read or subvocalize the complete piece once. Listen for plodding paragraphs,
breathless clauses, repeated sentence shapes, abrupt changes of footing, and language the author
would never say. Fix the stumbles that obstruct the reader. Do not continue polishing after the
piece works.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |