Agent Skills
› microsoft/Generative-AI-for-beginners-dotnet
› docs-standards
docs-standards
GitHub提供符合微软风格指南及团队规范的文档写作标准，涵盖标题格式、语态、结构及测试同步规则，确保文档一致性。
Trigger Scenarios
编写技术文档
审查文档内容
更新文档规范
Install
npx skills add microsoft/Generative-AI-for-beginners-dotnet --skill docs-standards -g -y
SKILL.md
Frontmatter
{
"name": "docs-standards",
"domain": "documentation",
"source": "earned (PAO charter, multiple doc PR reviews)",
"confidence": "high",
"description": "Microsoft Style Guide + Squad-specific documentation patterns"
}
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 correspondingEXPECTED_*arrays intest/docs-build.test.tsin the same commit
Examples
✓ Correct:
# 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:
# 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
Version History
- bd4e082 Current 2026-08-20 14:05
