BCMS Skills

This skill gives the AI coding agent concise, BCMS‑specific guidance and defers longer explanations to the files in references/ . The agent should keep this file under roughly 500 lines and load deeper guides only when needed.

Key topics:

• Setup and client initialization (see references/bcms-api-basics.md )

• Working with templates (see references/templates.md )

• Entries (see references/entries.md )

• Groups (see references/groups.md )

• Widgets (see references/widgets.md )

• Media (see references/media.md )

• Properties and field types (see references/properties.md )

• Functions and webhooks (see references/functions-webhooks.md )

• Permissions (see references/permissions.md )

• Framework integrations (see references/frameworks.md )

Integration principles and defaults

• Default to the latest BCMS stack: use the latest BCMS features and the newest @thebcms/* and @bcms-types/* packages unless the user explicitly targets an older version.

• Model content with BCMS primitives first: prefer templates + entries as your main content model, with groups for reusable structures, widgets for reusable content blocks, and the media library for files.

• Use CLI starters when possible: for framework projects (Next, Nuxt, Astro, etc.) prefer the official @thebcms/cli starters before hand‑rolling integration; see references/frameworks.md .

• Render via BCMS components: in UI frameworks, prefer BCMSContentManager and BCMSImage (or their framework equivalents) to render rich text, widgets and media instead of building your own renderers.

• Always isolate secrets: read orgId , instanceId and API key credentials from environment variables, use separate keys per environment (dev/stage/prod) and prefer scoped keys, especially for media delivery; see references/bcms-api-basics.md and references/permissions.md .

• Design for localisation: when sites are multi‑lingual, use BCMS locales and model meta /content per locale; see references/entries.md and references/properties.md .

• Evolve schemas, don't break them: when changing content models, add or migrate fields via templates and groups; avoid destructive changes on production data; see references/templates.md and references/groups.md .

Patterns to avoid (and what to do instead)

• Never hard‑code API keys or use admin keys in the browser. Instead, store secrets in environment variables and use minimally scoped keys; see references/bcms-api-basics.md and references/permissions.md .

• Never delete templates, groups, widgets or media in production without checking impact. Always inspect usage first (group.whereIsItUsed , widget.whereIsItUsed , template.whereIsItUsed ) and plan a migration path; see references/templates.md , references/groups.md , references/widgets.md , and references/media.md .

• Avoid stuffing unstructured JSON into meta or content when a property, group or widget fits. Prefer explicit properties (string, rich text, enum, pointers, media) and reusable groups/widgets for structure; see references/properties.md , references/groups.md , and references/widgets.md .

• Avoid re‑implementing rich‑text and widget rendering when BCMSContentManager is available. Use the official components (@thebcms/components-* ) with BCMSContentManager and BCMSImage , and only drop down to custom parsing when you have a clear requirement; see references/entries.md and references/frameworks.md .

• Avoid exposing unnecessary write capabilities to public clients. Do not use keys with create/update/delete rights from the frontend; keep mutations behind server‑side code or functions, and use read‑only or media‑only keys in the browser; see references/permissions.md .

• Do not bypass webhook security. Always verify webhook signatures, check timestamps, and design idempotent handlers; see references/functions-webhooks.md .

When to reach for which BCMS features

Marketing, blog, or documentation sites Use templates like page , blog , doc with structured properties, groups for SEO/author blocks, widgets for reusable sections, and the media library for images; render with BCMSContentManager and BCMSImage . See references/templates.md , references/entries.md , references/groups.md , references/widgets.md , and references/media.md .

Multi‑locale content Model meta and content per locale, use BCMS locales, and ensure frontends handle missing translations gracefully via types from @bcms-types/ts . See references/entries.md and references/properties.md .

Asset‑heavy or image‑driven experiences Rely on the media library, folder structure, and auto‑generated sizes; use a dedicated media API key for public delivery and BCMSImage (or equivalent) to serve optimised variants. See references/media.md and references/bcms-api-basics.md .

Framework‑based frontends (Next.js, Nuxt, Astro, Gatsby, Svelte, Vite) Prefer the official BCMS starters; otherwise, follow the framework‑specific guides, using the standard Client constructor, generated types, and the appropriate @thebcms/components-* package. See references/frameworks.md .

Setup and Client Initialization

• Always use environment variables for secrets, never hard‑code BCMS credentials.

• Use separate API keys per environment (development, staging, production).

• Prefer scoped keys with the minimum necessary permissions.

Example client initialization (TypeScript):

import { Client } from '@thebcms/client';

export const bcms = new Client( process.env.BCMS_ORG_ID!, process.env.BCMS_INSTANCE_ID!, { id: process.env.BCMS_API_KEY_ID!, secret: process.env.BCMS_API_KEY_SECRET!, }, { injectSvg: true, // inline SVG icons into HTML useMemCache: true, // enable in‑memory caching enableSocket: false, // disable websockets when not needed }, );

For more, including API key structure and environment setup, see references/bcms-api-basics.md .

Working with Templates

• Treat templates as your content types (e.g., blog , page , author ).

• Use singular, descriptive names and rely on groups for reusable structures.

• Only admins (or keys with advanced rights) should create or modify templates.

Common operations:

• List all templates: await bcms.template.getAll()

• Get a template by ID or name

• Update or delete templates when refactoring content models

See references/templates.md for naming conventions, creation guidelines and code examples.

Entries

• Entries are instances of templates (e.g., a single blog post).

• Entries usually have:

• meta fields (title, slug, SEO, etc.)

• content fields, often localized by language code

Example: get all entries for a blog template:

const blogPosts = await bcms.entry.getAll('blog');

Agents should be able to:

• Create, update and delete entries

• Retrieve entries by ID, slug or status

• Filter entries by template and status (e.g., draft vs. published)

See references/entries.md for full CRUD examples and multilingual details.

Groups, Widgets and Media

• Groups are reusable structures that can be nested inside templates, widgets or other groups.

• Widgets are reusable content blocks embedded in rich‑text fields.

• Media refers to files in the BCMS media library (images, documents, etc.).

Typical operations:

• Groups:

• bcms.group.getAll()

• bcms.group.whereIsItUsed(groupId)

• Widgets:

• bcms.widget.getAll()

• bcms.widget.whereIsItUsed(widgetId)

• Media:

• bcms.media.getAll() , bcms.media.getById(id)

• Create folders and upload files using media API helpers

Widgets cannot currently be deleted via the SDK and must be removed via the BCMS dashboard. See references/groups.md , references/widgets.md and references/media.md for concrete examples and media best‑practices.

Properties and Field Types

BCMS supports various property types used in templates, groups and widgets, including:

• String, rich‑text, number, date, boolean

• Enumeration

• Entry pointer, group pointer

• Media fields (single and multiple)

Agents should choose appropriate field types based on content modelling goals and reusability. See references/properties.md , references/groups.md , references/widgets.md and references/templates.md for details.

Permissions and API Key Scopes

• BCMS enforces granular permissions for users and API keys.

• Permissions can be:

• Simple: broad access levels

• Advanced: per‑resource get/create/update/delete scopes

• Only admins can create templates, widgets, groups and API keys.

API keys:

• Should be scoped per template, function and media access where possible.

• Use least privilege: grant only the rights needed for the specific integration.

See references/permissions.md for a deeper explanation and configuration examples.

Functions and Webhooks

• Functions are serverless handlers you deploy inside BCMS and call via REST.

• Webhooks notify external systems about events such as entry or media changes.

Agents should:

• Call functions using the correct URL and headers, including an API key with function permissions.

• Configure and secure webhooks by:

• Verifying the X-Bcms-Webhook-Signature header

• Validating timestamps to avoid replay attacks

• Making handlers idempotent and rate‑limited

See references/functions-webhooks.md for full examples and security notes.

Best Practices and Troubleshooting

• Prefer TypeScript and generated BCMS types (e.g., @bcms-types/ts ) where available.

• Use caching (e.g., in‑memory or application‑level) for frequently read data.

• Separate dev, staging and production environments and API keys.

• On errors, check:

• URL correctness (org, instance, function ID)

• API key scopes and permissions

• Network and TLS configuration

For in‑depth guidance, always cross‑reference the official BCMS documentation from the references/ files.