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

Or via ClawHub for OpenClaw:

openclaw skills install @bcms/bcms
openclaw skills install @bcms/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 scoped API key (BCMS_API_KEY). Interactive MCP uses a separate per-project MCP key (not scoped). 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).

Maintainer commands (root package.json): npm run sync (reference sync), npm run check (sync + link/version validation), npm run package (rebuild dist/agent-resources/ and copy-mode plugin packages under dist/packages/ for symlink-less publishing), npm run validate:release (the full CI release gate), npm test (CLI tests against a mocked client). See AGENTS.md for the release workflow.

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)

• 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).

• 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 keys to browsers, public repos, or client bundles. MCP keys are per-project credentials (not scoped API keys) for trusted agents and local config only; 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.

• 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.) Configure MCP with a project MCP key (mcpKey query param). MCP keys are not scoped — they generally access all entries, templates, groups, widgets, and media. Do not embed those keys in shipped apps. See thebcms.com/agents, references/mcp.md, and BCMS MCP documentation.

BCMS hosts an MCP server so assistants can work with BCMS content and schema using an MCP key. 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: an MCP key (not an API key). MCP keys are per-project and not template/media-scoped — generally full access to entries, templates, groups, widgets, and media.
• 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.
• 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.

Agent gotchas, resources, troubleshooting, and MCP vs SDK guidance: references/mcp.md.

• 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.

• 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 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 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.

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.

• 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 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.

• 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.