write-clearly

A writing skill for making documentation, explanations, reports, emails, and agent instructions clear, precise, concise, and honest.

In plain words
What is it for?
Use it to structure and revise prose, choose familiar words, clarify instructions, and check whether emphasis or figurative language accurately conveys the meaning.
Why use it?
It removes unnecessary wording and ambiguity while preserving important facts, uncertainty, and the intended voice.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/photostructure/coding-skills/write-clearly
Any agent
npx skills add photostructure/coding-skills --skill write-clearly
Clone the repo
git clone --depth 1 https://github.com/photostructure/coding-skills

Made for: Claude Code, Codex.

Per session 104 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 900 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00104 $0.00900
Opus 5 $0.00052 $0.00450
Sonnet 5 $0.00021 $0.00180
Haiku 4.5 $0.00010 $0.00090

Measured 2d ago against content hash f3599867505d, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

write-clearly scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

plugins/coding/skills/write-clearly/SKILL.md · 79 lines

How it starts

The opening of the file, as written. The whole thing — 79 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Write Clearly

Make the intended meaning easy for the intended reader to grasp. Less is more: precise, concise wording respects the reader's time and attention, and every needless word spends both. Preserve facts, uncertainty, necessary detail, and the author's recognizable voice.

Workflow

  1. Identify the reader, purpose, desired response, format, and tone. State only assumptions that could materially change the result.
  2. Fix structure before sentences. Lead with the conclusion, request, or action. Keep one topic per paragraph. Use descriptive headings; use lists or tables only when they make real sequences or comparisons easier to scan.
  3. Apply Orwell's tests:
    • Replace stale or mixed figures of speech with fresh wording or literal fact. Test each surviving figure by its literal image: if the picture cannot be drawn ("overarching pillars that undergird", "point a toolkit at a problem"), the words were paired by habit or co-occurrence, not meaning. Fluent phrasing over an incoherent image is the strongest marker of machine-generated prose.
    • Prefer the shortest familiar word that is equally exact.
    • Cut every word that adds no meaning, tone, or useful rhythm.
    • Prefer active voice when it makes the actor and responsibility clearer.
    • Replace needless jargon, scientific language, or untranslated foreign terms with an everyday equivalent.
    • Break any rule before producing prose that is false, ugly, or inhumane.
  4. Apply complementary checks:
    • Prefer concrete nouns, specific examples, and strong verbs. Turn nominalizations into verbs when that exposes the action.
    • Keep necessary technical terms when they are more precise or familiar to the reader; define them on first use when needed.
    • Keep subjects near verbs, modifiers near referents, and parallel ideas in parallel form.
    • Give each sentence one main thought, but vary sentence and paragraph length enough to avoid a mechanical rhythm.
    • Ration signature rhetorical devices: "not X but Y" contrasts, groupings of three, staccato sentence fragments, self-validating asides ("and that matters"), and pet intensifiers such as honestly, actually, and delve. Each is legitimate rhetoric on its own; clustered, they read as machine-generated boilerplate.
    • Remove euphemism and abstraction that hide what happened or who is responsible.
    • Never gain brevity by changing scope, certainty, causality, intent, or voice.
  5. Verify the result. Check that the takeaway appears early, actors and actions are unambiguous, and every word earns its place. Read it aloud. For high-stakes public content, ask representative readers to find and paraphrase the key points.

Read the full file on GitHub · 79 lines

Files

What ships with it

3 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 79 lines · 104 tokens per session scan A f3599867505d

Subscribe to this mod's changes

write-clearly is a skill published in the GitHub repository photostructure/coding-skills (3 stars, last pushed 2d ago), licensed MIT. It adds 104 tokens to every session and 900 once invoked, about $0.0005 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Related

Other skills, from other repositories

decision-records

Creates, supersedes and validates decision records (ADRs) against the convention a collection already follows, instead of imposing a published one. Use when the user wants to record a decision, write an ADR, supersede an existing decision, audit or lint a decisions folder, check that an ADR index is in sync, or asks…

fvadicamo/dev-agent-skills · 113 tokens

github-pr-review

Handles PR review comments and feedback resolution. Use when user wants to resolve PR comments, handle review feedback, fix review comments, address PR review, check review status, respond to reviewer, verify PR readiness, review PR comments, analyze review feedback, evaluate PR comments, assess review suggestions, or…

fvadicamo/dev-agent-skills · 95 tokens

privacy-guard

Prevents private infrastructure details (node hostnames, internal project names, local usernames and personal emails, absolute home paths, private and VPN IP ranges) from leaking into public repositories through commits, PRs, docs or release artifacts. Use when working in a public or soon-to-be-public repo, before…

fvadicamo/dev-agent-skills · 128 tokens

github-pr-creation

Creates GitHub Pull Requests with automated validation and task tracking. Use when user wants to create PR, open pull request, submit for review, or check if ready for PR. Analyzes commits, validates task completion, generates Conventional Commits title and description, suggests labels. NOTE - for merging existing…

fvadicamo/dev-agent-skills · 75 tokens

github-pr-merge

Merges GitHub Pull Requests after validating pre-merge checklist. Use when user wants to merge PR, close PR, finalize PR, complete merge, approve and merge, or execute merge. Runs pre-merge validation (tests, lint, CI, comments), confirms with user, merges with proper format, handles post-merge cleanup.

fvadicamo/dev-agent-skills · 72 tokens

git-commit

Creates git commits following Conventional Commits format with type/scope/subject. Use when user wants to commit changes, create commit, save work, or stage and commit. Enforces project-specific conventions from CLAUDE.md.

fvadicamo/dev-agent-skills · 49 tokens