Microsoft Writing Style Guide

Purpose

Apply the Microsoft Writing Style Guide to documentation, UI text, error messages, notifications, marketing copy, emails, slides, procedures, developer content, and conversational experiences.

Microsoft voice is warm and relaxed, crisp and clear, and ready to lend a hand. Use bigger ideas and fewer words. Write with less head and more heart.

This skill is a pinned, offline reference snapshot. See references/source-manifest.md for its authoritative source commit, coverage, and synchronization date.

When to use

Use this skill to:

• Draft content in Microsoft voice.
• Rewrite content for clarity, brevity, accessibility, or global readiness.
• Review content for Microsoft style violations.
• Resolve a specific term, spelling, capitalization, or UI-language question.
• Check procedures, developer documentation, bot content, or error messages.

Don't use it to:

• Rewrite legal or contractual text without legal review.
• Change code identifiers, API syntax, commands, URLs, or literal UI text.
• Replace a product's documented naming conventions.
• Impose Microsoft voice on content for another brand.

Choose a mode

If the user requests more than one mode, do them in this order: review, rewrite, write. Use term lookup whenever another mode encounters a questionable term.

Source precedence

Use the most specific applicable guidance:

1. Exact A-Z term entry.
2. Relevant term collection.
3. Topic guidance and content-type rules.
4. Checklist.
5. Quick-reference guidance in this file.

Match literal UI, code, and product names when the task requires it. If two rules appear to conflict, prefer the more specific rule and explain the exception only when it affects the result.

For a rule that may have changed after the synchronization date, verify the live Microsoft Writing Style Guide when live access is available. Otherwise, disclose the snapshot date if freshness is material to the answer.

Load only what you need

Never load the full corpus by default.

Term lookup

1. Search references/term-index.tsv for the canonical term.
2. Load the routed A-Z file and read the complete matching ### section.
3. If the term isn't indexed, search the applicable term collection.
4. Return the preferred form, rule, example, and reference heading.

Example search:

rg -i '^plugin\t|^plug-in\t' references/term-index.tsv

Topic routing

Apply the selected mode

Term lookup

Return:

• Use: the preferred form.
• Guidance: the rule and important exceptions.
• Example: one correct example when useful.
• Source: the reference file and heading.

Don't infer a rule from spelling alone. Read the complete term entry.

Write

1. Identify the audience, content type, intended action, and space constraints from the request.
2. Load the smallest relevant reference set.
3. Draft the content with the important information first.
4. Check terminology, accessibility, global readiness, and the applicable checklist.
5. Return the finished content. Mention assumptions only when they materially affect the result.

Rewrite

1. Preserve facts, intent, required terminology, placeholders, code, and literal UI strings.
2. Fix explicit Microsoft-style violations.
3. Improve structure, clarity, brevity, and scanability without flattening the meaning.
4. Return the revised content first.
5. Follow with a short Material changes list. Omit it when the user asks for only the revised text.

Review

Review the content type and audience before applying rules. Run the applicable checklist, look up questionable terms, and deepen the review only in areas that the quick scan flags.

Use these severities:

For each finding, provide:

### [Severity] Short finding

**Text:** "Exact problematic text"
**Fix:** "Exact replacement text"
**Rule:** Category and reference heading
**Why:** One concise explanation

Group repeated instances of the same issue. Omit empty severity sections. If the content has no material issues, say so—don't invent findings.

Quick reference

Guardrails

• Don't alter technical meaning to satisfy a style preference.
• Don't replace exact UI text with the preferred generic term.
• Don't flag an exception as a violation.
• Don't claim factual, legal, security, or product accuracy from a style review.
• Don't load or quote large reference sections when a concise answer is enough.
• Cite the reference file and heading when explaining a disputed rule.