skillit-docs

Files (1)

• SKILL.md

SKILL.md (first lines)

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

```json
{ "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:

```json
{ "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:

```markdown
# my-lib

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

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

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

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

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

**E2: @returns on non-void functions**:

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

**E3: Interface property JSDoc**:

```typescript
export interface Config {
  /** Maximum token budget per reference file (default: 4000) */
  maxTokens: number;
}
```

**E4: At least one @example** — Realistic usage, not trivial:

````typescript
/**
 * @example
 * ```typescript
 * import { renderSkills, writeSkills } from '@skillit/core';
 * const rendered = renderSkills(extracted, { maxTokens: 4000 });
 * writeSkills(rendered, { outDir: 'skills' });
 * ```
 */
````

**E5: package.json repository** — Add the repo URL.

### Warning — Polish for Quality

**W1:** Add `@packageDocumentation` to index.ts with overview and feature list.
**W2:** Add `@example` to every exported function.
**W3:** Use `@deprecated`, `@since`, `@throws`, `@see` tags where applicable.
**W4:** Add 10+ domain-specific keywords.
**W5:** Add `## Features` section to README.
**W6:** Add `## Troubleshooting` section to README — common issues, errors, and FAQs users encounter.

## JSDoc Tags for Expert-Quality Skills

These three custom tags are what separate a "passing" skill from a genuinely useful one. They provide the expert knowledge that Claude doesn't already have — decision procedures, anti-patterns, and freedom calibration.

The plugin auto-registers these as `blockTags` at load time — no `typedoc.json` config needed. If they're accidentally placed in `modifierTags`, the plugin auto-moves them with a warning (modifierTags strips content).

### `@useWhen` — When to reach for this class/function

Each bullet is a scenario where an agent should use this export. Only write entries that contain **non-obvious expert knowledge** — if Claude could guess the answer from the class name, don't write it.

BAD (obvious): `@useWhen - Displaying images` on Sprite — Claude already knows Sprite displays images.
GOOD (expert): `@useWhen - Rendering >500 identical sprites — ParticleContainer batches into a single GPU draw call vs O(n) individual draws`

For large libraries (50+ classes), write `@useWhen` on **5-10 key decision points**, not every class. Focus on scenarios where the wrong choice causes performance cliffs or silent bugs.

```typescript
/**
 * @useWhen
 * - You need CPU-intensive work isolated from the main process — IPC overhead is ~1ms per call
 * - You want EventEmitter events forwarded transparently across process boundaries

From pradeepmouli/skillit, MIT.

More from pradeepmouli/skillit