Plain Language for AI Agents

An agent skill that helps LLMs write documents conforming to ISO 24495-1:2023 — the international standard for plain language.

Tuned for internal technical writing: memos, RFCs, PRDs, design docs, runbooks, postmortems, and one-pagers. Works in any harness that follows the Agent Skills standard — Claude Code, Cursor, Codex, Copilot, Gemini CLI, Goose, OpenCode, and 25+ others.

MIT licensed. No dependencies.

Contents

1. What the skill does
2. Install
3. Before and after
4. The four principles
5. Anti-patterns the skill blocks
6. Document types
7. Repository layout
8. Contributing
9. FAQ
10. License

What the skill does

When loaded into an agent, the skill:

1. Prompts the agent to identify readers, purpose, context, and format before drafting.
2. Enforces a reader-first structure — the ask at the top, warnings before instructions, team-owned sections, supporting detail last.
3. Applies the language rules from ISO 24495-1:2023 clauses 5.3.2 to 5.3.8: familiar words, one idea per sentence, active voice, consistent terminology, respectful tone, cohesive drafting.
4. Runs a 42-item self-review checklist before delivering the document.
5. Provides an adaptive template for common technical document types.

The skill does not push reader testing for internal memos. It is available for the rare external document that warrants it.

Install

The skill is distributed through the skills CLI.

npx skills add nikdumroese/plain-language-skill

The CLI detects which agents you have installed and offers to install for each. To try the skill without installing:

npx skills use nikdumroese/plain-language-skill@plain-language-iso-24495

Once installed, invoke by asking for a document ("draft a decision memo for X") or a rewrite ("rewrite this using plain language").

No terminal (Claude.ai)

1. Download SKILL.md.
2. In Claude.ai (paid plan), open Settings → Capabilities and turn on code execution.
3. Open Settings → Customize → Skills → Upload and upload the file.
4. Turn the skill on.

No skill support (ChatGPT, Gemini, other)

Copy prompts/system-prompt.md into the platform's custom-instruction field.

Before and after

The folder examples/ contains real samples generated by the same model with and without the skill. Neither run has access to CLAUDE.md, auto-discovered skills, or project context. The only difference is whether the skill is in the system prompt.

The script that produced them is at evals/run.sh. It auto-detects available runners in this order: pi, claude, codex. Override with:

RUNNER=claude ./evals/run.sh
MODEL=claude-opus-5 ./evals/run.sh

One effect the skill produces

For a prompt with missing reader information, the model asks for it before drafting instead of making assumptions.

Prompt used:

Write a memo asking leadership to approve migrating payment processing from Stripe to Adyen. It saves cost, improves European latency, takes six weeks. Legal, Security, and Finance need to sign off.

Baseline output (excerpt):

Recommendation

Approve migrating our payment processing from Stripe to Adyen. The migration will take six weeks and requires sign-off from Legal, Security, and Finance before we start.

Why we should switch

Lower cost. Adyen's pricing will reduce our payment processing fees.

Faster payments in Europe. Adyen processes European transactions closer to our customers, cutting latency and improving checkout speed for EU users.

With-skill output (excerpt):

Before I draft this, I need a few concrete details — plain language requires numbers, not vague claims, and the standard says to confirm the reader before writing.

1. Numbers: What's the actual cost saving and the actual latency improvement? I won't write "significant savings" or "faster" — I need figures or a placeholder you'll fill in.
2. Primary reader: Is this memo aimed at one leader who makes the final call, with Legal/Security/Finance as required sign-offs? Or is it a joint decision by all three plus leadership?
3. Project owner: Who owns the migration itself — the person Legal/Security/Finance should route questions to?
4. Risk/warning: Is there anything the reader must know before approving — downtime window, dual-running period, contract termination cost with Stripe?
5. Response mechanism: How should each of Legal, Security, and Finance respond — reply in a thread, sign a form, attend a meeting? And by when?

The baseline invents plausible content. The skill refuses to write until it has the reader, the numbers, and the response mechanism.

For an RFC prompt with more content, the baseline produces a generic RFC. The skill produces a structured document with a multi-audience routing block, per-team action items with time estimates, an alternatives-considered table, and explicit success criteria. Full outputs: examples/generated-before-after.md.

The four principles

ISO 24495-1:2023 defines plain language through four principles. A document conforms if readers can:

Principle	Reader can	What the skill enforces
Relevant	Get what they need	Reader identification before drafting. Format check. Cut content the reader does not need.
Findable	Easily find what they need	The ask at the top. Warnings before instructions. Team-owned sections. Supplementary detail last. Scannable headings.
Understandable	Easily understand what they find	Short sentences. One idea per paragraph. Active voice. Familiar words. Consistent terminology. Diagrams where prose is unclear.
Usable	Easily use the information	Explicit response mechanism. Self-review checklist. Date, version, and author in the header.

Full detail: references/principles.md.

Anti-patterns the skill blocks

Most plain-language guidance was written for public-sector notices. This skill is tuned for the failure modes specific to internal technical documents.

Structure

• Starting with background or context. The ask goes first.
• "TL;DR" tags. Use a plain headline.
• Rhetorical questions as headings.
• Nested lists deeper than two levels.
• Meta-content about the document itself ("This document will explain...").

Attribution

• Personalising sections with names ("For Jane Doe"). People move; roles persist.
• Ownership by more than one team without a named primary owner.
• Author-centric framing ("I want to propose...", "We have been thinking...").

Language

• Marketing verbs: leverage, synergise, empower, unlock, drive.
• Weasel words: we believe, arguably, potentially, somewhat.
• Vague timing: soon, recently, in the coming weeks. Use dates.
• Modal verbs used interchangeably. The skill follows RFC 2119: must, should, may are defined terms.
• Chained acronyms ("SRE-owned CI/CD via IaC"). Unreadable even when each acronym is defined.
• Synonyms for the same concept in the same document.

Content

• Stating a constraint without its reason ("we must use PostgreSQL" — why?).
• Vague success criteria ("we will monitor and iterate").
• Vague review requests ("please review and provide feedback").
• Strawman comparisons. Compare to real alternatives.
• Missing dates, version, or author in the header.

Tone

• Performative politeness — "please" every paragraph, "thank you for your time".
• Passive-aggressive framing ("as has been repeatedly mentioned...").
• Manufactured consensus ("we all agree that...").

Full list in SKILL.md.

Document types

The template is shaped as a decision memo. The skill adapts it for:

Type	Adaptation
Decision memos, approval requests	Default shape.
RFCs, design docs	"How to respond" becomes a comment thread or decision meeting.
Runbooks	Condition before command. Warnings before instructions.
Postmortems	Concrete times, actions, follow-up tickets.
One-pagers	Reader-first structure at any length.

Not suitable for: marketing copy, blog voice, brand writing.

Repository layout

skills/plain-language-iso-24495/
├── SKILL.md                     # Workflow, deliverables, anti-patterns
├── references/
│   ├── principles.md            # ISO 24495-1:2023 principles and guidelines
│   ├── checklist.md             # 42-item pre-flight self-review
│   └── reader-test.md           # Reader evaluation for external documents
└── assets/
    └── template.md              # Adaptive starting template

evals/run.sh                     # Regenerate before/after samples
examples/                        # Generated samples committed for reference
prompts/system-prompt.md         # For harnesses without skill support

Contributing

Issues and pull requests welcome at github.com/nikdumroese/plain-language-skill.

Useful contributions:

• Anti-patterns the skill misses.
• Document types the template does not cover well.
• Runners the eval script should support.
• Corrections to the paraphrased principles.

Before opening a pull request, re-run ./evals/run.sh and confirm the with-skill output still differs from the baseline as expected.

FAQ

Does the skill produce ISO-certified output? No. ISO does not certify tools or output. The skill applies the principles and guidelines from ISO 24495-1:2023 as an author would.

Does it replace ASD-STE100 (Simplified Technical English)? No. ASD-STE100 is for technical procedures where a misread instruction can cause harm — aircraft manuals, safety-critical runbooks. This skill is for documents where readers must find, understand, and act — memos, RFCs, decision documents.

Does it test documents with real readers? Not for internal memos. Reader testing is proportionate for external documents: public terms, customer policy, regulator submissions. The file reader-test.md describes how to run one when it is warranted.

Will the output sound robotic? No. Plain language is not simplified language. It is language shaped for the reader's time. The output reads like a well-written internal memo — direct, structured, specific.

Why not just prompt "write clearly"? "Clearly" is an opinion. "The ask appears in the first screen" and "one term per concept" are specifications. Models follow specifications.

License

MIT. The repository paraphrases the ISO 24495-1:2023 principles for teaching purposes and reproduces no normative text. Unofficial project, not affiliated with or endorsed by ISO. ISO 24495-1:2023 is copyright ISO.