docs-standards
Microsoft Style Guide + Squad-specific documentation patterns
- License 许可
- MIT
- 所属仓库
- github/squad
- 最近更新
- 2026-11-15
- Stars
- ★ 3.4k
- Forks
- 520
01 前言 Front Matter
- name
- docs-standards
- domain
- documentation
- source
- earned (documentation reviews)
- confidence
- high
- description
- Microsoft Style Guide + Squad-specific documentation patterns
03 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 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
04 同仓库更多 Skills
windows-compatibility
Cross-platform path handling and command patterns
versioning-policy
SemVer rules for Squad's stable, preview, insider, and local package versions
tiered-memory
Three-tier agent memory model (hot/cold/wiki) for context reduction per spawn
test-discipline
Design assertions that prove the actual contract and fail on realistic regressions
squad
Squad's command catalog and interactive menu. Invoke via /squad (slash command) or natural language ("squad commands", "what can squad do", "show me squad options"). Presents categorized operations (Install & Upgrade, Team Management, Issues & PRs, Plugins & Skills, Model & Cost, Sessions & State) as an interactive picker. Routes to the right squad CLI command or the Squad coordinator agent.
squad-version-check
Internals of how @bradygaster/squad-cli stamps its version, how `squad upgrade` works (what it preserves vs overwrites), and how to probe the npm registry for the latest version from a coordinator prompt.