Packages Documentation
Businesspackages-documentationPackages Documentation is an Agent Skill for business published in the reactive/data-client repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Write, update, and format documentation for @data-client public APIs - API reference (Docusaurus/MDX), README files, JSDoc/TSDoc docstrings, usage examples, migration guides, deprecation notices, changelog entries. Use when changing exported APIs (docs must update in the same PR), writing new package docs, or updating the dataclient.io site.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/reactive/data-client/blob/HEAD/.cursor/skills/packages-documentation/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/packages-documentation, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Package Documentation Writing Guidelines
This guide covers how to write and format documentation for public library interfaces.
Documentation Structure
The /docs folder is organized by package:
docs/core/- Documentation for@data-client/coreand@data-client/reactdocs/rest/- Documentation for@data-client/restdocs/graphql/- Documentation for@data-client/graphql
Each package documentation has subdirectories:
api/- API reference documentation (one file per public class/function/hook)guides/- How-to guides and tutorialsconcepts/- Conceptual documentationgetting-started/- Getting started guides
Documentation File Naming
API documentation files should match the exported name:
useSuspense.ts→docs/core/api/useSuspense.mdRestEndpoint.js→docs/rest/api/RestEndpoint.mdController.ts→docs/core/api/Controller.mdEntity.ts→docs/rest/api/Entity.md(ordocs/core/api/Entity.md)
Documentation Format
All API documentation files should include:
- Frontmatter with metadata:
---
title: API Name
sidebar_label: Display Name
---
-
Description - What the API does
-
Usage examples - Code examples showing how to use it
-
Parameters/Options - Document all parameters, options, and return types
-
Type information - TypeScript types and examples
-
Related APIs - Links to related documentation
Finding the Right Documentation File
- Identify the package: Check which package the code belongs to (
packages/core,packages/rest, etc.) - Check exports: Look at the package's
index.tsor main entry point to see what's exported - Match the name: Find the corresponding file in
docs/{package}/api/ - Check guides: If it's a workflow change, also check
docs/{package}/guides/
Examples
Example 1: Adding a new hook
- File:
packages/react/src/hooks/useNewFeature.ts - Action: Create
docs/core/api/useNewFeature.mdwith usage examples and API reference
Example 2: Changing a method signature
- File:
packages/rest/src/RestEndpoint.js(changingextend()method) - Action: Update
docs/rest/api/RestEndpoint.mdwith new signature, migration notes, and updated examples
Example 3: Deprecating an API
- File:
packages/core/src/SomeClass.ts(deprecatingoldMethod()) - Action:
- Update
docs/core/api/SomeClass.mdwith deprecation notice - Document the replacement API
- Add migration guide if needed
- Update
Example 4: Adding a new option
- File:
packages/rest/src/RestEndpoint.js(addingnewOptionparameter) - Action: Update
docs/rest/api/RestEndpoint.mdto document the new option with examples
Checklist
Before completing changes to public APIs in /packages:
- Identified all affected public APIs (exports from package entry points)
- Located or created corresponding documentation files in
/docs/{package}/api/ - Updated API reference documentation with changes
- Added/updated code examples
- Updated related guides if workflow changed
- Added migration notes for breaking changes
- Updated TypeScript examples in documentation
- Verified documentation builds correctly (if applicable)
Important Notes
- Public APIs are anything exported from the package's main entry point (typically
index.tsorsrc/index.ts) - Internal/private APIs (prefixed with
_, not exported, or marked as@internal) don't require documentation updates - When in doubt, err on the side of documenting - it's better to have extra documentation than missing documentation
- Documentation should be updated in the same commit or PR as the code changes