docs-standards

Microsoft Style Guide + Squad-specific documentation patterns

6 stars

bycwoodruff

View on GitHub Installation ↓

Best use case

docs-standards is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Microsoft Style Guide + Squad-specific documentation patterns

Teams using docs-standards should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/docs-standards/SKILL.md --create-dirs "https://raw.githubusercontent.com/cwoodruff/morespeakers-com/main/.copilot/skills/docs-standards/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/docs-standards/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How docs-standards Compares

Feature / Agent	docs-standards	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Microsoft Style Guide + Squad-specific documentation patterns

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

## 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