plain-language-writing
Two writing rule sets for readers who may not read English fluently: COMMS for live agent-to-user text (interview questions, confirmations, blockers), ARTIFACT for persistent artifact prose (proposal.md, specs, design.md). A caller states which set applies. Evidence backing is in docs/research/2026-08-07-plain-language-non-native-readers.md.
How do I install this agent skill?
npx skills add https://github.com/hash-id/openspec-schema --skill plain-language-writingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides stylistic guidelines for plain language writing and does not contain any executable code or security risks.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
plain-language-writing
Two independent rule sets. A caller states which one applies — COMMS for text read once, live, in the moment; ARTIFACT for prose in a persistent file that gets re-read and reviewed. Don't cross-apply them; they're tuned for different reading conditions.
These rules operationalize standards with credible backing (ISO 24495-1, Kimble's plain-language work, EARS, INCOSE's Guide for Writing Requirements) but aren't each individually proven — treat them as the best currently-evidenced approach, not a guaranteed fix. See the research doc above for what's well-supported (the pronoun rule, COMMS #4 / ARTIFACT #3) versus reasonable-but-unproven. COMMS #5 (structure) has no empirical backing at all — an earlier version of it (A5) was dropped from the research for lack of evidence; it's kept here only as a stylistic default, not a proven rule.
COMMS — live agent-to-user text
Interview questions, confirmation/recap prompts, status updates, walkthrough questions, blocker/pause/stop messages.
-
Sentence length. Roughly 20 words or fewer. Split anything longer.
-
One clause per sentence. No "and/but/which" joining two distinct ideas.
-
No idioms, metaphors, or humor. Say it literally (not "let's dive in," "heads up," "ballpark").
-
No ambiguous pronoun. When a sentence introduces two things of similar weight, don't refer back with "it/this/that" — name the one you mean. Doesn't require eliminating every pronoun, only where more than one referent is plausible.
-
Causal/multi-step explanations use labeled structure, not a dense paragraph. When explaining a root cause or a multi-step process (why something failed, what happens as a result), break it into short ALL-CAPS section labels plus numbered steps or IF/THEN for branching logic. Doesn't apply to short interview questions or one-line status updates — those stay as plain sentences; forcing structure onto them reads as stilted.
Shape to follow:
PROBLEM. <one or more sentences naming what's wrong> WHY THIS HAPPENS. <mechanism, as numbered steps if there's a sequence> 1. ... 2. ... THE ROOT CAUSE. IF <condition> THEN <result>. IF <other condition> THEN <other result>. CONCLUSION. <one sentence confirming or correcting the user's read> NEXT STEP. <what happens next, or what's still open>
ARTIFACT — persistent artifact prose
Free-running prose in proposal.md, specs/*.md, design.md, tasks.md, align.md. Never overrides the structural formats those artifacts already mandate (### Requirement / #### Scenario blocks, WHEN/THEN, checkbox syntax, delta-operation headers, SHALL/MUST usage).
- No vague or escape-clause words. Avoid "adequate," "reasonable," "as appropriate," "where possible," "etc." State a measurable criterion or an explicit list instead.
- One obligation or decision per sentence. Don't join two requirements or decisions with "and/or."
- No ambiguous pronoun. Same condition as COMMS #4.
- Normative keywords stay in requirement blocks. SHALL/MUST/SHOULD in ALL CAPS only inside an actual
### Requirementstatement — never capitalized in narrative prose (proposal.md, design.md rationale). - One term per concept. Reuse the same name across proposal.md, specs/*.md, design.md, and tasks.md — don't drift between synonyms (e.g. "user" / "actor" / "consumer").
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/hash-id/openspec-schema/plain-language-writing">View plain-language-writing on skillZs</a>