Back to Skills

Writing Style Guide

Defines and enforces writing rules for clarity, structure, formatting, headlines, lists, CTA style, and readability. Use whenever the user writes, edits, audits, or improves any content — including articles, landing pages, emails, social posts, documentation, or marketing copy — even if they don't say 'style guide' explicitly.

Purpose

This skill governs all written content. Every piece of writing — internal or external, short or long — must follow these rules. The goal is not style for its own sake but communication that is understood immediately and acted on confidently.

Core Writing Principles

Clarity first

Write for the reader's comprehension, not the writer's comfort. If a sentence requires a second read, rewrite it.

  • Use concrete language. Replace vague nouns with specific ones: not "solution" but "automated reporting dashboard."

  • One idea per sentence. Split compound sentences that carry more than one claim.

  • Active voice as the default. "The team ships features weekly" — not "Features are shipped weekly by the team."

  • Cut filler. Remove: basically, very, quite, in order to, it is important to note that, as mentioned above.

  • Avoid nominalization. Not "make a decision" → "decide." Not "provide assistance" → "help."

Reader-first perspective

Open every piece by answering the reader's implicit question: "What is this about and why does it matter to me?" Never bury the lead.

Tone of Voice

Context

Tone

Marketing / Landing pages

Confident, direct, human — never hype

Product / Feature copy

Clear, functional, benefit-led

Documentation

Precise, neutral, instructional

Emails

Warm but efficient — no filler greetings

Social / Short-form

Conversational, punchy, no corporate-speak

Never use:

  • Buzzwords without meaning (synergy, leverage, ecosystem, disruptive)

  • Passive constructions to avoid accountability ("Mistakes were made")

  • Exaggerated claims ("the world's best," "revolutionary") unless verifiable

  • Faux-urgency ("Don't miss out!") — urgency must be real and specific

Sentence & Paragraph Structure

  • Sentence length: Average 15–20 words. No sentence exceeds 30 words without a deliberate stylistic reason.

  • Paragraph length: 2–4 sentences for web/marketing. Up to 6 for long-form. One paragraph = one idea.

  • Rhythm: Vary sentence length intentionally. Short punches land harder after longer setups.

  • Transitions: Use them to connect ideas, not to pad text. Prefer: therefore, however, as a result, that means — not additionally, furthermore, moreover (these add weight without adding logic).

Headlines

Headlines are promises. They must tell the reader exactly what they will get — and make them want it.

Rules

  • Lead with the benefit or the action, not the topic label. Not "Team Collaboration" → "Ship faster with one shared workspace."

  • Keep headlines under 60 characters for web/SEO contexts.

  • Use sentence case for body content headlines. Title Case is reserved for product names and formal titles.

  • No punctuation at the end of standalone headlines unless it's a question mark that genuinely fits.

  • Test the "so what?" rule: Read the headline and ask "so what?" If the reader can ask that question and not get an answer from the headline itself, rewrite it.

Headline Hierarchy

  • H1: One per page/document — the primary promise or topic anchor.

  • H2: Major sections — each must stand alone as a meaningful label.

  • H3: Sub-points under H2 — more specific, never orphaned without an H2 parent.

  • H4 and below: Use sparingly; if needed, consider restructuring instead.

Headline Anti-patterns to Reject

  • "Introduction" or "Overview" as an H2 — describe what is introduced instead

  • Headline as a complete essay: "How Our Platform Helps Teams of All Sizes Across Different Industries Work Together More Effectively"

  • Clickbait that the body doesn't deliver: "Everything changes with this one feature"

Lists

Lists exist to make scannable what would otherwise be dense prose. Use them when items are genuinely parallel and discrete — not as a crutch to avoid writing proper sentences.

When to use lists

  • 3 or more parallel items of equal weight

  • Step-by-step instructions where sequence matters

  • Feature comparisons or option sets

When NOT to use lists

  • Two items (write as a sentence: "X and Y")

  • Items with natural connective flow (use prose with transition words)

  • As a substitute for actual structure and argument

List rules

  • Parallel construction is mandatory. All items in a list must start with the same grammatical form — all verbs, all nouns, all clauses.

    • Wrong: "Fast onboarding, you can integrate APIs, and support is included"

    • Right: "Fast onboarding, flexible API integration, and included support"

  • Lead with the key word. Put the most important word first in each item, not at the end.

  • No full stop on list items unless one item contains multiple sentences (then punctuate all items).

  • Maximum 7 items per list. Beyond that, group into subsections.

  • No nested lists in marketing or user-facing content. In documentation, a maximum of one level of nesting is permitted.

Formatting

Bold and Italics

  • Bold = genuinely critical information, key terms on first use, UI labels

  • Italics = titles of works, foreign words, or subtle emphasis — sparingly

  • NEVER use bold for decoration or to make a paragraph "look important"

Code and Technical Strings

  • Wrap all code, commands, file names, and API parameters in code formatting

  • Never substitute visually similar characters (e.g., use — not -- in prose)

Numbers

  • Spell out one through nine; use numerals for 10 and above

  • Always use numerals for: measurements, percentages, prices, statistics

  • Thousands separator: 1,000 — not 1000

Dates

  • Written format: 17 June 2026 (no ordinal suffixes: not "17th")

  • Abbreviated: 17 Jun 2026

  • ISO in technical contexts: 2026-06-17

Capitalization

  • Sentence case throughout (capitalize first word + proper nouns only)

  • Product names: follow official brand capitalization exactly

  • Job titles: lowercase when used generically (the marketing manager), capitalize when used as a direct title before a name (Marketing Manager Jane Smith)

CTA (Call-to-Action) Style

CTAs are the single most important sentence or phrase in any conversion-oriented piece. They must be specific, immediate, and low-friction.

CTA Rules

  • Use a verb. Every CTA starts with an action word: Start, Get, Download, Try, Book, See, Join.

  • Be specific. Not "Learn more" → "See how the integration works." Not "Sign up" → "Start your free 14-day trial."

  • State the outcome, not the action. Not "Click here" → "Get your personalized report."

  • Match urgency to reality. Only use time-pressure language ("Today only," "Limited spots") when it is factually true.

  • One CTA per section. Multiple competing CTAs dilute conversion. If a second CTA is needed, it must be clearly secondary in visual weight and copy.

  • Micro-copy below CTAs: Reduce friction with one short reassurance line — No credit card required. Cancel anytime. Free for 30 days.

CTA Anti-patterns

  • "Click here" (non-descriptive, inaccessible)

  • "Submit" on form buttons (replace with the outcome: "Send my request")

  • "Learn more" without context (acceptable only when the context is crystal clear from surroundings)

Readability Standards

Target Flesch-Kincaid Grade 8–10 for general web content. Documentation and technical writing may go higher; marketing copy should target Grade 6–8.

Practical readability rules

  • Maximum syllables per word (on average): Keep polysyllabic words to under 20% of total word count

  • Jargon: Define on first use or replace with plain language. If a term requires explanation, ask whether it belongs at all

  • Acronyms: Spell out in full on first use, then abbreviate: Conversion Rate Optimization (CRO)

  • Reading-level test: After drafting, read the piece aloud. Anything you stumble over is a rewrite candidate

Clarification — When to Ask

Ask before starting only when:

  • The target audience is unknown → "Who is the primary reader — expert, general audience, or mixed?"

  • The content type is ambiguous → "Is this for a landing page, email, internal doc, or social post?"

  • A brand voice override is in effect → "Should this follow a specific voice profile different from the default?"

Never ask about:

  • Whether to use active voice — always use it unless the user specifies otherwise

  • Whether to apply formatting rules — always apply them

  • Which headline style to use — always sentence case unless instructed otherwise

Process

When writing or editing any piece of content:

  1. Identify the content type (marketing, documentation, email, social, etc.) and apply the corresponding tone

  2. Check the headline — does it pass the benefit test and the 60-character rule?

  3. Scan for passive voice and convert to active

  4. Check all lists for parallel construction and appropriate length

  5. Review CTAs — do they start with a verb and state a specific outcome?

  6. Read aloud — flag any sentence you stumble over and rewrite it

  7. Apply formatting rules — bold, lists, numbers, capitalization

When auditing existing content, deliver a structured review with:

  • Summary verdict (pass / needs revision / major rewrite required)

  • Specific issues flagged by category (Clarity / Headlines / Lists / CTA / Formatting / Readability)

  • Corrected version or targeted rewrites for each flagged section

Output Format

For new content: Deliver the final copy directly, formatted and ready to use. No meta-commentary unless the user asked for explanation.

For content audits:

## Writing Audit

**Overall Verdict:** [Pass / Needs Revision / Major Rewrite]

### Clarity
- [Issue] → [Suggested fix]

### Headlines
- [Issue] → [Suggested fix]

### Lists
- [Issue] → [Suggested fix]

### CTA
- [Issue] → [Suggested fix]

### Formatting
- [Issue] → [Suggested fix]

### Readability
- Grade level estimate: [X]
- [Issue] → [Suggested fix]

---
**Revised Version**
[Full corrected text]