AgentSkillsCN

documentation

README.md 和 AGENTS.md 文件的文档编写标准——语气、结构、精简 AGENTS.md 的理念

SKILL.md
--- frontmatter
name: documentation
description: Documentation standards for README.md and AGENTS.md files - tone, structure, thin AGENTS.md philosophy
license: MIT
compatibility: None required
metadata:
  author: youdotcom-oss
  version: "1.0.0"
  category: development
  keywords: [documentation, readme, agents-md, thin-agents, tsdoc]

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:

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

code

**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):

markdown
## 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/rules/code-patterns.md
  • •Test patterns, retry config → .claude/rules/code-patterns.md
  • •Error handling (err: unknown) → .claude/rules/code-patterns.md
  • •Type guards, private fields → .claude/rules/code-patterns.md
  • •Git workflow, commits → .claude/rules/git-workflow.md
  • •Documentation standards → .claude/skills/documentation

Good vs Bad Examples

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

markdown
## 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):

markdown
## Code Style

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

## 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/rules/code-patterns.md - Universal patterns
code

## 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/rules/code-patterns.md`

## Quick Start
[2-3 commands only]

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

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

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

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

## Related Skills
[List of relevant skills]

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

API Documentation Strategy

Do NOT create API.md files. Instead:

Add TSDoc to all exports

typescript
/**
 * 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

markdown
# {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/rules/code-patterns.md`

---

## Quick Start

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

## Code Style

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

## 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/rules/code-patterns.md`

### 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/rules/code-patterns.md` - Universal code patterns
- `.claude/skills/documentation` - Documentation standards
- `.claude/rules/git-workflow.md` - 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/rules/code-patterns.md 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

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

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

markdown
# AGENTS.md (150 lines)

> For universal patterns: `.claude/rules/code-patterns.md`

## 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/rules/code-patterns.md`

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 package documentation types:

AspectPackage README.mdPackage AGENTS.md
AudienceEnd users (integrators)Developers (contributors)
PurposeHow to use packageHow to contribute
ToneEncouraging, accessibleDirective, technical
LengthAny100-200 lines
InstallationSingle-platform npmN/A (dev setup)
Code ExamplesUsage examplesSide-by-side patterns
TroubleshootingUser issuesDev environment issues
Key ContentFeatures, quick start, examplesPackage-specific patterns, architecture
What to AvoidTechnical jargonUniversal patterns (use skills)
Progressive DisclosureCollapsible sectionsNo
DistributionPublished to npmPublished to npm

Common Mistakes

❌ Bloated Package AGENTS.md with Universal Patterns

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

markdown
# Package AGENTS.md (RIGHT)

> For universal patterns: `.claude/rules/code-patterns.md`

## Package-Specific Patterns

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

Related Skills

  • •.claude/rules/code-patterns.md - Universal code patterns
  • •.claude/rules/git-workflow.md - Git conventions
  • •.claude/rules/workflows.md - Package setup workflow