SKILL.md (2356B)
1 --- 2 name: "docs-standards" 3 description: "Microsoft Style Guide + Squad-specific documentation patterns" 4 domain: "documentation" 5 confidence: "high" 6 source: "earned (PAO charter, multiple doc PR reviews)" 7 --- 8 9 ## Context 10 11 Squad documentation follows the Microsoft Style Guide with Squad-specific conventions. Consistency across docs builds trust and improves discoverability. 12 13 ## Patterns 14 15 ### Microsoft Style Guide Rules 16 - **Sentence-case headings:** "Getting started" not "Getting Started" 17 - **Active voice:** "Run the command" not "The command should be run" 18 - **Second person:** "You can configure..." not "Users can configure..." 19 - **Present tense:** "The system routes..." not "The system will route..." 20 - **No ampersands in prose:** "and" not "&" (except in code, brand names, or UI elements) 21 22 ### Squad Formatting Patterns 23 - **Scannability first:** Paragraphs for narrative (3-4 sentences max), bullets for scannable lists, tables for structured data 24 - **"Try this" prompts at top:** Start feature/scenario pages with practical prompts users can copy 25 - **Experimental warnings:** Features in preview get callout at top 26 - **Cross-references at bottom:** Related pages linked after main content 27 28 ### Structure 29 - **Title (H1)** → **Warning/callout** → **Try this code** → **Overview** → **HR** → **Content (H2 sections)** 30 31 ### Test Sync Rule 32 - **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 33 34 ## Examples 35 36 ✓ **Correct:** 37 ```markdown 38 # Getting started with Squad 39 40 > ⚠️ **Experimental:** This feature is in preview. 41 42 Try this: 43 \`\`\`bash 44 squad init 45 \`\`\` 46 47 Squad helps you build AI teams... 48 49 --- 50 51 ## Install Squad 52 53 Run the following command... 54 ``` 55 56 ✗ **Incorrect:** 57 ```markdown 58 # Getting Started With Squad // Title case 59 60 Squad is a tool which will help users... // Third person, future tense 61 62 You can install Squad with npm & configure it... // Ampersand in prose 63 ``` 64 65 ## Anti-Patterns 66 67 - Title-casing headings because "it looks nicer" 68 - Writing in passive voice or third person 69 - Long paragraphs of dense text (breaks scannability) 70 - Adding doc pages without updating test assertions 71 - Using ampersands outside code blocks