reactive/data-client / .agents/skills/packages-documentation
packages-documentation
VerifiedWrite, 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.
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/core,@data-client/reactand@data-client/vuedocs/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
React and Vue (single source)
docs/core renders twice: React at /docs, Vue at /vue. Never copy a page to make a Vue version.
Wrap framework-specific content instead, so shared prose and resources stay in one place:
:::react/:::vueblocks (use::::on an outer admonition that contains them):react[...]/:vue[...]for inline words or links<FrameworkPlayground>instead of<HooksPlayground>, with shared resource code blocks directly inside and component code blocks in:::react/:::vueframework-importson a code fence for framework-agnostic code (managers, middleware): write@data-client/reactimports and Vue pages show@data-client/vue. Examples never import@data-client/core; apps only install the react or vue packagevue_title:,vue_description:(anyvue_<key>:) front matter overridesframeworks: [react]front matter for pages with no Vue equivalentfoo.vue.mdreplacesfoo.mdfor Vue; only for Vue-only pages or when nothing is shareable
When changing a page, update both framework blocks in the same edit. See website/framework-docs/README.md.
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. Pick a live playground's layout by
website/src/components/Playground/README.md(Layouts) -
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)
- Updated agent skills in
.agents/skillsthat cover the API:references.jsonfor added/renamed/deleted pages, andSKILL.mdexamples (see.cursor/rules/skills-sync.mdc)
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |