Add a repository-scoped Microsoft writing style skill

[Brett Wilson (MSBrett)]

🛠️ Description

Vendor the microsoft-writing-style-guide Agent Skill under .claude/skills so Claude Code and GitHub Copilot CLI share the same repository-scoped writing guidance. Update AGENTS.md to direct content-string work to the vendored skill instead of relying only on automatic discovery.

The skill is installed from msbrettorg/microsoft-writing-style and pinned to commit d9227efa6c984c13260e3bf869f4b6132cfb3c19. GitHub CLI provenance metadata records the source path, commit, and tree SHA, and prevents routine updates from changing the snapshot.

Fixes #2275

📋 Checklist

🔬 How did you test this change?

• 🤏 Lint tests
• 🤞 PS -WhatIf / az validate
• 👍 Manually deployed + verified
• 💪 Unit tests
• 🙌 Integration tests

The bundled offline validator and its self-check pass. The pinned skill is discoverable through gh skill list, and gh skill update --dry-run skips it as expected.

📦 Deploy to test?

• Hubs + ADX (managed)
• Hubs + Fabric (manual) — URI: N/A
• Hubs (manual)
• Hubs (no data)
• Workbooks
• Alerts

🙋‍♀️ Do any of the following that apply?

• 🚨 This is a breaking change.
• 🤏 The change is less than 20 lines of code.

📑 Did you update docs/changelog.md?

• ✅ Updated changelog (required for dev PRs)
• ➡️ Will add log in a future PR (feature branch PRs only)
• ❎ Log not needed (small/internal change)

📖 Did you update documentation?

• ✅ Public docs in docs (required for dev)
• ✅ Public docs in docs-mslearn (required for dev)
• ✅ Internal dev docs in docs-wiki (required for dev)
• ✅ Internal dev docs in src (required for dev)
• ➡️ Will add docs in a future PR (feature branch PRs only)
• ❎ Docs not needed (small/internal change)

[Copilot]

Pull request overview

This pull request vendors a repository-scoped microsoft-writing-style-guide Agent Skill under .claude/skills so local agent tooling (Claude Code / GitHub Copilot CLI) can apply consistent Microsoft Writing Style guidance offline.

Changes:

• Add the pinned skill entrypoint (SKILL.md) plus a set of consolidated reference markdown files and a canonical term index.
• Add an offline validator (scripts/validate.py) and representative evals (evals/evals.json) to verify the snapshot shape and freshness.
• Record provenance/source metadata in references/source-manifest.md.

Reviewed changes

Copilot reviewed 24 out of 25 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
.claude/skills/microsoft-writing-style-guide/SKILL.md	Defines the skill metadata and usage workflow (modes, routing, guardrails).
.claude/skills/microsoft-writing-style-guide/evals/evals.json	Adds expected-behavior eval prompts for the skill.
.claude/skills/microsoft-writing-style-guide/scripts/validate.py	Adds an offline validator to ensure snapshot integrity (term inventory, sentinels, etc.).
.claude/skills/microsoft-writing-style-guide/references/a-z-term-list-a-c.md	Vendored A–Z term guidance (A–C) for term lookup routing.
.claude/skills/microsoft-writing-style-guide/references/a-z-term-list-d-g.md	Vendored A–Z term guidance (D–G) for term lookup routing.
.claude/skills/microsoft-writing-style-guide/references/a-z-term-list-h-m.md	Vendored A–Z term guidance (H–M) for term lookup routing.
.claude/skills/microsoft-writing-style-guide/references/a-z-term-list-n-r.md	Vendored A–Z term guidance (N–R) for term lookup routing.
.claude/skills/microsoft-writing-style-guide/references/a-z-term-list-s-u.md	Vendored A–Z term guidance (S–U) for term lookup routing.
.claude/skills/microsoft-writing-style-guide/references/a-z-term-list-v-z.md	Vendored A–Z term guidance (V–Z) for term lookup routing.
.claude/skills/microsoft-writing-style-guide/references/accessibility-and-bias-free-communication.md	Adds accessibility and inclusive-language guidance references.
.claude/skills/microsoft-writing-style-guide/references/checklists.md	Adds quick checklists for audits/reviews.
.claude/skills/microsoft-writing-style-guide/references/content-planning-and-process.md	Adds content planning/process reference material.
.claude/skills/microsoft-writing-style-guide/references/developer-and-bot-content.md	Adds developer documentation + bot/VA style guidance references.
.claude/skills/microsoft-writing-style-guide/references/global-communications.md	Adds global-ready writing guidance references.
.claude/skills/microsoft-writing-style-guide/references/grammar-and-parts-of-speech.md	Adds grammar/person/voice guidance references.
.claude/skills/microsoft-writing-style-guide/references/keys-and-keyboard-shortcuts.md	Adds keyboard/key naming term collection references.
.claude/skills/microsoft-writing-style-guide/references/numbers-acronyms-capitalization.md	Adds numbers/acronyms/capitalization guidance references.
.claude/skills/microsoft-writing-style-guide/references/punctuation.md	Adds punctuation guidance references.
.claude/skills/microsoft-writing-style-guide/references/scannable-content-and-procedures.md	Adds scanability + procedures guidance references.
.claude/skills/microsoft-writing-style-guide/references/source-manifest.md	Captures snapshot provenance/coverage and support artifacts.
.claude/skills/microsoft-writing-style-guide/references/term-collections-numbers-symbols.md	Adds term-collection reference material for symbols/number-related terminology.
.claude/skills/microsoft-writing-style-guide/references/term-index.tsv	Adds the canonical term routing index used for lookup.
.claude/skills/microsoft-writing-style-guide/references/text-formatting.md	Adds text formatting/type-treatment guidance references.
.claude/skills/microsoft-writing-style-guide/references/word-choice.md	Adds word-choice guidance references.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 27 out of 28 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 27 out of 28 changed files in this pull request and generated no new comments.

Suppressed comments (8)

Previously missed (7) — in code that hasn't changed since the last review.

.claude/skills/microsoft-writing-style-guide/scripts/validate.py:160

• A TSV row with a missing field is loaded by csv.DictReader with a None value, so the subsequent normalize() or digest() call raises instead of reporting validation errors. Validate each row before processing it so a damaged term index cannot crash the offline validator.

                rows = list(reader)

.claude/skills/microsoft-writing-style-guide/references/a-z-term-list-a-c.md:883

• The Learn-specific :::image directives are unresolved in this offline snapshot, and the referenced media file isn't included, so agents see raw conversion markup in both examples. Replace the directives with readable text descriptions or include locally resolvable media.

**Examples** Select the **Close** button :::image type="icon" source="media/close-button/1581618122.png":::. Select **Close** :::image type="icon" source="media/close-button/1581618122.png":::.

.claude/skills/microsoft-writing-style-guide/references/a-z-term-list-s-u.md:433

• These Start-icon examples retain Learn-specific :::image directives whose media isn't part of the vendored skill, so the offline reference exposes raw markup instead of the intended icon. Replace both directives with readable text descriptions or bundle locally resolvable media.

If possible, to help customers locate the button, include the Start graphic :::image type="icon" source="media/start-button-start-menu/967781121.png"::: in references to the Start button.

**Example** You'll find the Start :::image type="icon" source="media/start-button-start-menu/967781121.png"::: button on the taskbar.

.claude/skills/microsoft-writing-style-guide/references/scannable-content-and-procedures.md:525

• This example retains a Learn-specific :::image directive, but the referenced Search icon isn't included in the offline skill. Replace the directive with readable text or a locally resolvable image so agents don't consume raw conversion markup.

This issue also appears on line 527 of the same file.

|            **Go to**            |                                                                                                                                    <ul><li>Opening a menu.</li></ul> <ul><li>Going to a tab or another particular place in the UI.</li></ul> <ul><li>Going to a website or webpage.</li></ul> <br>It's OK to use <em>On the</em> <strong><em>XXX</em></strong> <em>tab</em> if the instruction is brief and continues immediately.                                                                                                                                    | <ul><li>Go to Search :::image type="icon" source="media/describing-interactions-with-ui/721771267.png":::, enter the word <strong>settings</strong>, and then select <strong>Settings</strong>. </li></ul> <ul><li>Go to <strong>File</strong>, and then select <strong>Close</strong>.</li></ul> <ul><li>On the ribbon, go to the <strong>Design</strong> tab. </li></ul> <ul><li>Go to the <strong>Deploy</strong> tab. In the <strong>Configuration</strong> list … </li></ul> <ul><li>On the <strong>Deploy</strong> tab, in the <strong>Configuration</strong> list … </li></ul> <ul><li>Go to Example.com to register.</li></ul> |

.claude/skills/microsoft-writing-style-guide/scripts/validate.py:132

• The unresolved-image check only recognizes !Image/!Screenshot, so the seven :::image ...::: directives still present in the reference files pass validation even though their media isn't vendored. Extend this detector and its self-check to cover Learn :::image markup after replacing the current occurrences.

        if re.search(r"!(?!\[)(?:image|screenshot)\b", text, re.I):
            errors.append(f"UNRESOLVED_IMAGE: {path.relative_to(root)}")

.claude/skills/microsoft-writing-style-guide/references/grammar-and-parts-of-speech.md:48

• Each list item closes the <ul> before the <li>, producing invalid HTML in this table cell. Close the list item first so the passive-voice use cases render consistently.

| **Passive** | <ul><li>Avoiding condescending text or blaming the customer, especially in errors, warnings, or notifications</ul></li> <ul><li>Avoiding awkward constructions</ul></li> <ul><li>Emphasizing the receiver of the action</ul></li> | That site can’t be found. Double-check the site address in the Address bar.<br />When the user clicks **OK**, the transaction is committed. (in content for developers) |

.claude/skills/microsoft-writing-style-guide/references/scannable-content-and-procedures.md:530

• Both list items close the <ul> before the <li>, which is invalid HTML and can render inconsistently. Close each list item before its list container.

|           **Choose**            |                                                                                                                                                                                                                                                     Choosing an option, based on the customer's preference or desired outcome.<br /><br />Selecting something that begins with the word **Select**, to avoid a repeated word.                                                                                                                                                                                                                                                      |                                                                                                                                                                                                                                                                                          <ul><li>On the **Font** tab, choose the effects that you want. </ul></li>  <ul><li> Choose **Select users**.</ul></li>                                                                                                                                                                                                                                                                                       |

.claude/skills/microsoft-writing-style-guide/references/scannable-content-and-procedures.md:527

• The Start-icon :::image directive is unresolved because its media isn't vendored, so this offline example contains raw Learn markup. Replace it with readable text or a locally resolvable image.

|       **Select and hold, select and hold (or right-click)**       |                                                                                                                                                                                                   Pressing and holding an element in the UI. It's OK to use *right-click* with *select and hold* when the instruction isn't specific to touch devices.                                                                           |                                                                                                                                                                                                                                                                <ul><li>To flag a message that you want to deal with later, select and hold it, and then select **Set flag**.</li></ul> <ul><li>Select and hold (or right-click) the Windows taskbar, and then select **Cascade windows**.</li></ul> <ul><li>Select and hold (or right-click) the **Start** :::image type="icon" source="media/describing-interactions-with-ui/967781121.png"::: button, and then select **Device Manager**.</li></ul>                                                                                                                             |