Imported from powerstacks-corp/microsoft-style-skill (SKILL.md). Install upstream with npx skills add powerstacks-corp/microsoft-style-skill. Copyright stays with the author.

Microsoft Writing Style — Audit & Rewrite

You are editing technical documentation to align with the Microsoft Writing Style Guide (https://learn.microsoft.com/style-guide/). PowerStacks publishes its product documentation alongside Microsoft's product documentation; readers expect a consistent voice and terminology between the two. This skill flags and fixes the most common divergences.

Scope

Apply this skill to:

• Technical documentation (docs.powerstacks.com content, install guides, admin guides, troubleshooting docs, API references, README files in product repos, in-product help text)
• Step-by-step procedures
• UI references and product terminology

Do not apply this skill to:

• Marketing copy on powerstacks.com (different voice, different rules — marketing tolerates more personality)
• Blog posts (intentionally have a writer's voice)
• Internal-only documents (Claude memory files, draft notes, internal Slack)
• Mobile-specific content (PowerStacks's audience is at a desk on a computer)

Modes

rewrite (default) — Find Microsoft-style violations and rewrite the content to fix them.

detect — Find violations and report them only; do not rewrite. Use this when:

• The writer wants to see what's flagged and decide what to fix themselves
• You're auditing third-party content that shouldn't be modified
• You want a quick scan without producing a full rewrite

Trigger detect mode when the user says "detect," "audit only," "flag only," "scan," "what's wrong with," or similar. Default to rewrite mode otherwise.

In rewrite mode, your output is:

1. Audit: list each violation with the rule it breaks, citing the specific text
2. Rewrite: a clean version with all violations fixed
3. Diff summary: brief list of what changed and why

In detect mode, your output is just the audit list. No rewrite.

This skill is complementary to the avoid-ai-writing skill. Run both in sequence on docs: avoid-ai-writing first to remove AI patterns, then microsoft-style to align terminology and formatting.

1. Step-by-step instructions — the highest-priority section

Step-by-step instructions are the most common content type in PowerStacks docs and the single biggest source of Microsoft-style divergence. Most rules below apply only to procedure content — heading style and word choice apply elsewhere too.

References:

• https://learn.microsoft.com/style-guide/checklists/procedures-and-instructions-checklist
• https://learn.microsoft.com/style-guide/procedures-instructions/
• https://learn.microsoft.com/style-guide/procedures-instructions/writing-step-by-step-instructions
• https://learn.microsoft.com/style-guide/procedures-instructions/describing-interactions-with-ui
• https://learn.microsoft.com/style-guide/procedures-instructions/formatting-text-in-instructions
• https://learn.microsoft.com/style-guide/procedures-instructions/describing-alternative-input-methods#multiple-input-methods-and-branching-within-procedures

Procedure structure

• Use numbered lists for sequential steps (order matters).
• Use bulleted lists for items that don't have a required order.
• One action per step where possible. Combine only when actions are tightly bound and happen in the same UI location (Select Save, then close the dialog.).
• Don't overload one procedure with too many steps. Try to fit all steps on a single screen. Break long procedures into separate procedures with their own headings.
• Add an introductory step to anchor the customer if the action could happen in multiple places: 1. Open Settings. before subsequent steps.
• Include the completing actions (selecting OK, Apply, Save) — don't leave the customer wondering whether the action committed.

Headings for procedures

• Use a heading to introduce each procedure. The heading should concisely describe what the procedure accomplishes.
• Use parallel structure across sibling procedure headings: Create a profile / Add an account / Delete a profile — all imperative-verb start.
• If an introductory sentence appears between the heading and the numbered list, make sure the introduction adds information the heading doesn't already convey. Don't restate the heading.

"Step N:" headings vs action headings — when to use which

Microsoft uses Step N: headings only when the procedure mirrors a numbered wizard in the product UI itself. For example, the Win32 Intune app deployment doc uses Step 1: App information, Step 2: Program, etc. — those step numbers match the wizard's own tab labels.

For everything else, use sentence-case action headings: Register the application, Add API permissions, Grant admin consent. The procedure's order is implied by the page structure — readers don't need Step N: framing to follow a sequence. Microsoft's quickstart-register-app is the canonical example.

When in doubt, look for the product UI wizard. No numbered wizard → no Step N: headings.

✓ ## Register the application
  (general admin procedure — no product wizard)

✓ ## Step 1: App information
  (matches the Win32 deploy wizard's tab labels exactly)

✗ ## Step 1: Open App registrations in Azure
  ## Step 2: Select New registration
  ## Step 3: Enter a name
  (these are clicks, not phases — collapse into one action heading)

Heading should describe the section's outcome, not the first task within it

If the heading is identical to the first numbered item inside, the heading is too granular. The heading names the phase of work; the numbered items spell out the clicks.

✗ ### Step 7: Select Microsoft Graph
  1. Select Microsoft Graph.

✓ ### Step 2: Add Microsoft Graph permissions
  1. On the app registration page select API Permissions.
  2. Select Add a permission.
  3. Select Microsoft Graph.
  4. Select Application permissions.
  ...

A good test: read the heading aloud, then read the first numbered item. If they say the same thing, the heading is at the wrong granularity.

Reference pages don't use Step headings

A page that explains parameters, options, or configuration is a reference, not a procedure. Use H2 categories with H3 per item, not Step N: framing.

✗ ### Step 4: Configure Sign-Ins Failure Only
  - Required: No
  - Default: TRUE

✓ ## Sign-in data

  ### AzureAD Sign-Ins Failure Only

  **Required:** No
  **Default:** TRUE

  Determines whether successful sign-ins are available in the reports...

Reference content is for lookup, not for following in sequence — the reader needs to scan and jump, not iterate through steps. The page's purpose dictates the structure.

Single-step procedures

A one-step procedure doesn't necessarily need a numbered list. If you want format consistency with the surrounding multi-step procedures, use a bullet instead of a number — never 1. alone.

✓ To move a group of tiles:
  - On the Start screen, zoom out and drag the group to where you want it.

✗ To move a group of tiles:
  1. On the Start screen, zoom out and drag the group to where you want it.

Step writing — sentence structure

• Complete sentences. Capitalize the first word. End with a period.

• Anchor before action — high-priority rule. Make sure the customer knows where the action takes place before you describe the action. This is one of the most-violated rules in technical writing. Microsoft provides two ways to anchor:

  Pattern A — inline location phrase: put the location at the start of the sentence, before the verb.

  ✓ On the Design tab, select Header row.
  ✓ For Alignment, select Left.
  ✗ Select Header row on the Design tab.
  ✗ Select Left for Alignment.

  Pattern B — introductory step: add a separate step that establishes the location, then the action step follows.

  ✓ 1. On the ribbon, go to the Design tab.
    2. Select Header row.

  Use Pattern B when the location matters enough that splitting it out makes the procedure clearer, or when the same location anchors multiple subsequent steps. Use Pattern A when the location is light and only matters for one step.

• Imperative verb first when no location anchor is needed: Open Photos. not You should open Photos.

• Match the UI verbatim. Capitalization, wording, punctuation of UI element names must match what the customer actually sees on screen.

• Don't include the type of UI element (button, checkbox, tab, menu, pane, palette) unless the type adds clarity. Select Save. not Select the Save button.

• Use sentence-style capitalization for UI element names, unless the UI uses something different. Match the UI.

• Drop trailing punctuation from UI labels. If a label ends in : or …, omit it in the procedure step. Select Save as not Select Save as….

✓ 1. Open Settings.
  2. Select Accounts > Other accounts > Add an account.
  3. Enter your email.
  4. Select Sign in.

✗ 1. First, you can open Settings.
  2. Click on the accounts tab, then click on the other accounts tab, then click on the add an account button.
  3. Type in your e-mail address please.
  4. Hit the Sign-in button.

Verbs for UI interactions — the canonical set

Microsoft uses input-neutral verbs that cover mouse, touch, keyboard, voice, and assistive technologies. Don't use input-specific verbs like click, tap, or swipe in general instructions.

Don't talk about the UI — talk about what to do

For dialog boxes, menus, palettes, panes, tabs, toggles, and windows, avoid mentioning the UI element type itself. Describe what the customer needs to do, naming the element by its label in bold only when necessary to disambiguate.

✓ Select Save and continue.
✗ Click the Save and continue button.

✓ In Properties, select Details.
✗ In the Properties dialog box, select the Details tab.

✓ Go to Tools, and select Change language.
✗ On the Tools menu, click the Change language menu item.

When you must refer to a specific UI element by name, use bold for the name. Use sentence-style capitalization unless the UI uses something different (in which case match the UI). Don't include the type (button, dialog, menu, pane, tab, toggle, window) unless it adds clarity.

Elements and conventions — the comprehensive table

This is the canonical Microsoft reference for how to format every text element that appears in instructions. Match exactly.

Multi-input-method procedures

When a procedure needs to support more than one input method (mouse, keyboard, touch, voice), Microsoft offers four patterns. Pick one and stick to it consistently.

1. Use a table with a separate column per input method.
2. Document the primary method, then add the alternative in parentheses or a follow-up sentence: To pan, slide one finger in any direction (or drag the mouse pointer, or use the arrow keys). To copy the selection, click Copy on the toolbar. You can also press Ctrl+C.
3. Use a table comparing whole procedures (one row per approach) if there are multiple ways to complete the same outcome.
4. For a single step with an alternative, separate the alternative into its own paragraph in the step, or use the word or between them.

For input-method-specific verbs:

• Touch-only content uses tap, double-tap, tap and hold, pan, flick, swipe. Don't use tap on or double-tap on. Don't use touch and hold.
• Mouse-only content can use click, double-click, right-click. But for general docs that work across input methods, use select.
• Keyboard procedures should always be documented for accessibility, even if shown in UI.

2. Word choice

Word choice is the second-most-common Microsoft-style violation. For words not on this list, check the full Microsoft A-Z list at https://learn.microsoft.com/style-guide/a-z-word-list-term-collections/.

UI actions and verbs

Microsoft product terminology

Security and access terminology

Plain-language replacements

Anthropomorphism — devices don't have feelings

Direction and reference

Words with multiple meanings or that are dated

3. Capitalization

Microsoft uses sentence-style capitalization almost everywhere. Reference: https://learn.microsoft.com/style-guide/capitalization

The default rule

In headings, titles, UI labels, standalone phrases, and the beginnings of sentences:

• Capitalize only the first word plus any proper nouns.
• Lowercase everything else.

✓ Configure email notifications
✗ Configure Email Notifications

✓ Add the production redirect URI
✗ Add The Production Redirect URI

✓ Sign in and verify
✗ Sign In And Verify

Proper nouns

Always capitalize:

• Product names: Microsoft Intune, Microsoft Entra ID, PowerShell, App Store for Intune, BI for Intune, Power BI
• Service names: Azure SQL Database, Application Insights, Log Analytics
• Brand names, place names, person names

UI element names

Match the UI exactly. If the button label is sentence case in the product, use sentence case. If the label uses title case, use title case.

✓ Select Save and continue.   (UI shows "Save and continue")
✗ Select save and continue.

✓ Navigate to Microsoft Entra ID > Security > Conditional Access.

Title-style capitalization exceptions

Use title-style only for:

• Book titles, e-book titles, white papers, reports
• Game titles, event names, webinar titles
• Article titles in citations
• Names of blogs
• Titles of people: Vice President, Director of Marketing

Title-style rules:

• Capitalize the first and last words.
• Don't capitalize a, an, the unless first word.
• Don't capitalize prepositions of four or fewer letters (on, to, in, up, down, of, for) unless first or last.
• Capitalize all verbs, nouns, pronouns, adjectives, adverbs.

Things to never capitalize

• ALL CAPS for emphasis — use italics sparingly instead.
• all lowercase as a design choice — start sentences with a capital.
• Internal capitalization (AutoScale, e-Book) unless part of an established brand name.
• The spelled-out form of an acronym unless it's a proper noun: virtual private network (VPN), not Virtual Private Network (VPN).

Slash and hyphen compounds

• In a slash compound, capitalize the word after the slash if the word before is capitalized: Country/Region, Turn on the On/Off toggle.
• Hyphenated compounds follow standard rules.

4. Bold usage

Microsoft uses bold for specific structural purposes, not for emphasis. Reference: https://learn.microsoft.com/style-guide/text-formatting/formatting-common-text-elements

Use bold for

• UI elements that the reader interacts with: button labels, menu items, tab names, checkbox labels, dialog names, form field labels.
• Database names (in prose).
• Titles in body content — bold is preferred over italics.
• Key names and keyboard shortcuts in instructions: Shift, Ctrl+Alt+Del.
• The text the user types in command examples or input fields (when called out as user input).

✓ Select **Save** and then select **OK**.
✓ In the **Name** field, enter your tenant ID.
✓ On the **Settings** tab, select **Advanced**.
✓ Press **Alt+F4** to close the window.

Don't use bold for

• Emphasis — use italics sparingly instead. Bold-for-emphasis dilutes the visual signal that bold = UI element.
• Entire sentences or paragraphs — if a whole paragraph is bold, it's not emphasis anymore, it's noise.
• "Important" callouts — use admonition blocks (Note, Tip, Warning) for that.
• Person names.
• Product names — capitalization handles those.

Italics — sparingly

• Emphasis (rarely — usually you can rewrite to make the point).
• Mathematical constants and variables (a² + b² = c²).
• New terms on first mention if you're defining them immediately.

5. Formatting titles and headings

Reference: https://learn.microsoft.com/style-guide/text-formatting/formatting-titles

Titles

• Sentence-style casing for almost all titles. First word capitalized, everything else lowercase except proper nouns.
• Skip end punctuation on titles, headings, subheadings, UI titles, and list items of three or fewer words. Save periods for body content.
• Use bold, not italics, for titles in body content.

✓ Configure Microsoft Teams Bot
✗ Configure Microsoft Teams Bot.

✓ Sign in and verify
✗ Sign In and Verify.

Headings

• Sentence case. First word capitalized.
• Front-load keywords for scannability.

✓ Grant Microsoft Graph permissions to the App Service
✗ How to give Microsoft Graph permissions for the App Service

• Don't end headings with a colon unless the heading literally functions as a label for the content that immediately follows.

Title-style exceptions

Allowed for book titles, white papers, reports, games, events, webinars, formal long-form names. See section 3 for the rules.

6. Voice and tone

Use second person

Address the reader as you. Avoid third person (the user, the administrator) and first person plural (we configure).

✓ You can change the admin group from the Settings tab.
✗ The administrator can change the admin group from the Settings tab.

Use active voice

✓ Microsoft Entra ID validates the token.
✗ The token is validated by Microsoft Entra ID.

✓ Select Save to apply your changes.
✗ Your changes will be applied when Save is selected.

Use present tense

✓ The portal validates the token and grants access.
✗ The portal will validate the token and then access will be granted.

Contractions are encouraged

Microsoft embraces common contractions in technical content: you'll, don't, can't, won't, it's, that's, here's, we're.

✓ You'll see the deploy form open in Azure Portal.

Avoid awkward contractions (wouldn't've, mightn't). Avoid contractions in legal/compliance text and anywhere misreading could mislead.

Don't tell people what they don't need to do

Microsoft (and PowerStacks) docs prefer describing only what's required. Sentences like You don't need to do X or Don't worry about Y add noise. Just don't mention X or Y.

This rule is enforced more strictly by the companion avoid-ai-writing skill.

References:

• https://learn.microsoft.com/style-guide/brand-voice-above-all-simple-human
• https://learn.microsoft.com/style-guide/grammar/person

7. Search writing

For docs that need to surface in search results, structure content for scanners and search engines. Reference: https://learn.microsoft.com/style-guide/search-writing

Title and heading rules

• Front-load the most important keyword in titles and headings.
• Use the specific product name, not a pronoun or generic term.
• Keep titles under ~60 characters where possible.

✓ Configure Microsoft Teams Bot for App Store
✗ Setting up your bot

✓ Grant Microsoft Graph permissions to the App Service
✗ Permissions that need granting

First paragraph

• The first paragraph of every page should contain the most important keyword and answer the page's question directly.
• Don't bury the lead with throat-clearing context.

✓ "App Store for Intune is a full-lifecycle application management platform..."
✗ "Welcome to App Store for Intune! In this guide, you'll learn how to..."

Use customer language, not internal terminology

If customers search for single sign-on, don't title the page SSO configuration. Use the term the customer types.

8. Formatting common text elements (non-procedure docs)

For content outside step-by-step procedures, the conventions for common text elements are simpler. Reference: https://learn.microsoft.com/style-guide/text-formatting/formatting-common-text-elements

For instruction-specific element conventions, see section 1 (Step-by-step instructions).

9. Punctuation — high-frequency rules

Em dashes ( — )

Use sparingly. Microsoft style allows them but prefers commas or sentence breaks where possible. The companion avoid-ai-writing skill flags em dashes as an AI-pattern signal and recommends replacement. Defer to that rule in PowerStacks docs.

When used: closed (no spaces around): She said—and she meant it—the answer was no.

En dashes ( – )

Use only for number or date ranges: pages 5–12, January–March 2026.

Hyphens ( - )

Use for compound adjectives before a noun: multi-factor authentication, read-only file. Microsoft is gradually de-hyphenating common words (email, not e-mail; online, not on-line).

Oxford comma

Use it. Red, white, and blue.

Colons in headings

Avoid unless the heading literally functions as a label.

Reference: https://learn.microsoft.com/style-guide/punctuation/dashes-hyphens

10. Acronyms

• Spell out the full term on first use, with the acronym in parentheses: multi-factor authentication (MFA). Use the acronym afterward.
• Don't capitalize the spelled-out form unless it's a proper noun.
• Avoid acronyms in titles, headings, and the first line of body content unless the acronym is more recognizable than the spelled-out term (URL, HTML, API).
• Microsoft-preferred acronyms not needing spell-out: URL, HTML, API, MFA, SSO, VPN, OS.

Reference: https://learn.microsoft.com/style-guide/acronyms

Workflow

When invoked:

1. Read the content the user provides (or the file they reference).
2. Audit against the rules above, in priority order: step-by-step instructions → word choice → capitalization → bold → titles → voice/tone → search → common text elements → punctuation → acronyms.
3. In rewrite mode: produce the fixed version plus a brief diff summary of what changed.
4. In detect mode: produce only the audit list with each violation cited and the rule it breaks.

If the content already passes all major rules, say so. Don't invent problems.

For anything not covered here, defer to the canonical Microsoft Writing Style Guide: https://learn.microsoft.com/style-guide/.

Pairing with avoid-ai-writing

The avoid-ai-writing and microsoft-style skills are complementary. Recommended order:

1. Run avoid-ai-writing first to strip AI patterns (em dashes, delve into, hollow intensifiers, It's not X — it's Y constructions).
2. Run microsoft-style second to align terminology, capitalization, and formatting.

Some overlap exists (both dislike unnecessary words and indirect phrasing) but the rule sets focus on different problems. The combined pass produces tighter, more Microsoft-aligned docs.