# Skillit Docs

> Documentation conventions for generating high-quality AI agent skills from TypeScript source. Use when preparing a library for skill generation, auditing JSDoc quality, fixing audit warnings, writing @useWhen/@avoidWhen/@never tags, or asking about documentation conventions for skills.

- Skill: `pradeepmouli/skillit-docs-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pradeepmouli/skillit-docs-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pradeepmouli/skillit-docs-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: pradeepmouli (https://skillmd.com/u/pradeepmouli)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pradeepmouli/skillit-docs-2

---


# Documentation Conventions for Skill Generation

Use this skill when improving TypeScript package metadata, README structure, and public JSDoc so `typedoc-plugin-skillit` can generate better SKILL.md output.

## Focus Areas

- Package metadata: meaningful `description`, domain keywords, repository URL
- README shape: opening summary, Features, Troubleshooting
- JSDoc coverage: summaries, `@param`, `@returns`, `@remarks`, `@example`
- Skill routing tags: `@useWhen`, `@avoidWhen`, `@never`, `@category`

## Fix Patterns

- Prefer problem-oriented summaries over type restatements
- Write `@param` prose around caller-visible effects
- Use `@never` in `NEVER [action] — [reason]. Fix: [recovery path]` form
- Add 3–5 strong `@useWhen` triggers to important exports