@bettercms-ai/install
Installs the BetterCMS agent skills into the coding agents on your machine.
npx @bettercms-ai/install
In a terminal it asks at most two things, each with the likely answer already picked, so pressing Enter through it is a normal install:
┌ BetterCMS agent setup v0.4.44
│
◇ Where do you want to install the BetterCMS skills?
│ Globally
│
◇ Configure BetterCMS MCP and agent skills for these editors?
│ Claude Code, Codex CLI, Cursor, Zed
│
◆ MCP configured for Claude Code, Codex CLI, Cursor and Zed
│
◆ BetterCMS agent skills installed (24):
│ ~/.claude/skills 24 installed
│ Claude Code /bettercms
│ ~/.codex/skills 24 installed
│ Codex CLI $bettercms
│ ~/.cursor/skills 24 installed
│ Cursor /bettercms
│
└ Restart Claude Code, Codex CLI, Cursor and Zed and type "set up BetterCMS for this site" in the chat.
- Where: "This project" is offered first inside a project (a folder with
package.json,.gitor 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. - Editors: one question covers both the skills and the MCP. Claude Code, Codex CLI, Cursor, VS Code and Zed are always offered; the ones found on your machine are ticked. Untested agents are listed when installed, and labelled.
- Skills: all of them. Name skill ids as arguments to install fewer.
- MCP: the hosted BetterCMS MCP goes into each editor's user-level config (
--no-mcpskips it). It never overwrites an existingbettercmsentry 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,vscode,zed --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
unchangedinstead of rewriting, an upgrade prunes what a new version dropped, and--removedeletes exactly what it wrote and nothing else. - Shows before it writes. The guided flow lists every folder and config it will touch;
--dry-rundoes the same in a script.
Options
| Option | Meaning |
|---|---|
[skill-ids...] | Install only these skills, by id (bettercms, bettercms-migrate, bettercms-abm); the ids are the folders under packages/skills. The default is all three. |
--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 |
| Codex CLI | ~/.codex/skills | .agents/skills | yes |
| Cursor | ~/.cursor/skills | .agents/skills | yes |
| VS Code (Copilot) | ~/.copilot/skills | .agents/skills | yes |
| Zed | (no skills folder: MCP only) | yes | |
| Amp | ~/.config/amp/skills | .agents/skills | no |
| Gemini CLI | ~/.gemini/skills | .agents/skills | no |
| OpenCode | ~/.config/opencode/skills | .agents/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 |
Project roots follow vercel-labs/skills: the agents that read the shared .agents/skills get one copy there, not one each.
"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.mdbody goes intoglobal_rules.mdbetween<!-- 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.
Without --mcp, 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.
--removedeletes 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 abettercms-*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 connects the hosted BetterCMS MCP (https://mcp.bettercms.ai; --api dev uses https://mcp.bettercms.dev, any other API its own /mcp). The entry goes into each editor's user-level config, in that editor's own shape:
| Editor | Where | Entry |
|---|---|---|
| Claude Code | claude mcp add --transport http -s user bettercms <url> (JSON printed if the claude CLI is not on your PATH) | |
| Codex CLI | ~/.codex/config.toml | [mcp_servers.bettercms] url = "<url>" |
| Cursor | ~/.cursor/mcp.json | mcpServers.bettercms: { url } |
| VS Code (Copilot) | the user mcp.json (~/.config/Code/User, ~/Library/Application Support/Code/User, %APPDATA%\Code\User) | servers.bettercms: { type: "http", url } |
| Zed | ~/.config/zed/settings.json | context_servers.bettercms: { url } |
| Gemini CLI | ~/.gemini/settings.json | mcpServers.bettercms: { httpUrl } |
| Other agents | JSON snippet printed |
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. A config file that is not plain JSON (Zed's settings allow comments) is left untouched, and the snippet is printed for you to paste. You sign in on the first tool call, in the browser.
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