@bettercms-ai/install

Installs the BetterCMS agent skills into the coding agents on your machine.

npx @bettercms-ai/install

In a terminal it asks four things, each with the likely answer already picked, so pressing Enter through it is a normal install:

┌  BetterCMS skills installer v0.1.0
◇  Where do you want to install the BetterCMS skills?
│  This project (~/sites/acme)
◇  Which coding agents should get them?
│  Claude Code, Cursor, Codex
◇  Which skills?
│  bettercms, bettercms-components, bettercms-content-modeling, bettercms-frameworks, bettercms-inline-editing
◇  Connect the BetterCMS MCP too? The skills need it to reach your site (sets it up in Claude Code, Cursor; shows setup for Codex).
│  Yes
◇  About to write ─────────────────────────────────────────────╮
│  5 skills into:                                              │
│    Claude Code  ./.claude/skills                             │
│    Cursor       ./.cursor/skills                             │
│    Codex        ./.codex/skills                              │
│  MCP (no credential is written):                             │
│    Claude Code  claude mcp add-json bettercms (user scope)   │
│    Cursor       ~/.cursor/mcp.json                           │
│    Codex        shows TOML snippet for ~/.codex/config.toml  │
├──────────────────────────────────────────────────────────────╯
◇  Go ahead?
│  Yes
◆  Claude Code  5 installed  /bettercms
◆  Cursor  5 installed  /bettercms
◆  Codex  5 installed  $bettercms
◆  Claude Code MCP  connected
◆  Cursor MCP  connected
└  You're all set: the BetterCMS skills work in this project. Next: ask your agent "set up BetterCMS for this site"; it will ask you to sign in once.

• Where: "This project" is offered first inside a project (a folder with package.json, .git or an agent folder). A project with no agent folder yet gets the agents you have installed, and their folders are created. In your home directory, "Globally" is offered first.
• Agents: the ones found on your machine, ticked. Untested agents are labelled.
• MCP: never overwrites an existing bettercms entry and never writes a credential. You sign in the first time your agent uses it.

Scripted, the same install is:

npx @bettercms-ai/install --global          # every detected agent, in your home directory
npx @bettercms-ai/install --project -y      # agent folders inside the current project
npx @bettercms-ai/install -g --agents claude,cursor --mcp

Why this installer

• Offline. The skills ship inside the package. Installing makes no network request and needs no account or token.
• Knows what it wrote. A receipt lists every file with its sha256, so a re-run reports unchanged instead of rewriting, an upgrade prunes what a new version dropped, and --remove deletes exactly what it wrote and nothing else.
• Shows before it writes. The guided flow lists every folder and config it will touch; --dry-run does the same in a script.

Options

| Option | Meaning | | --- | --- | | [skill-ids...] | Install only these skills. forms and bettercms-forms both work. The default is all of them. | | --global, -g | Use the agent roots under your home directory. | | --project | Use the agent roots under the current directory. | | --agents a,b | Choose the agents. By default, every agent whose directory already exists is used. | | --mcp | Also register the BetterCMS MCP server (see below). | | --api <rung\|url> | The API that --mcp points at: prod (default), dev, local, or a full https:// URL. Any other value exits 2. | | --remove | Delete what an earlier install wrote. Removes every skill, or only the ids you give. | | -y, --yes | Skip the confirmation prompt. | | --dry-run | Print the outcome lines without writing anything. |

Without a terminal (CI, a pipe) or with -y, nothing is asked. With no --global or --project, a project folder (one with an agent folder, or a package.json or .git while some agent is installed for you) means --project; anywhere else the command exits 2 rather than guessing. -y never connects the MCP: that takes --mcp.

In a scripted run, each agent/skill pair prints one line: installed, updated, unchanged, removed, exists-unmanaged, skipped: <reason> or failed: <reason>. exists-unmanaged means a bettercms-<id> folder is already there and no receipt lists it. The installer writes nothing into that folder and carries on with the other skills. The exit code is 0 when nothing failed, 1 when anything failed or was exists-unmanaged, and 2 for a usage error. A build with no skills bundled also exits 2.

What gets written where

Each skill is copied to <root>/bettercms-<id>/. Skill ids that already start with bettercms- keep their name as is.

| Agent | --global root | --project root | Tested | | --- | --- | --- | --- | | Claude Code | ~/.claude/skills | .claude/skills | yes | | Cursor | ~/.cursor/skills | .cursor/skills | yes | | Codex | ~/.codex/skills | .codex/skills | yes | | Amp (shared .agents) | ~/.config/amp/skills | .agents/skills | no | | Gemini CLI | ~/.gemini/skills | .gemini/skills | no | | OpenCode | ~/.config/opencode/skills | .opencode/skills | no | | Pi | ~/.pi/agent/skills | .pi/skills | no | | Antigravity | ~/.gemini/antigravity/skills | .gemini/antigravity/skills | no | | Windsurf | ~/.codeium/windsurf/memories/global_rules.md | .windsurf/rules/bettercms-<id>.md | no |

"Untested" means the root follows the convention other skill installers use, but nobody has checked that the agent actually loads skills from it. These rows are marked with * in the output.

Windsurf has no skills folder:

• Global: each skill's SKILL.md body goes into global_rules.md between <!-- bettercms:<id>:begin v=<version> --> and <!-- bettercms:<id>:end -->. A re-run replaces the whole block, so you never end up with two copies. Anything you wrote outside the markers stays as it was.
• Project: each skill becomes one rule file.

In both cases only SKILL.md is carried over. Reference files are not.

With --mcp and no other flags, the installer writes only inside the agent roots above.

Receipts, upgrades, uninstall

Each root gets a .bettercms-skills.json receipt. It lists every file the installer wrote, with its sha256.

• Re-running the same version changes nothing. Files are only written when their bytes differ, and the receipt is only rewritten when its contents change.
• Upgrading writes the new files. Files the new version no longer ships are deleted, and so are skills that were renamed or retired.
• --remove deletes exactly the files listed in the receipt, then any directories that left empty, then the receipt entry. The receipt file itself goes once it is empty. Anything not in the receipt is never deleted, including files you added inside a bettercms-* folder.

Before anything is written, the installer checks the bundled manifest and every file hash. Every write and delete path must resolve inside the chosen root, and the installer refuses to go through a symlink below the root.

--mcp

--mcp adds one stdio server entry:

{ "command": "npx", "args": ["-y", "@bettercms-ai/mcp"], "env": { "BETTERCMS_API_URL": "https://api.bettercms.ai" } }

• Claude Code: runs claude mcp add-json bettercms '<json>' -s user if the claude CLI is on your PATH. Otherwise it prints the JSON for you to add.
• Cursor: merges the entry into ~/.cursor/mcp.json under mcpServers.bettercms.
• Codex: prints a TOML snippet for ~/.codex/config.toml. Nothing is written, because this path is untested.
• Other agents: prints the JSON snippet.

If a bettercms entry already exists, the result is skipped: exists. The installer never overwrites or merges into that entry, and never writes a token or credential. You sign in on the first tool call, through the MCP server's own device flow.

--api sets BETTERCMS_API_URL. dev resolves to https://dev-api.bettercms.ai.

Remote MCP instead

You don't need a local server. Hosted MCP runs at https://mcp.bettercms.ai, and you can add it as a remote (HTTP) MCP server in any client that supports one. This installer does not configure it.

Development

prepack runs scripts/build-manifest.mjs. It copies every packages/skills/<id>/ that contains a SKILL.md into skills/, and writes manifest.json plus .claude-plugin/{plugin.json,marketplace.json}. The build fails on a skill with no name or description, on a symlink, and on any unsafe path. The generated files are gitignored.

bun test test/install.test.js
bun test test/build-manifest.test.js