| name | explain |
| description | Use when an internal package, module, or shared component has little or no usage documentation and people (or future AI sessions) keep using it wrong โ "document this", "write docs for our library", onboarding someone onto an internal API, or handing a package to another team. |
Document Package โ make an internal package self-explaining to any model
Most internal packages ship with no usage docs, so every consumer โ a teammate, or an AI โ reads the
source, guesses the intended usage, and gets the gotchas wrong. This skill fixes that: one colocated
usage doc per public unit, capturing the API and the non-obvious rules, so the next reader is correct
on the first try. It applies to any package โ a UI component kit, a utils library, a services/API
layer, a hooks package, an internal SDK.
Why it matters for portability: these docs are the layer that makes your package understandable to
any model. If you migrate from one AI to another (Claude โ GPT โ Gemini), the new model still
understands your package immediately โ the knowledge lives in the repo, not in one model's head.
Ask first โ always
This writes files into the user's repo. Confirm before doing anything: "I can generate AI-friendly
usage docs for <package> so any model (and teammate) understands it correctly โ one doc per public unit,
with the gotchas. Want me to? (I'll show one sample first.)" Show a sample doc for one unit and get a
thumbs-up before fanning out across the package.
Method
-
Discover the public units. Read the package's public entry (index.ts/exports) for the real list โ
components, exported functions, hooks, services, classes. Note any existing docs' style and match it.
-
Read the source of truth โ don't guess. For each unit: the implementation, its types, its
variants/options, its tests/stories, and one real usage in the codebase. Verify every claim against
the code (never document a guess; mark "unverified" or omit).
-
Write a colocated doc (a README.md/doc beside the unit) with a consistent template:
- Title + one-line purpose + what it's built on.
- Signature / API โ a table: params/props/args ยท type ยท default ยท description; what it returns.
- Quick start โ the minimal correct usage (real import path).
- Variants / options / states (where applicable) โ with a code example each.
- Composition โ how it combines with siblings.
- Examples โ the handful of real scenarios people actually need.
- Gotchas โ the highest-signal section: rules the API doesn't enforce but people get wrong
(default values, which state hides what, reserved-but-unimplemented options, ordering constraints).
- Errors / accessibility / TypeScript โ as relevant to the unit's kind.
-
Prioritize the gotchas. The API table can be inferred from types; the gotchas cannot. That's the value.
-
Stamp it so drift is detectable. The code is the SSOT; the doc is derived โ so record what it
was derived from, the way engineering/ROUTER.md records a hash per node. End each doc with a
footer naming the source file(s), the repo commit SHA at generation time, and a short content hash
of each source (git rev-parse --short HEAD, git hash-object <file>):
Detecting drift is then a one-liner anyone (or any model) can run: re-hash the source and
compare to the footer โ git hash-object src/Button.tsx โ or git log a1b2c3d..HEAD -- src/Button.tsx
to see whether the unit changed since. Mismatch โ treat the doc as stale: re-read the source and
regenerate that unit before trusting it. No build script required; if the repo already has a docs
check or pre-commit hook, wire the same comparison into it rather than inventing a second mechanism.
Guardrails
- Derive from source, never invent. Unconfirmable behavior โ "unverified" or omit.
- One doc per unit, colocated โ found next to the thing it describes, travels with it.
- Match the package's existing doc style if any exists; consistency beats your template.
- Confirm scope + a sample before mass-generating โ the template must fit before you fan out.
