packages-documentation_skill

Overview

This skill helps write, update, and format documentation for public TypeScript packages in a monorepo that provides async state management, REST/GraphQL clients, SSE, and hooks. It focuses on API reference files, guides, conceptual docs, examples, migration notes, and deprecation notices organized under docs/{package}. It ensures documentation matches exports, includes TypeScript types and usage examples, and ships with the same commit as code changes.

How this skill works

The skill inspects package exports (index.ts or main entry) to identify public APIs and locates or creates matching files under docs/{package}/api/. It updates frontmatter, descriptions, examples, parameters, and type information, and adds related guides or migration notes when signatures or behavior change. It also enforces filename and folder conventions, checks for deprecation/migration guidance, and verifies documentation examples and TypeScript snippets are present.

When to use it

• Adding a new exported hook, class, function, or component in packages/*
• Changing a public method or function signature that affects consumers
• Deprecating an API or introducing a breaking change that needs migration guidance
• Introducing new options, parameters, or behavior that requires examples and type updates
• Improving or fixing existing API examples, README snippets, or docstrings

Best practices

• Always update docs in the same commit or PR as code changes to keep docs and code in sync
• Place API reference files at docs/{package}/api/ with filenames matching exported names
• Include frontmatter (title, sidebar_label), a concise description, multiple usage examples, parameters/options, return types, and TypeScript type examples
• Add related guides and migration notes for workflow or breaking changes; deprecation notices should recommend replacements
• Prefer concrete, copy-paste examples and keep snippets minimal and focused on common use cases

Example use cases

• Add docs for a new hook at packages/react/src/hooks/useNewFeature.ts → create docs/core/api/useNewFeature.md with examples and types
• Change RestEndpoint.extend() signature → update docs/rest/api/RestEndpoint.md, include new signature, examples, and migration notes
• Deprecate oldMethod() on a public class → add deprecation notice, document replacement, and provide a migration guide in docs/core/guides/
• Add a new option to a REST endpoint → update API doc with parameter description, default behavior, and TypeScript example showing usage