Skip to content

reactive/data-client / .agents/skills/packages-documentation

packages-documentation

Verified

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.

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/react and @data-client/vue
  • docs/rest/ - Documentation for @data-client/rest
  • docs/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 tutorials
  • concepts/ - Conceptual documentation
  • getting-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 / :::vue blocks (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 / :::vue
  • framework-imports on a code fence for framework-agnostic code (managers, middleware): write @data-client/react imports and Vue pages show @data-client/vue. Examples never import @data-client/core; apps only install the react or vue package
  • vue_title:, vue_description: (any vue_<key>:) front matter overrides
  • frameworks: [react] front matter for pages with no Vue equivalent
  • foo.vue.md replaces foo.md for 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.md
  • RestEndpoint.js → docs/rest/api/RestEndpoint.md
  • Controller.ts → docs/core/api/Controller.md
  • Entity.ts → docs/rest/api/Entity.md (or docs/core/api/Entity.md)

Documentation Format

All API documentation files should include:

  1. Frontmatter with metadata:
---
title: API Name
sidebar_label: Display Name
---
  1. Description - What the API does

  2. Usage examples - Code examples showing how to use it. Pick a live playground's layout by website/src/components/Playground/README.md (Layouts)

  3. Parameters/Options - Document all parameters, options, and return types

  4. Type information - TypeScript types and examples

  5. Related APIs - Links to related documentation

Finding the Right Documentation File

  1. Identify the package: Check which package the code belongs to (packages/core, packages/rest, etc.)
  2. Check exports: Look at the package's index.ts or main entry point to see what's exported
  3. Match the name: Find the corresponding file in docs/{package}/api/
  4. 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.md with usage examples and API reference

Example 2: Changing a method signature

  • File: packages/rest/src/RestEndpoint.js (changing extend() method)
  • Action: Update docs/rest/api/RestEndpoint.md with new signature, migration notes, and updated examples

Example 3: Deprecating an API

  • File: packages/core/src/SomeClass.ts (deprecating oldMethod())
  • Action:
    • Update docs/core/api/SomeClass.md with deprecation notice
    • Document the replacement API
    • Add migration guide if needed

Example 4: Adding a new option

  • File: packages/rest/src/RestEndpoint.js (adding newOption parameter)
  • Action: Update docs/rest/api/RestEndpoint.md to 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/skills that cover the API: references.json for added/renamed/deleted pages, and SKILL.md examples (see .cursor/rules/skills-sync.mdc)

Important Notes

  • Public APIs are anything exported from the package's main entry point (typically index.ts or src/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
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: 466kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexUnverifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall