Skip to content

gridaco/grida / .agents/skills/docs

Decide which family a doc belongs to before drafting — SDK/developer, user/product, or working-group (WG) — since family sets the audience, home, and tone. Use when creating, moving, or restructuring docs, when unsure which directory a doc belongs in, or when a request says "document this" / "write docs for X" without naming the kind. Routes to the specialized skill for each family.

FileKindSize
SKILL.mdskill md8.1 KB
---
name: docs
description: >
  Decide which family a doc belongs to before drafting — SDK/developer,
  user/product, or working-group (WG) — since family sets the audience,
  home, and tone. Use when creating, moving, or restructuring docs, when
  unsure which directory a doc belongs in, or when a request says
  "document this" / "write docs for X" without naming the kind. Routes to
  the specialized skill for each family.
---

# Docs

Documentation in Grida is not one thing. Before drafting, name the
**family** — because the family decides the audience, the home directory,
the tone, and which skill governs the rest. Writing the right content in
the wrong family (a spec dump in a user guide, a marketing tone in an
RFC) is the most common and most expensive docs mistake, because it is
invisible until someone reads it for the wrong reason.

`/docs/**` is the source of truth, synced to `/apps/docs/docs/**` at
build and published at `grida.co/docs`. Edit the root `/docs`, never the
synced copy. The operational rules that apply to _every_ family —
taxonomy (`draft` / `unlisted` / `doc_tasks`), frontmatter, MDX safety
(`format: md`), `_history/`, the structure table — live in
[`docs/AGENTS.md`](../../../docs/AGENTS.md). Read it once; this skill does
not repeat it.

## The three families

| Family                      | Audience                                                       | Home                                                                            | Character                                              | Governing skill                                                                                                                                                                                                                                                        |
| --------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SDK / developer**         | engineers (and, implicitly, agents) consuming a package or API | `packages/<pkg>/docs/` for spec-only; `docs/reference/**` for stable references | technical, example-dense, low-visual, precise          | this skill (below)                                                                                                                                                                                                                                                     |
| **User / product**          | humans using a Grida product                                   | `docs/editor/**`, `docs/forms/**`, `docs/platform/**`, `docs/with-figma/**`, …  | content-rich, screenshots, SEO-friendly, task-oriented | canvas editor (`docs/editor/`) → [`docs-canvas`](../docs-canvas/SKILL.md); cross-cutting → [`seo`](../seo/SKILL.md) + [`docs-svg-kit`](../docs-svg-kit/SKILL.md); other surfaces have no dedicated skill yet — use [`docs/AGENTS.md`](../../../docs/AGENTS.md) + `seo` |
| **WG / research / RFC-RFD** | contributors and maintainers reasoning about _why_ and _what_  | `docs/wg/**`                                                                    | spec-rich, language-agnostic, code-agnostic, factual   | [`docs-wg`](../docs-wg/SKILL.md)                                                                                                                                                                                                                                       |

If the request fits one family cleanly, hand off to its governing skill
and stop reading here. The rest of this page covers the routing edges and
the SDK family (which has no skill of its own).

## Routing — which family is this?

Ask, in order:

1. **Is it about _why_ a thing is designed the way it is, or _what_ a
   feature/spec should be — independent of any one implementation?**
   → WG. Go to [`docs-wg`](../docs-wg/SKILL.md).
2. **Is the reader a person trying to _use_ a shipped product?**
   → User docs. Content-rich and SEO-aware. For the canvas editor
   (`docs/editor/`) use [`docs-canvas`](../docs-canvas/SKILL.md); for
   other surfaces (forms, platform, with-figma) there is no dedicated
   skill yet — follow [`docs/AGENTS.md`](../../../docs/AGENTS.md) and
   [`seo`](../seo/SKILL.md). [`docs-svg-kit`](../docs-svg-kit/SKILL.md)
   covers SVG figures for any of them.
3. **Is the reader an engineer (or agent) trying to _consume_ a package
   or API correctly?** → SDK docs (below).

The boundaries are real, not bureaucratic:

- **Architecture / design rationale never goes in user docs.** It belongs
  in WG. ([`docs-canvas`](../docs-canvas/SKILL.md) enforces the
  same boundary from its side.)
- **A WG doc is not an SDK doc.** WG says "this is what the feature is and
  why"; SDK says "this is the API and how to call it." A WG doc that
  drifts into API signatures has become an SDK doc in the wrong place —
  see [`docs-wg`](../docs-wg/SKILL.md) on staying code-agnostic.
- **Implementation-binding specs live with the code, not in `docs/wg`.**
  A spec that maps a universal contract onto _one_ codebase — the concrete
  data a structure holds, this build's keymap, the contract→code mapping —
  is code-specific. It belongs in the package or crate's own `docs/`, next
  to what it binds, so `docs/wg` can stay code-agnostic. It is neither a WG
  doc (too code-specific) nor an SDK doc (not for external consumers) — its
  home is the code.
- **A product that lives in another Grida repo authors its docs there.**
  FX's guide is written in `gridaco/fx` and published at `grida.co/docs/fx`
  as a [docs source](../../../docs/wg/platform/docs-sources.md): its pages
  and assets never enter this repo, only a pinned commit
  (`apps/docs/sources.json`). Edit such docs in their repo, follow its asset
  rules there, and never copy them into `/docs`. Private products are the
  exception: their public docs are written here.
- **Plans, TODO lists, and conversational logs are not docs of any
  family.** Plans live in untracked `*.plan.md` files (gitignored); they
  do not belong under `docs/`.

## SDK / developer docs

SDK docs explain how to consume a package or API. They optimize for an
engineer (and, without ever saying so, for an agent) who needs to get a
call right on the first try.

**Where they live:**

- **`packages/<pkg>/docs/`** — when the docs are spec-heavy and not
  visually rich. Co-locating with the package keeps the contract next to
  the code it describes and versioned with it. (Precedent:
  `packages/grida-svg-editor/docs/`.) A package's `README.md` and
  `AGENTS.md` are the entry points; `docs/` holds the deeper material.
- **`docs/reference/**`** — for stable, cross-package technical
references, glossaries, and specs that deserve a place on the published
site. This tree is actively maintained alongside `docs/wg/\*\*`.

**What good SDK docs look like:**

- **Example-dense.** Every non-trivial API earns a short, runnable
  example. Examples carry more than prose for a consumer.
- **Technical and precise** about types, contracts, and edge cases —
  light on screenshots and marketing.
- **Good for agents by being good, period.** Do not write "for AI" — a
  clear, complete, example-backed reference is what an agent needs and
  what a human needs. The two goals do not diverge.
- **Honest about stability.** Mark experimental surfaces; an SDK doc that
  oversells a shaky API costs its readers time.

## Related skills

[`docs-wg`](../docs-wg/SKILL.md) (WG authoring doctrine),
[`docs-canvas`](../docs-canvas/SKILL.md) (canvas/editor user docs),
[`seo`](../seo/SKILL.md) (frontmatter + search),
[`links`](../links/SKILL.md) (how to write any link),
[`grounding`](../grounding/SKILL.md) (find/reconcile the authoritative
doc before editing). Operational taxonomy and frontmatter:
[`docs/AGENTS.md`](../../../docs/AGENTS.md).
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: 471kUpdated 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: 198kUpdated 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: 198kUpdated 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: 198kUpdated Claude CodeCodexVerifiedInstall