Agent-Skills.md

Agent Skills: Clear Writing

Apply ISO 24495-1 to create text that helps readers easily find, understand, and use the information they need. Use this skill only to write, revise, or review practical documents that convey information, explain procedures, or support decision-making, and provide only the requested output.

UncategorizedID: buyoung/skills/clear-writing

Repository

buyoung/skills
buYoungLicense: MIT
213

Install this agent skill to your local

pnpm dlx add-skill https://github.com/buYoung/skills/tree/HEAD/skills/clear-writing

Skill Files

Browse the full folder contents for clear-writing.

Download Skill

Loading file tree…

skills/clear-writing/SKILL.md

Skill Metadata

Name
clear-writing
Description
Apply ISO 24495-1 to create text that helps readers easily find, understand, and use the information they need. Use this skill only to write, revise, or review practical documents that convey information, explain procedures, or support decision-making, and provide only the requested output.

Clear Writing

ISO 24495-1:2023 defines plain language by its outcome: wording, structure, and design so clear that the intended readers can easily find what they need, understand what they find, and use that information. Everything in this skill serves that outcome.

Two things about the standard shape how you should work:

  • It focuses on how well readers can use a document, not on mechanical measures such as readability formulas. So the job is not "shorten sentences and swap hard words." Most of the work is deciding what these readers need and arranging it so they can act on it. Word choice is a small part: the International Plain Language Federation (IPLF) reports that only about 7% of the standard's roughly 485 ideas concern word choice.
  • It applies to most written languages, and the IPLF describes it as language-neutral. Apply its guidelines through the conventions of the language you are writing in.

The four principles

The standard treats the principles as interdependent, not as a sequence: a text is usable when its content is relevant, findable, and understandable, and only evaluation shows whether it really is. The steps below follow the principles in working order; go back to an earlier step whenever a later one shows a problem.

| Principle | Reader outcome | Guidelines (clause) | |---|---|---| | 1 Relevant | Readers get what they need | 5.1.2 Identify the readers · 5.1.3 Identify the readers' purpose · 5.1.4 Identify the context in which readers will read the document · 5.1.5 Select the document type or types · 5.1.6 Select content that readers need | | 2 Findable | Readers can easily find what they need | 5.2.2 Structure the document for readers · 5.2.3 Use information design techniques that enable readers to find information · 5.2.4 Use headings to help readers predict what comes next · 5.2.5 Keep supplementary information separate | | 3 Understandable | Readers can easily understand what they find | 5.3.2 Choose familiar words · 5.3.3 Write clear sentences · 5.3.4 Write concise sentences · 5.3.5 Write clear and concise paragraphs · 5.3.6 Consider including images and multimedia · 5.3.7 Project a respectful tone · 5.3.8 Ensure that the document is cohesive | | 4 Usable | Readers can easily use the information | 5.4.2 Evaluate the document continually as it is developed · 5.4.3 Evaluate the document further with readers · 5.4.4 Continue to evaluate readers' use of the document |

references/guidelines.md explains what each guideline asks and how to apply and check it. Read it once at the start of the task, and go back to the relevant section when a specific question comes up (for example, where warnings belong relative to steps). It also marks which statements summarize the standard, which come from IPLF commentary, and which are practical guidance written for this skill — keep that distinction when you cite the standard.

Choose the mode

  • Write: the user gives notes, facts, or a request and wants new text.
  • Rewrite: the user gives existing text and wants it plainer. If they ask to "check and fix," it is a rewrite.
  • Review: the user wants to know whether and where a text falls short, without a rewrite. Use Steps 2 to 5 and the Check questions in references/guidelines.md as your criteria, and report in the review format under Output instead of rewriting.

All three modes start with readers, purpose, and situation, because plainness only exists relative to particular readers. A sentence that is plain for nurses can be opaque to patients.

Step 1: Confirm readers, purpose, and situation before writing

You need three things before drafting or reviewing:

  • Readers: who will read it, and how much they already know about the topic.
  • Purpose: what readers need to do, decide, or know after reading.
  • Situation (the context in 5.1.4): where and how they will meet the text (text message, printed letter, notice board, web page), and any pressure on them that would change the text (urgency, worry, bad news).

Treat each as known only when the user states it, or the provided material states it outright (for example, an addressee line plus an explicit request to the reader). A stated channel, such as "문자로 보낼 안내" or a printed letter, confirms the situation. If any of the three would have to be guessed, ask before drafting or reviewing. A wrong guess produces a polished text for the wrong person, which costs more than one short exchange.

Ask in a single message that is quick to answer, covering only what is still missing. Offer two or three likely options drawn from the context so the user can pick rather than compose. Add these to the same message when they apply:

  • Only when it would change the text: the document type if the request leaves it open, required wording, format, or length, and facts the text needs that are missing (dates, amounts, contacts, conditions).
  • If several audiences will read the document, ask which one is primary. When needs conflict, the standard gives the primary audience priority.
  • In a rewrite, list any source passages whose meaning you cannot pin down. Guessing there can change someone's obligations or rights.
  • If the described readers have serious difficulty reading (for example, a cognitive disability or very limited command of the language), note briefly that ISO 24495-1 separates plain language from easy language, and ask whether to continue with plain language. If they want easy language instead, say that this skill does not apply easy-language rules.

After the answers, proceed. Do not start a second round of questions unless an answer reveals a gap that would make the text wrong. If the user has explicitly told you not to ask, write for the most likely readers, purpose, and situation the context supports.

Step 2: Decide the content (Principle 1)

  • List the questions the readers will bring: what is this, does it affect me, what must I do, by when, how, what happens if I don't, whom do I contact. Answer the ones these readers need; leave out what they don't.
  • Keep content the author is required to include (legal notices, compliance text), but place it so it does not block the main message (5.2.5).
  • Select content ethically: accurate, not misleading, and nothing the reader needs to know hidden or buried. Simplifying never means dropping a condition, fee, deadline, risk, or exception that affects the reader.
  • Do not invent facts. Resolve missing facts needed for a correct, usable text through Step 1. Omit an unknown detail only when the remaining text still serves the reader's purpose accurately.
  • Choose a document type that fits the readers, purpose, and situation. In a rewrite, keep the user's document type and channel unless they ask to change it.

Step 3: Structure and design (Principle 2)

  • Readers should be able to tell at a glance what the text is about and whether it concerns them. Give it a title or subject line that says so when the document type has one.
  • Lead with what most readers need most, usually the main message or the action required.
  • Order the rest by the reader's logic: steps in time order; warnings about what not to do before the steps they protect; information most readers need before information only some need; new information built on what readers already know.
  • Use headings that let readers predict what follows. A heading that states the point or asks the reader's question ("언제까지 신청해야 하나요?", "What happens if I miss the deadline?") does more than a bare label ("신청 기간", "Deadline").
  • Make the structure visible with what the destination supports: numbered steps, short lists, tables for comparisons and values, emphasis for the one or two things that must not be missed, space between groups. Format elements with the same function the same way.
  • Move background, legal detail, and edge cases after the main content or into a clearly labeled section.
  • Scale structure to length. A two-sentence text message needs no headings; a multi-page guide needs headings and often a short summary at the top.

Step 4: Wording (Principle 3)

  • Choose words and expressions that are familiar, precise, and natural for these readers. Replace unfamiliar jargon with a clearer equivalent when it preserves the intended meaning. Use necessary technical or legal terms consistently, and explain them at first use when these readers need help with them. Expand or avoid unfamiliar abbreviations; retain familiar ones when they are clearer.
  • When readers must match, copy, search for, or enter an existing string (such as a button label, path, command, identifier, or error message), reproduce it exactly. Improve the surrounding explanation as needed. This protection does not freeze labels or messages that the user asks you to author or revise.
  • Make each sentence show who does what. Prefer a concrete actor and a verb over abstract nouns. Address readers directly when it fits the document and the language.
  • Keep the main point of each sentence easy to spot rather than buried behind long preambles or stacked conditions. Split sentences that carry several ideas, and cut words that add nothing.
  • Give each paragraph one topic and state it early.
  • Keep a respectful tone: no blaming, threatening, or talking down. Treat readers as capable adults and use inclusive language.
  • Make the text cohesive: consistent terms, references whose target is obvious, transitions that show how parts connect, and consistent formatting.
  • Use tables and worked examples in the text when they help readers understand better than prose. When the requested deliverable includes an image or diagram, provide the finished visual in a format the destination supports.

ISO 24495-1 favors reader success over mechanical measures such as readability formulas, so do not impose fixed targets of your own, such as a maximum sentence length. The IPLF notes that countries can add language-specific practices, such as sentence length, when they adapt the standard. Judge each choice by whether these readers can follow it. If the user's organization or language has its own conventions (a style guide, house terms, mandated wording), follow them.

Language adaptation

Apply each guideline through the natural patterns of the target language instead of importing English habits. For example, a Korean sentence often gets clearer when a chain of Sino-Korean nouns ("서류 제출 시 본인 확인 절차 진행 후 처리") becomes verbs ("서류를 내시면 본인인지 확인한 뒤 처리합니다"), when translationese such as "~에 의해" or "~되어지다" goes, and when the subject and predicate sit close together. In English, the usual moves are active voice where the actor matters, "you" for the reader, and everyday words over formal ones. These are examples of local practice, not ISO rules.

Step 5: Evaluate as you go (Principle 4)

The standard says following Principles 1 to 3 makes a usable text likely, but only evaluation confirms it. You cannot test with real readers, so do the evaluation you can do (5.4.2) before you deliver:

  1. Re-read the draft as the primary reader in their situation, for example skimming on a phone if that is how they will read it.
  2. For each reader question from Step 2, check that the reader can find the answer quickly, understand it on the first read, and act on it without having to contact anyone.
  3. In a rewrite, compare the full source with the draft. Preserve the meaning and accuracy of information readers need and content the author must include. Check that omissions remove only irrelevant or redundant material, and that required exact strings still match. Change wording, order, and structure whenever that serves the reader.
  4. Fix what fails, then check again.

Do not claim that a text "conforms to" or is "certified under" ISO 24495-1. Part 1 offers guidance, and the IPLF states that it is not for certification. Your own check covers only 5.4.2; confirming that readers can use the document also takes evaluation with readers (5.4.3) and of their continued use (5.4.4), which you cannot do here. If the user asks about compliance or testing, explain this and suggest reader-testing methods from references/guidelines.md.

Output

Choose the output language or languages to suit the user's request and intended readers, using the task context when no language is specified.

Write and rewrite modes: deliver only the finished reader-facing text. Include only content that belongs in that document: no preface, summary of changes, checklist, drafting or design notes, placeholders, or other commentary attached to the text. If the user later asks why something changed or wants a check, answer then.

  • Format for the destination. Markdown headings and tables suit documents and web pages. For text messages, chat, or plain-text email, use plain-text structure (line breaks, numbered lines) instead of Markdown syntax.

Review mode: the review is the deliverable. Translate the labels below into the chosen output language, with this structure:

Readers, purpose, and situation: <one line, as confirmed>

Findings (most harmful to readers first)
1. [Principle N, clause and guideline name] Where: <short quote or location>
   Problem: <what goes wrong for the reader>
   Fix: <concrete suggestion, with a short example rewrite when it helps>
2. ...

What already works: <one to three points, only if useful>

Needs checking with real readers: <points that reading alone cannot settle>

Report only problems that affect readers, not cosmetic preferences. Do not rewrite the whole text in review mode unless the user asks. When you name a guideline, cite its clause number and title; do not attribute specific rules such as "always use active voice" to the standard.

Scope

  • ISO 24495-2 (legal communication) and ISO 24495-3 (science writing) add domain guidance on top of Part 1. This skill applies Part 1 only. For legal or science texts, apply Part 1 and keep legally required wording intact.
  • Plain language serves a general audience. Easy language (easy-read) is a separate practice for readers with reading difficulties.
  • Part 1 covers printed or digital information that is mainly text. It does not replace accessibility guidance such as WCAG.