# Docs Standards

> Docs Standards is an Agent Skill for documents published in the CommunityToolkit/Aspire repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Microsoft Style Guide + Squad-specific documentation patterns

- Skill name: `docs-standards`
- Category: [Documents](https://www.openparable.com/skill/documents/1)
- Source: https://github.com/CommunityToolkit/Aspire/blob/HEAD/examples/squad/CommunityToolkit.Aspire.Hosting.Squad.AppHost/dev-squad/.squad/templates/skills/docs-standards/SKILL.md
- Repository: CommunityToolkit/Aspire (614 GitHub stars when collected)

## SKILL.md

## Context

Squad documentation follows the Microsoft Style Guide with Squad-specific conventions. Consistency across docs builds trust and improves discoverability.

## Patterns

### Microsoft Style Guide Rules
- **Sentence-case headings:** "Getting started" not "Getting Started"
- **Active voice:** "Run the command" not "The command should be run"
- **Second person:** "You can configure..." not "Users can configure..."
- **Present tense:** "The system routes..." not "The system will route..."
- **No ampersands in prose:** "and" not "&" (except in code, brand names, or UI elements)

### Squad Formatting Patterns
- **Scannability first:** Paragraphs for narrative (3-4 sentences max), bullets for scannable lists, tables for structured data
- **"Try this" prompts at top:** Start feature/scenario pages with practical prompts users can copy
- **Experimental warnings:** Features in preview get callout at top
- **Cross-references at bottom:** Related pages linked after main content

### Structure
- **Title (H1)** → **Warning/callout** → **Try this code** → **Overview** → **HR** → **Content (H2 sections)**

### Test Sync Rule
- **Always update test assertions:** When adding docs pages to `features/`, `scenarios/`, `guides/`, update corresponding `EXPECTED_*` arrays in `test/docs-build.test.ts` in the same commit

## Examples

✓ **Correct:**
```markdown
# Getting started with Squad

> ⚠️ **Experimental:** This feature is in preview.

Try this:
\`\`\`bash
squad init
\`\`\`

Squad helps you build AI teams...

---

## Install Squad

Run the following command...
```

✗ **Incorrect:**
```markdown
# Getting Started With Squad  // Title case

Squad is a tool which will help users... // Third person, future tense

You can install Squad with npm & configure it... // Ampersand in prose
```

## Anti-Patterns

- Title-casing headings because "it looks nicer"
- Writing in passive voice or third person
- Long paragraphs of dense text (breaks scannability)
- Adding doc pages without updating test assertions
- Using ampersands outside code blocks

---

Source: https://www.openparable.com/skill/documents/docs-standards (OpenParable). Cite the canonical URL above.