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.

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. Read it once; this skill does not repeat it.

The three families

FamilyAudienceHomeCharacterGoverning skill
SDK / developerengineers (and, implicitly, agents) consuming a package or APIpackages/<pkg>/docs/ for spec-only; docs/reference/** for stable referencestechnical, example-dense, low-visual, precisethis skill (below)
User / producthumans using a Grida productdocs/editor/**, docs/forms/**, docs/platform/**, docs/with-figma/**, …content-rich, screenshots, SEO-friendly, task-orientedcanvas editor (docs/editor/) → docs-canvas; cross-cutting → seo + docs-svg-kit; other surfaces have no dedicated skill yet — use docs/AGENTS.md + seo
WG / research / RFC-RFDcontributors and maintainers reasoning about why and whatdocs/wg/**spec-rich, language-agnostic, code-agnostic, factualdocs-wg

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.
  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; for other surfaces (forms, platform, with-figma) there is no dedicated skill yet — follow docs/AGENTS.md and seo. docs-svg-kit 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 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 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: 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 (WG authoring doctrine), docs-canvas (canvas/editor user docs), seo (frontmatter + search), links (how to write any link), grounding (find/reconcile the authoritative doc before editing). Operational taxonomy and frontmatter: 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: 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