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/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.
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 |