gridaco/grida / .agents/skills/docs
docs
VerifiedDecide 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
| 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; cross-cutting → seo + docs-svg-kit; other surfaces have no dedicated skill yet — use 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 |
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:
- 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. - Is the reader a person trying to use a shipped product?
→ User docs. Content-rich and SEO-aware. For the canvas editor
(
docs/editor/) usedocs-canvas; for other surfaces (forms, platform, with-figma) there is no dedicated skill yet — followdocs/AGENTS.mdandseo.docs-svg-kitcovers SVG figures for any of them. - 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-canvasenforces 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-wgon 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 owndocs/, next to what it binds, sodocs/wgcan 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/fxand published atgrida.co/docs/fxas 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.mdfiles (gitignored); they do not belong underdocs/.
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'sREADME.mdandAGENTS.mdare 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 alongsidedocs/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.
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 |