Agent Skills: Documentation

Documentation

Follow writing-voice for tone.

Documentation explains why, not what. Users can read code to see what it does. They need you to explain the reasoning.

When to Apply This Skill

Use this pattern when you need to:

• Write or update folder README.md files with architecture intent.
• Add JSDoc to public APIs with usage context and examples.
• Review docs/comments that currently restate code without rationale.
• Add code comments for non-obvious decisions, constraints, or workarounds.

Folder READMEs

Primary job: explain why this folder exists and the mental model.

Can Include

• ASCII art diagrams for complex relationships
• Overview of key exports or entry points
• Brief file descriptions IF they add context beyond the filename
• Relationships to other folders

Avoid

• Exhaustive file listings that just duplicate ls
• Descriptions that repeat the filename ("auth.ts - authentication")
• Implementation details better expressed in code

Good

# Converters

Transform field schemas into format-specific representations.

```
┌─────────────┐     ┌──────────────┐
│ Field Schema│────▶│  to-arktype  │────▶ Runtime validation
└─────────────┘     ├──────────────┤
                    │  to-drizzle  │────▶ SQLite columns
                    └──────────────┘
```

Field schemas are pure JSON Schema objects with `x-component` hints. Each converter takes the same input and produces output for a specific consumer.

Bad

# Converters

- `to-arktype.ts` - Converts to ArkType
- `to-drizzle.ts` - Converts to Drizzle
- `index.ts` - Exports

The bad example just lists files without explaining the pattern or when to add new converters.

JSDoc Comments

JSDoc explains when and why to use something, not just what it does.

Good

/**
 * Get all table helpers as an array.
 *
 * Useful for providers and indexes that need to iterate over all tables.
 * Returns only the table helpers, excluding utility methods like `clearAll`.
 *
 * @example
 * ```typescript
 * for (const table of tables.defined()) {
 *   console.log(table.name, table.count());
 * }
 * ```
 */
defined() { ... }

Bad

/** Returns all table helpers as an array. */
defined() { ... }

Rules

• Include @example blocks with realistic usage
• Explain WHEN to use it, not just WHAT it does
• Document non-obvious behavior or edge cases
• Public APIs get detailed docs; internal helpers can be minimal

Code Comments

Comments explain why, not what.

Good

// Y.Doc clientIDs are random 32-bit integers, so we can't rely on ordering.
// Use timestamps from the entries themselves for deterministic sorting.
const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);

Bad

// Sort the entries
const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);

Rules

• If the code is clear, don't comment it
• Comment the "why" when it's not obvious
• Comment workarounds with links to issues/docs
• Delete commented-out code; that's what git is for