Agent Skills: BCMS Skills

BCMS Skills

Canonical copy: edit this file at ai/skills/bcms/SKILL.md. The Claude Code and Cursor plugins package the same file via symlinks at ai/providers/claude/plugin/skills/bcms-best-practices/SKILL.md and ai/providers/cursor/plugin/skills/bcms-best-practices/SKILL.md (see ai/README.md and ai/AGENTS.md). On Windows, if symlinks are unavailable, copy this file into those paths when publishing.

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)
• MCP for agents and IDEs (see references/mcp.md)

Integration principles and defaults

• Default to the latest BCMS stack: use the latest BCMS features and the newest @thebcms/* packages unless the user explicitly targets an older version. Generated types usually live under bcms/types/ts after bcms --pull types (see framework guides); some setups import from @thebcms/types or an alias—match the project you are editing.
• 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: store the three‑part API key (keyId.secret.instanceId) in environment variables (e.g. BCMS_API_KEY, plus a public key var where the framework docs require it), 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.
• MCP when the agent has BCMS tools: if the environment exposes BCMS MCP tools, use them for listing templates and entries, creating or updating entries (within key scopes), and media discovery. Use @thebcms/client for application code, builds, and anything outside MCP (see references/mcp.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 ship MCP API keys to browsers, public repos, or client bundles. MCP keys are for trusted agents and local config only; scope them like any write-capable key; see references/mcp.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 using generated types (e.g. from bcms/types/ts or your project’s type package). 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.

• AI assistants and IDE workflows (Cursor, Claude Code, etc.) Enable MCP on a dedicated API key, configure the MCP URL with least‑privilege template and media scopes, and use the exposed tools for content operations. Do not embed those keys in shipped apps. See references/mcp.md and BCMS MCP documentation.

BCMS MCP (agents and IDEs)

BCMS hosts an MCP server so assistants can work with entries and media using a key that has MCP enabled. Official overview: thebcms.com/docs/mcp.

• URL pattern: https://app.thebcms.com/api/v3/mcp?mcpKey=<bcms-mcp-key> (adjust host if your org uses a custom app URL). Matches BCMS MCP docs.
• Transport: Streamable HTTP; after initialize, send mcp-session-id on follow‑up requests.
• Scopes: the dashboard can show per‑template GET / POST / PUT / DELETE, but the product note is that MCP currently supports creating, reading, and updating content only—treat entry delete as not available via MCP tools even if DELETE appears in key settings.
• Rich text: entry bodies use node trees aligned with the docs (paragraphs, headings, lists, image, widget, etc.); use get_entry_pointer_link and get_media_pointer_link for internal BCMS links in link marks.

Full tool names, troubleshooting, and MCP vs SDK guidance: references/mcp.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.

Preferred for app starters (matches Next.js / Nuxt docs): one three‑part API key string in env (keyId.secret.instanceId) and a single‑argument client:

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

// Private: reads BCMS_API_KEY from the environment by default
export const bcmsPrivate = new Client({ injectSvg: true });

// Public / browser-safe key (example for Next.js)
export const bcmsPublic = new Client({
  apiKey: process.env.NEXT_PUBLIC_BCMS_API_KEY,
  injectSvg: true,
});

Scripts and servers: set BCMS_API_KEY to the same three‑part string and use new Client({ injectSvg: true, useMemCache: true, enableSocket: false }) (see ai/scripts/init-client.ts). Details match thebcms.com/docs integration guides.

For env variable patterns and security, 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.

Local repo examples (ai/scripts/)

Human developers (and agents with repo access) can run the TypeScript examples under ai/scripts/:

• init-client.ts — construct Client with BCMS_API_KEY (three‑part key).
• call-function.ts — call a BCMS function by ID with a JSON body (BCMS_API_KEY, BCMS_BASE_URL, BCMS_FUNCTION_ID).

These are not MCP; they illustrate SDK usage. See each file’s header for how to run them (e.g. npx tsx with env set).

Repo-level notes for automation: ai/AGENTS.md. Change history for this skill pack: ai/CHANGELOG.md.

Best Practices and Troubleshooting

• Prefer TypeScript and generated BCMS types (bcms/types/ts after CLI pull, or your framework’s documented import path) 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.