Skip to content

jackson2w/claude-code-skills / clarity

clarity

Verified

Draft, 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.

FileKindSize
LICENSEother1.0 KB
SKILL.mdskill md7.5 KB
references/edit.mdmarkdown7.1 KB
references/interview.mdmarkdown3.2 KB
references/longform.mdmarkdown4.9 KB
references/medium.mdmarkdown3.4 KB
references/review.mdmarkdown2.7 KB
scripts/prose_stats.pyexecutablescript14.1 KB
scripts/strip_markdown.pyexecutablescript2.4 KB

references/edit.md

View on GitHub
# Editing guide

Use this for rewrites and as the pattern reference during reviews. Read the passage before
classifying a pattern. A familiar construction is not a defect when the surrounding prose earns
it or the medium requires it.

## Order of work

Fix problems in this order:

1. **Truth and scope.** Inventory claims, attribution, uncertainty, examples, citations, links,
   conditions, quotations, redactions, and required structure. These are protected.
2. **Substance.** Identify the real outcome or point. In authored long-form work, find the
   source material only this author supplied. If it is absent, ask or label the limitation.
3. **Development.** Make paragraphs depend on one another through cause, contrast, sequence,
   qualification, example, or consequence. Restructure only as much as the request permits.
4. **Sentences.** Remove inflated, repetitive, or formulaic machinery while preserving useful
   voice and medium conventions.
5. **Craft.** Restore concrete material, stance, warmth, or rhythm if editing made the piece
   colder or flatter.

## High-value diagnoses

### Importance without mechanism

The sentence claims magnitude instead of showing what happens.

```txt
Watch: pivotal, crucial, transformative, underscores the importance, represents a shift,
       testament to, broader trend, plays a key role
Test:  remove the emphasis. Does the remaining claim name an actor, mechanism, result, or limit?
Fix:   state the supported mechanism and let the reader judge its importance.
```

Keep an evaluative word when the same passage supplies the evidence that earns it. `Robust`
belongs in an engineering sentence that names the failure handling; it does not belong in
`a robust approach` with no mechanism.

### Specific-looking vagueness

An anecdote can have the grammar of an example and the content of an abstraction: “a package
once caused a security problem.” Ask which package, what happened, and how it was caught. If the
source does not contain the answer, use `[TK]` or cut the anecdote. Never fill the gap yourself.

Dates, names, and citations make claims verifiable. Images make a reader present. Use the kind
of concreteness the register needs; do not add decorative facts to satisfy a density target.

### Vague attribution and false precision

```txt
Watch: experts argue, studies show, observers note, industry reports suggest
Fix:   name the supplied source, preserve explicit uncertainty, ask for it, or cut the claim.
```

Do not convert association into causation, `may` into `will`, `some` into `most`, or a vendor's
claim into narrator fact. A more confident sentence is not automatically a clearer one.

### Formula carrying the argument

Common forms include `not X but Y`, balanced threes, repeated short punchlines, fake questions,
and topic-sentence/explanation/zinger paragraphs.

Run two tests:

1. **Flatten test:** state the claim without the cadence. If nothing specific remains, the
   formula was doing the missing reasoning's work.
2. **Relation test:** restate the implied connection using `because`, `although`, `when`, `if`,
   `which`, or `so`. If doing so requires inventing a relation, the original only suggested one.

Keep an earned contrast, concrete three-item list, short sentence, fragment, or memorable line.
Change repeated use or unsupported performance, not the device itself.

### Abstract actors

Decisions do not decide and data does not speak. Name the person, team, system, or documented
process when that makes the action clearer. Passive voice remains correct when the actor is
unknown, irrelevant, deliberately protected, or less important than the object.

### Structural regularity

Inspect the piece's dominant shape rather than hunting isolated words:

- sections with identical length and internal order;
- paragraphs that can trade places without changing the argument;
- headings doing all the organizing;
- every example interpreted for the reader;
- every paragraph ending on a line built to be quoted;
- a conclusion that recaps or widens into generic optimism.

Fix only the dominant problem. Move or combine material, let one section carry more weight,
name the relation at a weak join, or stop at the last concrete consequence. Do not introduce a
random tangent, unresolved thread, or sentence-length wobble merely to look irregular.

### Surface residue

Usually remove:

```txt
Chatbot wrapper       Certainly, Great question, Here is..., I hope this helps, Let me know if
Meta narration        Let's dive in, In this section, As we will see, Without further ado
Empty emphasis        It is important to note, At its core, The real question is
Prestige vocabulary  delve, tapestry, landscape, pivotal, seamless, groundbreaking, unlock
Decorative tails      highlighting..., underscoring..., fostering..., reflecting...
Generic endings       In conclusion, Ultimately, Looking ahead, The future belongs to...
```

Treat the list as a search aid, not a ban. Keep quoted text, proper names, terms of art, and an
ordinary word used accurately. Do not replace one watched synonym with another; rewrite the
claim or leave it alone.

Formatting can also reveal default assistant behavior: unnecessary bold, bold-label bullet
lists, decorative emoji, title-case headings against house style, and a heading immediately
restated by its first sentence. Preserve formatting that supports scanning, accessibility, or
the requested medium.

## Preserve human material

Protect details and choices an author could defend:

- an unusual checkable detail;
- a real aside, self-correction, mixed feeling, or unresolved doubt;
- deliberate repetition of the right ordinary word;
- trade language, dated references, or a slightly surprising phrase that fits the author;
- sentence-length variation produced by the thought;
- an earned joke, contrast, rhythmic series, or closing beat.

Do not insert these as “human signals.” Existing texture can be preserved; invented texture is
performance.

## Put craft back

After subtraction, ask:

```txt
Can the reader see, hear, or feel anything where the piece most needs weight?
Does evaluative writing reveal what the writer wants, prefers, fears, or doubts?
Does the syntax express the relationship between thoughts?
Did the edit remove warmth, humor, or a memorable line that the surrounding prose earned?
```

Add only material supported by the source. For a hollow passage, a precise `[TK]` question is a
better edit than model-generated color.

## Rewrite check

Compare the finished text with the source:

- Every factual claim, number, quotation, citation, attribution, condition, and link survives
  with the same force.
- No new personal experience, preference, source, metric, or causal claim appeared.
- The rewrite does not reproduce the pattern it criticized under different punctuation.
- The medium still works: procedures scan, warnings remain visible, emails state the ask, and
  reference material remains retrievable.
- The strongest original sentence was left alone unless changing it solved a real problem.
- The ending stops on the last useful thought.

If a rewrite fails one of these checks, repair it once. Do not keep iterating until every
sentence shares the same polished register.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexUnverifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall