skills.rest
dotnet
dotnetOFFICIAL
Explore all skills by this author →
Website𝕏@dotnetfdnGitHub

docs-standards

Enforce Microsoft-aligned documentation structure and test sync for Squad markdown.

209|27|Updated Mar 10, 2026
Search Tags:#testing#documentation#markdown#consistency#style guide#developer experience#information architecture
One-click install
npx skills add https://github.com/dotnet/maui-labs --skill docs-standards-dotnet
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: docs-standards
Source: https://github.com/dotnet/maui-labs/tree/main/src/Comet/.copilot/skills/docs-standards
Command: npx skills add https://github.com/dotnet/maui-labs --skill docs-standards-dotnet

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It solves the confusion and inconsistency that happen when different authors document features with varying styles, structures, and tone. It also reduces regressions by helping teams remember which tests must be updated when new doc pages are added. You end up with docs that are easier to scan, easier to find, and safer to maintain.

Core Features & Use Cases

  • Microsoft Style Guide alignment: Uses sentence-case headings, active voice, second-person perspective, and present tense to keep writing uniform.
  • Squad documentation structure: Enforces a repeatable page layout (title, callout/warning, try-this prompt, overview, sections) to improve scannability.
  • Change coordination for doc build tests: Provides a “test sync” rule so adding pages to key folders updates the expected assertions in the docs build test.
  • Use cases: Creating new feature/scenario/guide pages, refactoring existing docs for clarity, and preparing preview/experimental announcements with consistent callouts.

Quick Start

Add or edit a Squad documentation page following the required structure and updating the corresponding EXPECTED_* arrays in test/docs-build.test.ts when you add pages to features, scenarios, or guides.

Frequently Asked Questions about docs-standards

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I enforce documentation consistency across multiple markdown contributors?▼

To enforce documentation consistency, apply standardized markdown style rules for headings, voice, and page structure. This ensures uniform formatting across contributors, making feature and scenario pages easier to scan and maintain.

Why do my documentation builds fail when I add new markdown pages?▼

Documentation builds fail when expected test arrays are not synchronized with new markdown pages. You must update the expected assertions in your docs build test files whenever pages are added to features, scenarios, or guides folders.

What is the best way to structure markdown pages for developer documentation?▼

The best way to structure markdown documentation is using a repeatable layout with YAML frontmatter, title, callouts, try-this prompts, and overview sections. This standardized page structure improves scannability and keeps page intent clear.

Does writing Microsoft Style Guide aligned documentation require sentence-case headings?▼

Yes, Microsoft Style Guide aligned documentation requires sentence-case headings, active voice, second-person perspective, and present tense. These style guide rules keep writing uniform and improve the overall developer experience.

Can I use standard markdown formatting for callouts and warnings in scenario guides?▼

Yes, you can use markdown formatting for callouts and warnings, but they must follow specific placement patterns within the page structure. Consistent callout and try-this placements ensure readers can quickly scan preview and experimental announcements.

When should I update docs build test assertions for markdown changes?▼

You should update docs build test assertions whenever you add new markdown pages to features, scenarios, or guides folders. This test synchronization prevents regressions and ensures documentation builds pass consistently across updates.

Related Skills

Explore More Content & Communication Skills→
p-iknowp-iknow
1

doc-frontmatter

Generate and validate YAML frontmatter for Markdown documentation files.

Community
Intermediate
bernajaberbernajaber

test

Run and validate automated acceptance tests for product features.

Community
Intermediate
usepowershellusepowershell
9

docs-standards

Standardize Markdown documentation with Microsoft Style Guide and squad patterns.

Community
Basic
sachinnair90sachinnair90

docs-standards

Standardize Markdown documentation to match Microsoft Style Guide and squad rules.

Community
Basic