skillit-docs

Documentation Conventions for Skill Generation

typedoc-plugin-skillit generates AI agent skills (SKILL.md) from your TypeScript documentation. The quality of the generated skill depends entirely on what you write in your source docs.

The generator runs an audit during pnpm typedoc that checks your docs against these conventions at four severity levels:

• fatal — skill is broken without this (fix first)
• error — LLMs can't write correct code from this
• warning — skill works but isn't as good as it could be
• alert — stylistic suggestion

Fixing Audit Issues

Run pnpm typedoc and look for the audit output after [skills] lines. Fix fatals first, then errors.

Fatal — Fix These First

F1: package.json description — One-sentence problem statement:

{ "description": "Generate AI agent skills from TypeScript API documentation" }

NEVER: taglines ("Fast and lightweight"), tech-stack descriptions ("A TypeScript library").

F2: package.json keywords — 5+ domain-specific words:

{ "keywords": ["proxy", "ipc", "child-process", "worker", "type-safe", "rpc"] }

NEVER: generic terms (typescript, library, npm, utils) — these are filtered out and add zero triggering value.

F3: README description — Blockquote after title:

# my-lib

> Map process.env to strongly-typed nested config objects with camelCase fields.

F4: JSDoc on every export — At least one sentence:

/** Render a single extracted skill into SKILL.md + progressive disclosure references */
export function renderSkill(skill: ExtractedSkill): RenderedSkill {

Error — Fix These Next

E1: @param descriptions — Describe what each parameter controls, not what type it is:

// GOOD:
/** @param options Configuration for rendering — controls token budgets and output format */

// BAD:
/** @param options The options */

E2: @returns on non-void functions:

/** @returns Rendered skill with SKILL.md discovery file and on-demand reference files */