Documentation Standards

Complete documentation standards for dx-toolkit packages. Use these guidelines when creating or updating README.md and AGENTS.md files.

Root README.md - Monorepo Overview

IMPORTANT: The root README.md (at monorepo level) is an exception to package-specific guidelines.

Purpose: Clean navigation document for developers (integrators + contributors)

Structure:

1. Title and intro - Multi-platform toolkit (Claude Code, Cursor, 20+ AI agents)
2. NPM Packages - One-liner per package with Documentation link
3. Marketplace - One-liner per plugin with Documentation link (match NPM Packages format)
4. Quick Start - Development setup only (prerequisites + setup commands)
5. Monorepo Commands - Workspace-level and package-specific commands
6. Documentation - Package docs and contributor docs links
7. Directory Structure - Basic structure overview
8. Roadmap - Packages and plugins in development (link to docs/ROADMAP.md)
9. Contributing - Link to CONTRIBUTING.md
10. License and Support - Standard sections

Key Principles:

• ✅ Single Quick Start for development setup - No separate user/contributor sections
• ✅ Unified format - NPM Packages and Marketplace use same one-liner pattern
• ✅ Link to detailed docs - Don't duplicate AGENTS.md or package READMEs
• ✅ Show both command patterns - Root shortcuts AND bun --cwd packages/<package> <command>
• ✅ Complete environment setup - Both YDC_API_KEY and ANTHROPIC_API_KEY
• ✅ Build before test - bun run build then bun test in Quick Start
• ✅ Reflect current state - Update roadmap for upcoming work
• ❌ Don't separate "For Users" vs "For Contributors" - Single flow
• ❌ Don't duplicate Testing/Code Quality sections - Covered in Monorepo Commands
• ❌ Don't include "Working with AI Agents" section - Link to AGENTS.md instead
• ❌ Don't include "GitHub Workflows" section - Link to AGENTS.md instead
• ❌ Don't use <details> for progressive disclosure - Keep simple and linear

Quick Start Pattern:

## Quick Start

**Prerequisites:**
- Bun >= 1.2.21: [Installation guide](https://bun.sh/docs/installation)
- GitHub CLI (recommended): `brew install gh` (macOS) or [other platforms](...)

**Development setup:**
```bash
# Clone repository
git clone git@github.com:youdotcom-oss/dx-toolkit.git
cd dx-toolkit

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env and add your YDC_API_KEY and ANTHROPIC_API_KEY
source .env

# Authenticate with GitHub (if using gh CLI)
gh auth login

# Build all packages
bun run build

# Run all tests
bun test

# Run all quality checks
bun run check

For comprehensive development guidelines, see AGENTS.md.

**Package/Plugin Listing Pattern** (One-liner with link):
```markdown
### [@youdotcom-oss/mcp](./packages/mcp/)
MCP Server giving AI agents real-time web search, AI answers, and content extraction via Model Context Protocol. **[Documentation →](./packages/mcp/README.md)**

### [teams-anthropic-integration](./plugins/teams-anthropic-integration/)
Generate Microsoft Teams apps with You.com Anthropic integration using `@youdotcom-oss/teams-anthropic` - handles setup workflow for new and existing apps. **[Documentation →](./plugins/teams-anthropic-integration/README.md)**

Contributing Pattern (Just link):

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

Target Length: ~200 lines (down from 300-400 with removed sections)

These guidelines apply to package-level documentation (e.g., packages/mcp/README.md, packages/ai-sdk-plugin/README.md).

Thin AGENTS.md Philosophy

Package AGENTS.md files should be minimal wrappers that primarily reference skills.

What to Include (Package-Specific Only)

✅ Include these in package AGENTS.md:

• Quick setup commands (2-3 lines)
• Framework-specific patterns (e.g., "Teams.ai Memory API uses push() not addMessage()")
• Domain-specific integration rules (e.g., "Anthropic requires system messages as separate parameter")
• Package-specific error patterns (e.g., "MCP tools must return responses, never throw")
• Architecture diagram if complex
• Troubleshooting specific to this package

What to Reference (Universal Patterns)

❌ Reference skills instead of duplicating:

• Arrow functions, Bun APIs → .claude/skills/code-patterns
• Test patterns, retry config → .claude/skills/code-patterns
• Error handling (err: unknown) → .claude/skills/code-patterns
• Type guards, private fields → .claude/skills/code-patterns
• Git workflow, commits → .claude/skills/git-workflow
• Documentation standards → .claude/skills/documentation

Good vs Bad Examples

❌ BAD - Bloated AGENTS.md (500+ lines):

## Code Style

### Arrow Functions
Always use arrow functions...
[50 lines of examples]

### Numeric Separators
Use underscores for large numbers...
[30 lines of examples]

### Error Handling
Always use try/catch with typed errors...
[100 lines of examples]

### Testing
Use test() not it()...
[150 lines of examples]

## Package-Specific Patterns
[Buried at the bottom, only 20 lines]

✅ GOOD - Thin AGENTS.md (150 lines):

## Code Style

> **For universal patterns**: See `.claude/skills/code-patterns`

## Package-Specific Patterns

### Teams.ai Memory API

Use `push()` and `values()`, NEVER `addMessage()`:
```ts
// ✅ Correct
await memory.push(input);
const messages = await memory.values();

[Only package-specific patterns, ~100 lines total]

Related Skills

• .claude/skills/teams-ai-patterns - Teams.ai integration
• .claude/skills/code-patterns - Universal patterns

## Document Types

### Package README.md - User-Facing Documentation

**Audience**: End users (developers integrating the package)

**Tone**: Encouraging and accessible

**Content Requirements**:
- Maximum 4 steps in "Getting started" section
- Natural language examples in quotes
- Progressive disclosure with collapsible sections
- Second-person voice ("you", "your")
- Emphasize immediate value

**Language Patterns**:
| ✅ Do | ❌ Don't |
|-------|----------|
| "Get up and running in 3 quick steps" | "Installation procedure requires..." |
| "No installation required" | "This package is hosted remotely" |
| "Your agent will automatically..." | "The system executes..." |
| "Just describe what you want" | "Invoke the tool with parameters" |

### Package AGENTS.md - Thin Developer Documentation

**Audience**: Developers, contributors, AI coding agents

**Tone**: Directive and technical (for package-specific content)

**Content Requirements** (Thin approach):
- Clear audience disclaimer at top
- Quick setup (2-3 commands)
- Reference to universal skills immediately
- **ONLY package-specific patterns** (framework APIs, domain rules)
- Architecture diagram if needed
- Symptom/solution troubleshooting for package-specific issues
- Heavy skill references throughout

**Structure**:
```markdown
# Package Development Guide

> For end users: See [README.md]
> For universal patterns: `.claude/skills/code-patterns`

## Quick Start
[2-3 commands only]

## Code Style
> See `.claude/skills/code-patterns`

## Package-Specific Patterns
[Only patterns unique to this package's domain]

## Testing
> For universal patterns: `.claude/skills/code-patterns`

### Package-Specific Testing
[Only if truly unique to this package]

## Related Skills
[List of relevant skills]

Target Length: 100-200 lines (not 500+)

Plugin README.md - Multi-Platform Installation Guide

Audience: End users (developers installing and using the plugin)

Tone: Encouraging and accessible (same as package README)

Key Differences from Package README:

1. Multi-platform installation - Claude Code, Cursor, and universal agents
2. Progressive disclosure per platform - Use <details> tags for each platform
3. Multiple installation options - Install script (recommended) + manual marketplace
4. Critical command order - Marketplace add BEFORE plugin install
5. Multiple package managers - npm, bun, yarn, pnpm in troubleshooting
6. Provider-agnostic issues - Avoid framework-specific problem titles

Installation Section Pattern:

## Installation

Get up and running in one command:

<details open>
<summary><strong>Claude Code</strong></summary>

**Option 1: Via install script (recommended)**

The script automatically configures the marketplace and installs the plugin:

```bash
curl -fsSL https://raw.githubusercontent.com/youdotcom-oss/dx-toolkit/main/scripts/install-plugin.sh | bash -s {plugin-name} --claude

Option 2: Via marketplace

First add the marketplace:

/plugin marketplace add youdotcom-oss/dx-toolkit

Then install the plugin:

/plugin install {plugin-name}

Use the plugin:

/{command-name}

curl -fsSL https://raw.githubusercontent.com/youdotcom-oss/dx-toolkit/main/scripts/install-plugin.sh | bash -s {plugin-name} --cursor

curl -fsSL https://raw.githubusercontent.com/youdotcom-oss/dx-toolkit/main/scripts/install-plugin.sh | bash -s {plugin-name} --agents.md

Troubleshooting Section Pattern (Multiple Package Managers):

<details>
<summary><strong>Cannot find module @youdotcom-oss/{package-name}</strong></summary>

The plugin should have installed it automatically. If not, run:

```bash
# NPM
npm install @youdotcom-oss/{package-name}

# Bun
bun add @youdotcom-oss/{package-name}

# Yarn
yarn add @youdotcom-oss/{package-name}

# pnpm
pnpm add @youdotcom-oss/{package-name}

Provider-Agnostic Issue Titles:

Plugin AGENTS.md - Command Discovery Wrapper

Audience: Universal AI agents (Claude, Cursor, Windsurf, Cody, Continue, etc.)

Purpose: Lightweight file that helps AI agents discover and reference plugin commands

Key Differences from Package AGENTS.md:

1. Different purpose - Not for contributors, for AI agent discovery
2. Thin wrapper pattern - Points to command files, never duplicates content
3. Relative paths - Uses install-location-relative paths, not repository paths
4. Public distribution - Hosted at https://api.you.com/plugins/{plugin-name}/AGENTS.md
5. Cross-IDE compatibility - Works with agents that don't support Claude Code plugins
6. Single source of truth - Detailed instructions stay in commands/ directory

Structure:

# {Plugin Title}

> For AI coding agents: {One-sentence description}

## When to Use

Trigger this integration when developer mentions:
- "{Keyword phrase 1}"
- "{Keyword phrase 2}"
- "{Keyword phrase 3}"

## Integration Instructions

**Fetch and follow the complete integration workflow:**

`commands/{command-name}.md`

This file contains:
- Complete step-by-step workflow
- Template integration patterns
- Configuration guide
- Validation checklist
- Troubleshooting guide

## For Claude Code Users

Use the slash command: `/{command-name}`

## Additional Resources

* Package README: https://github.com/youdotcom-oss/dx-toolkit/tree/main/packages/{package-name}
* Plugin README: https://api.you.com/plugins/{plugin-name}/README.md

Critical Rules:

• ✅ Use relative paths - commands/{command-name}.md (from installed location)
• ❌ Never use repository paths - Not plugins/{plugin-name}/commands/{command-name}.md
• ✅ Reference command files - Never duplicate command content
• ❌ Never include full workflow - Keep as thin wrapper
• ✅ List trigger keywords - Help AI agents know when to use
• ❌ No contribution guidelines - This is not for developers

Target Length: 30-50 lines (extremely thin wrapper)

Why this pattern:

• ✅ Single source of truth - Detailed instructions in commands/
• ✅ Never out of sync - AGENTS.md just points to command file
• ✅ Cross-agent compatibility - Works with Cursor, Windsurf, Cody, etc.
• ✅ Simple maintenance - Update command once, AGENTS.md unchanged

API Documentation Strategy

Do NOT create API.md files. Instead:

Add TSDoc to all exports

/**
 * Search the web using You.com API
 *
 * @param config - Optional configuration with API key
 * @returns AI SDK tool for web search
 *
 * @example
 * ```ts
 * import { youSearch } from '@youdotcom-oss/ai-sdk-plugin';
 *
 * const search = youSearch();
 * await generateText({
 *   model: 'anthropic/claude-sonnet-4.5',
 *   tools: { search },
 *   prompt: 'What happened today?'
 * });
 * ```
 */
export const youSearch = (config: YouToolsConfig = {}) => { ... }

Benefits of TSDoc over API.md

✅ Single source of truth - Types + docs in code ✅ Always in sync - Can't drift from implementation ✅ IDE integration - Hover shows docs instantly ✅ AI reads directly - Agents can access from source ✅ Less maintenance - One less file to update

Thin AGENTS.md Template

# {Package Name} Development Guide

Developer documentation for {package description}.

> **For end users**: See [README.md](./README.md) for setup and usage.
> **For universal patterns**: See `.claude/skills/code-patterns`

---

## Quick Start

\`\`\`bash
cd packages/{package-name}
bun install
bun test
\`\`\`

## Code Style

> **For universal patterns**: See `.claude/skills/code-patterns`

## Package-Specific Patterns

### [Framework/Domain Pattern 1]

[Only include if unique to this package's domain]

\`\`\`ts
// ✅ Correct - package-specific best practice
[example]

// ❌ Wrong - problematic pattern for this package
[anti-pattern]
\`\`\`

**Why this pattern?**
[Explanation specific to this package's domain]

### [Framework/Domain Pattern 2]

[Continue with only package-specific patterns]

## Testing

> **For universal patterns**: See `.claude/skills/code-patterns`

### Package-Specific Testing Patterns

[Only if testing approach is unique to this package]

## Architecture

[Diagram or description if package has complex architecture]

## Troubleshooting

### Symptom: [Package-specific problem]

**Solution**:
\`\`\`bash
[Fix specific to this package]
\`\`\`

## Related Skills

- `.claude/skills/{package-specific-skill}` - [Package-specific patterns]
- `.claude/skills/code-patterns` - Universal code patterns
- `.claude/skills/documentation` - Documentation standards
- `.claude/skills/git-workflow` - Git conventions

## Contributing

See root AGENTS.md for contribution guidelines.

**Package scope**: Use \`{package-name}\` in commit messages:
\`\`\`bash
feat({package-name}): add feature
fix({package-name}): resolve issue
\`\`\`

Target: 100-200 lines total, not 500+

Validation Checklists

Package README.md Checklist:

• Has 4-step "Getting started" section
• Uses encouraging language ("quick", "easy", "just")
• Provides natural language examples
• Uses second-person voice throughout
• Emphasizes immediate value
• Avoids technical jargon in main flow

Package AGENTS.md Checklist (Thin Approach):

• Starts with clear audience disclaimer
• References .claude/skills/code-patterns upfront
• Quick setup is 2-3 commands only
• Contains ONLY package-specific patterns
• No universal patterns duplicated (arrow functions, test patterns, etc.)
• Heavy skill references throughout
• Target length: 100-200 lines (not 500+)
• Lists related skills at bottom

Plugin README.md Checklist:

• Has installation section with three platform variants (Claude Code, Cursor, Other AI Agents)
• Each platform in <details> tag for progressive disclosure
• Claude Code section has TWO options (install script recommended, marketplace manual)
• Marketplace commands in correct order (add marketplace FIRST, then install)
• Troubleshooting sections include ALL package managers (npm, bun, yarn, pnpm)
• Issue titles are provider-agnostic (no "Anthropic", "OpenAI", etc.)
• Uses encouraging language and second-person voice (same as package README)
• Links to package README and plugin command documentation

Plugin AGENTS.md Checklist:

• Extremely thin wrapper (30-50 lines)
• Has "When to Use" section with trigger keywords
• References command file with relative path (commands/{command-name}.md)
• NEVER uses repository-relative paths (plugins/{plugin-name}/...)
• Does NOT duplicate command content (single source of truth)
• Lists what command file contains (workflow, templates, validation, troubleshooting)
• Includes slash command for Claude Code users
• Links to package README and plugin README as additional resources
• NO contribution guidelines (not for developers)
• NO package-specific patterns (those go in package AGENTS.md)

TSDoc API Documentation:

• All exports have TSDoc comments
• TSDoc includes description, params, returns
• TSDoc includes @example with runnable code
• No separate API.md file exists

Common Mistakes

❌ Bloated AGENTS.md

# AGENTS.md (600 lines)

## Arrow Functions
[100 lines of universal patterns]

## Error Handling
[150 lines of universal patterns]

## Testing
[200 lines of universal patterns]

## Package-Specific Patterns
[Only 50 lines buried at bottom]

Problem: Duplicates universal patterns, hard to maintain, hard to find package-specific content

✅ Thin AGENTS.md

# AGENTS.md (150 lines)

> For universal patterns: `.claude/skills/code-patterns`

## Package-Specific Patterns

### Teams.ai Memory API
[50 lines of package-specific patterns]

### Anthropic Streaming
[50 lines of package-specific patterns]

## Related Skills
- `.claude/skills/teams-ai-patterns`
- `.claude/skills/code-patterns`

Benefits: Easy to maintain, clear separation, package-specific content easy to find

Migration Path

For Existing Packages

1. Audit current AGENTS.md - Identify universal vs package-specific patterns
2. Extract universal patterns - Already covered by skills, can remove
3. Keep package-specific - Framework APIs, domain rules, architecture
4. Add skill references - Point to relevant skills throughout
5. Target 100-200 lines - Thin wrapper, not comprehensive guide

Example Migration

Before (500 lines):

• 300 lines universal patterns (arrow functions, testing, error handling)
• 200 lines package-specific (Teams.ai Memory API, Anthropic streaming)

After (150 lines):

• 50 lines references to skills
• 100 lines package-specific patterns
• Clear, focused, maintainable

Document Type Comparison

Quick reference comparing all four document types:

Common Document Type Mistakes

❌ Wrong: Using Package Patterns for Plugin README

# Plugin README (WRONG)

## Installation

npm install @youdotcom-oss/ai-sdk-plugin

Problem: Plugins need multi-platform installation (Claude Code, Cursor, agents.md)

✅ Right: Plugin README with Platform Variants

# Plugin README (RIGHT)

## Installation

<details open>
<summary><strong>Claude Code</strong></summary>

**Option 1: Via install script (recommended)**
curl -fsSL ...install-plugin.sh | bash -s plugin-name --claude

**Option 2: Via marketplace**
First add the marketplace:
/plugin marketplace add youdotcom-oss/dx-toolkit

❌ Wrong: Plugin AGENTS.md with Full Workflow

# Plugin AGENTS.md (WRONG)

## Integration Steps

1. First, ask the user which package manager...
2. Then, check if they have an existing setup...
3. Create the integration file...
[200 lines of detailed workflow]

Problem: Duplicates command file content, will drift out of sync

✅ Right: Plugin AGENTS.md as Thin Wrapper

# Plugin AGENTS.md (RIGHT)

## When to Use

Trigger when developer mentions:
- "AI SDK integration"
- "Vercel AI SDK tools"

## Integration Instructions

**Fetch and follow the complete integration workflow:**

`commands/integrate-ai-sdk.md`

❌ Wrong: Package AGENTS.md with Universal Patterns

# Package AGENTS.md (WRONG)

## Arrow Functions

Always use arrow functions...
[100 lines of examples]

## Testing

Use test() not it()...
[150 lines of examples]

## Package-Specific
[Only 50 lines buried at bottom]

Problem: Bloated with universal patterns, hard to maintain

✅ Right: Package AGENTS.md References Skills

# Package AGENTS.md (RIGHT)

> For universal patterns: `.claude/skills/code-patterns`

## Package-Specific Patterns

### Teams.ai Memory API
Use `push()` not `addMessage()`...
[Only package-specific content]

Related Skills

• .claude/skills/code-patterns - Universal code patterns
• .claude/skills/git-workflow - Git conventions
• .claude/skills/package-creation - Package setup workflow