Terminal
Terminal/Skill
Helps write GraphQL queries that read DatoCMS content through the Content Delivery API, including filters, images, localization and caching.
By DatoCMS
Works with
npx skills add datocms/agent-skills --skill datocms-cdaExpert at querying DatoCMS CDA (read-only GraphQL) using @datocms/cda-client. Follow steps in order.
If context already established, skip broad detection. Re-inspect only when needed.
Examine project setup:
Read package.json for @datocms/cda-client. Not installed? npm install @datocms/cda-client
Find existing executeQuery or rawExecuteQuery imports to understand usage patterns.
Check .env* files (incl. .env.example) for *DATOCMS*TOKEN* vars; reuse those names. Starters: DATOCMS_PUBLISHED_CONTENT_CDA_TOKEN, DATOCMS_DRAFT_CONTENT_CDA_TOKEN.
Check framework (Next.js, Astro, Remix, Nuxt, SvelteKit) to determine server vs client queries. Don't expose tokens to browser unless using public read-only token.
Check type generation setup:
gql.tada in dependencies + initGraphQLTada call (typically lib/datocms/graphql.ts)@graphql-codegen/cli in devDependencies + graphql.config.tsCDA only needs read-only token. If DATOCMS_API_TOKEN is also used for CMA, better suggesting a separate read-only token for CDA.
Clear request? Proceed directly. Read only relevant references from references/:
| Task | Reference |
|---|---|
| Basic (fetch by slug/ID, single-instance, collections, meta) | references/querying-basics.md |
| Filtering (field/meta filters, AND/OR, deep, uploads) | references/filtering.md |
| Pagination & ordering (first/skip, auto, sort, trees) | references/pagination-and-ordering.md |
| Localization (localized fields, fallback, all-locale values) | references/localization.md |
| Modular content (blocks, fragments, nested blocks) | references/modular-content.md |
| Structured text (DAST value/blocks/links, render) | references/structured-text.md |
| Images & media (responsiveImage, imgix, placeholders, focal, video) | references/images-and-videos.md |
SEO & meta (_seoMetaTags, favicons, globalSeo, OG tags) | references/seo-and-meta.md |
| Draft/preview, strict mode, reading cache tags, CDN, environments, Content Link query options | references/draft-caching-environments.md |
| Type generation (gql.tada, graphql-codegen, schema types, typed queries) | references/type-generation.md |
| gql.tada fragment discipline (masking, composition, page query) | references/fragment-patterns.md |
Client setup/wrappers, options, token permissions, ApiError handling, 429/complexity/CDN diagnostics, custom scalars | references/client-and-config.md |
Cross-cutting:
references/localization.mdreferences/modular-content.mdreferences/images-and-videos.mdreferences/pagination-and-ordering.mdreferences/pagination-and-ordering.md for complexity costsgql.tada project → references/fragment-patterns.mdAlso apply every Step 4 check while writing.
executeQuery from @datocms/cda-client (or repo's existing wrapper around it)rawExecuteQuery only if response headers are needed (cache tags)TypedDocumentNode / gql.tada); a string query returns unknown — type it: executeQuery<Result>(query, …)$first: IntType, $id: ItemId)/* GraphQL */ prefix enables editor highlighting/validationconst query = /* GraphQL */ `query { ... }`
autoRetry handles rate limitsBefore presenting final code:
ApiError caught at boundariesexecuteQueryWithAutoPaginationincludeDrafts intentional (not exposing unpublished in prod)excludeInvalid — recommend for stable schemas. Changing schema? use filter: { _isValid: { eq: true } } insteadas / as unknown as to silence errors@datocms/cda-client; keep generated GraphQL helpers if type-gen wired; React renderers from subpaths (react-datocms/structured-text): root react-datocms statically imports optional peer @mux/mux-player-reactvalue, blocks, links, inlineBlocks); omitting = silent data loss; render each with its own callback (inlineBlocks → renderInlineBlock, not renderInlineRecord)fetch, tagging, custom plumbing? use buildRequestHeaders() / buildRequestInit()graphql() function, check scalar mappings...Fragment spread; follow project's masking setup (see references/fragment-patterns.md)This skill covers reading via GraphQL CDA. Route to companion skill for:
| Condition | Route to |
|---|---|
| DAST structure or validation | datocms-structured-text — document model |
| DAST traversal/editing; Markdown/HTML import or format export | datocms-structured-text — editing or conversion |
| Mutating content, schema/uploads/webhooks, scripts (including REST queries) | datocms-cma |
| App wiring: draft mode endpoints, Web Previews, Content Link overlays, realtime subscriptions, cache-tag invalidation (revalidation, CDN purge) | datocms-frontend-integrations |
| Building plugin | datocms-plugin |
Query side of that wiring stays here: includeDrafts, contentLink / baseEditingUrl / _editingUrl, reading x-cache-tags via rawExecuteQuery.
Load the specialist only for a DAST task; ordinary GraphQL selection stays here. Missing sibling reference → install that skill from datocms/agent-skills or update the full bundle.