BCMS Skills

Install with the skills CLI:

# Guidance skill: SDK building + content modeling + MCP
npx skills add bcms/ai --skill bcms

# Executable skill: a thin CLI for daily content ops (entries + media)
npx skills add bcms/ai --skill bcms-content

The bcms skill gives the AI coding agent concise, BCMS‑specific guidance and defers longer explanations to the files in references/. The bcms-content skill ships a small CLI (cli/bcms.mjs, wrapping @thebcms/client) so agents can create / update / delete / list entries and upload media with a single API key — the same key used for the BCMS MCP. See skills/bcms-content/SKILL.md.

Setup guide: thebcms.com/agents — MCP connection, skill install, and the content CLI.

Where things live in this repo: canonical reference markdown is under ai/references/. Skill folders under ai/skills/ include generated references/ copies for skills.sh installs — run node scripts/sync-skill-references.mjs after editing canonical references (see skills/bundle.json).

Repository layout (1.1+)

Path	Role
ai/skills/bcms/SKILL.md	Canonical bcms skill—edit here. Covers SDK building and MCP content operations.
ai/skills/bcms/references/	Generated copies of the canonical references, bundled for skills.sh installs (node scripts/sync-skill-references.mjs).
ai/skills/bcms-content/SKILL.md	Canonical bcms-content skill—the executable content CLI. Ships cli/bcms.mjs + package.json (one dependency: @thebcms/client).
ai/providers/claude/plugin/skills/bcms/SKILL.md	Symlink to the canonical skill (Claude Code bundle). On Windows without symlink support, copy the canonical file when publishing.
ai/providers/cursor/plugin/	Cursor plugin bundle (skills + symlinks); marketplace manifest ai/.cursor-plugin/marketplace.json. See providers/cursor/plugin/README.md.
ai/skills/bundle.json	Which reference files the skill ships (node scripts/sync-skill-references.mjs).
ai/scripts/	SDK examples, validate-cursor-plugin.mjs, sync-skill-references.mjs.
ai/AGENTS.md	Layout and integration notes for maintainers.
ai/CHANGELOG.md	Skill pack version history.

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 content and schema operations — listing, creating, updating, and deleting entries, templates, groups, and widgets, plus media discovery and uploads. 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 thebcms.com/agents, references/mcp.md, and BCMS MCP documentation.

BCMS MCP (agents and IDEs)

BCMS hosts an MCP server so assistants can work with BCMS content and schema using a key that has MCP enabled. Agent landing page: thebcms.com/agents. Official overview: thebcms.com/docs/mcp.

• URL pattern: https://app.thebcms.com/api/v3/mcp?mcpKey=<keyId.secret.instanceId> (the query param is mcpKey; adjust host if your org uses a custom app URL).
• Auth: the three‑part API key must have the MCP flag enabled, or the endpoint returns 403.
• Transport: Streamable HTTP; after initialize, send mcp-session-id on follow‑up requests.
• Capabilities: fixed kebab‑case tools (IDs are passed as arguments, not encoded in tool names) covering full CRUD on entries (including delete) and on templates / groups / widgets, plus entry statuses, entry history, languages, media (list, folders, pre‑signed upload URL), pointer links, and trash. The full tool set is exposed to any MCP‑enabled key.
• Rich text: entry bodies use node trees (paragraph, heading, bulletList/orderedList, listItem, text, codeBlock, hardBreak, horizontalRule, widget, media — there is no image node); use get-entry-pointer-link and get-media-pointer-link for internal BCMS links in link marks.

Full tool names, resources, 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';

export const bcmsPrivate = new Client({ injectSvg: true });

export const bcmsPublic = new Client({
  apiKey: process.env.NEXT_PUBLIC_BCMS_API_KEY,
  injectSvg: true,
});

Scripts and servers: set BCMS_API_KEY and use new Client({ injectSvg: true, useMemCache: true, enableSocket: false }) (see scripts/init-client.ts). Follow thebcms.com/docs.

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.

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.