text-style-guide

name	text-style-guide
description	Apply a consistent writing style for course and documentation text. Use for drafting, editing, and reviewing copy for clarity, tone, structure, accessibility, and consistency.
argument-hint	What text should be drafted or edited, and who is the audience?

Text Style Guide Workflow

What This Skill Produces

• Consistent, readable text aligned to this project style.
• A repeatable edit workflow for new and existing content.
• A quality checklist for clarity, tone, structure, and accessibility.

When To Use

• Writing new lesson sections, callouts, or documentation.
• Editing existing pages for consistency.
• Reviewing copy before release.
• Normalizing mixed writing styles across files.

Required Inputs

• Target audience and prior knowledge level.
• Text purpose (inform, instruct, warn, summarize).
• Desired output format (lesson section, callout, checklist, docs page).
• Any fixed terms or product names that must remain unchanged.

Style Defaults

• Audience-first plain language.
• Short paragraphs and concrete wording.
• Sentence-case headings.
• Action-oriented instructions.
• Accessible wording with minimal jargon.
• Bullet points with no full stops

Workflow

1. Define intent and audience.
2. Set structure before sentence-level edits.
3. Rewrite for clarity and directness.
4. Normalize terms, tone, and formatting.
5. Run accessibility and readability checks.
6. Final pass with definition-of-done checks.

Detailed Procedure

1) Define intent and audience

• Identify who will read the text and what they should do after reading it.
• Set complexity level for non-expert readers unless asked otherwise.
• Capture one primary outcome for the text block.

Decision points:

• If audience knowledge is unclear, default to novice-friendly wording.
• If there are multiple outcomes, split into separate sections.

Completion checks:

• The text has one clear purpose.
• The audience and expected action are explicit.

2) Set structure before sentence-level edits

• Use descriptive headings in sentence case.
• Prefer short sections with one idea each.
• Use lists for steps, criteria, or options.

Decision points:

• If a paragraph exceeds 4 to 5 lines, split it.
• If sequence matters, use numbered lists; otherwise use bullets.

Completion checks:

• Information order matches reader workflow.
• Structure is scannable on desktop and mobile widths.

3) Rewrite for clarity and directness

• Replace abstract language with concrete actions.
• Prefer active voice and specific verbs.
• Remove filler and repeated ideas.

Decision points:

• If a sentence has more than one key idea, split it.
• If jargon is necessary, define it at first use.

Completion checks:

• Each sentence is unambiguous.
• Steps and guidance can be followed without extra interpretation.

4) Normalize terms, tone, and formatting

• Keep terminology consistent across files.
• Keep tone practical, calm, and instructional.
• Use consistent naming for UI elements and workflows.

Decision points:

• If two terms refer to the same concept, choose one and standardize.
• If tone shifts between sections, align to the section objective.

Completion checks:

• No conflicting terms for the same concept.
• Formatting patterns are consistent with nearby content.

5) Run accessibility and readability checks

• Ensure meaningful link text and descriptive labels.
• Avoid idioms and culturally specific shorthand when possible.
• Keep reading flow logical with clear transitions.

Decision points:

• If a reader must infer critical context, add explicit context.
• If a list item is too long, split into lead-in plus short items.

Completion checks:

• Text is understandable for non-specialist readers.
• Link and control text are descriptive without surrounding context.

6) Final pass with definition-of-done checks

• Re-read from top to bottom for flow and consistency.
• Confirm content meets intended outcome and scope.
• Trim non-essential text once clarity is preserved.

Completion checks:

• Purpose, audience, and action are clear.
• Heading style and term usage are consistent.
• Copy is concise, accessible, and ready to publish.

Definition Of Done

• The text is easy to scan and easy to act on.
• Headings use sentence case and sections are coherent.
• Terminology is consistent and jargon is controlled.
• Instructions are explicit and testable.
• Accessibility-focused language checks pass.

Example Prompts

• Apply the text-style-guide skill to rewrite this lesson for non-coders.
• Review these three course sections and standardize tone and terminology.
• Convert this long explanation into concise step-by-step guidance.