skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
hash-id/openspec-schema99 installs

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-writing
view source ↗

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

  1. Sentence length. Roughly 20 words or fewer. Split anything longer.

  2. One clause per sentence. No "and/but/which" joining two distinct ideas.

  3. No idioms, metaphors, or humor. Say it literally (not "let's dive in," "heads up," "ballpark").

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

  5. 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).

  1. No vague or escape-clause words. Avoid "adequate," "reasonable," "as appropriate," "where possible," "etc." State a measurable criterion or an explicit list instead.
  2. One obligation or decision per sentence. Don't join two requirements or decisions with "and/or."
  3. No ambiguous pronoun. Same condition as COMMS #4.
  4. Normative keywords stay in requirement blocks. SHALL/MUST/SHOULD in ALL CAPS only inside an actual ### Requirement statement — never capitalized in narrative prose (proposal.md, design.md rationale).
  5. 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").

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>