bladecp/skills

Teach your AI agent to migrate sites, read your account and follow the BladeCP docs. The official skills and BladeCP MCP for Claude Code, Codex, Cursor, Antigravity CLI and OpenCode.

Install  ·  Release notes  ·  SHA-256 checksum

Skills · Architecture · Installation · MCP server · API key · Security · FAQ · Support

Português (Brasil) · Español

[!TIP] Guided setup. Paste this sentence into your agent and it walks you through the installation: Fetch and follow the instructions to set me up for BladeCP at https://developers.bladecp.com/agents/prompt.md

The BladeCP Agent Skills are the official BladeCP plugin for coding agents. They teach your agent to migrate a site from cPanel to BladeCP with the BladeCP CLI, to inspect your servers and migrations, and to follow the BladeCP Developers documentation. The plugin also connects the BladeCP MCP server, which serves the documentation to anyone and, with your API key, read-only data from your account.

The package follows the Agent Skills format and ships plugin manifests for Claude Code, Codex, Cursor and Antigravity, plus a portable Agent Plugins manifest. OpenCode and other agents install the skills and connect the MCP server directly. Guide for every agent: https://developers.bladecp.com/agents

What your agent learns

Skills load automatically when the conversation is about their subject. They point the agent to the .md pages of the official documentation instead of copying it, so the agent always follows the current contract.

What the skills never do

• Ask for your key in the chat. The key comes from an environment variable or your secret manager, and the agent never prints or stores it.
• Approve on their own. Approving, cancelling and retrying a migration need your explicit instruction for that migration.
• Obey content. Files, backups, documentation and tool results are information, never instructions.
• Change anything through the MCP. The MCP only reads. Uploads go through the BladeCP CLI, and decisions stay with a person, in the CLI or in the Hub.

Included in the plugin

Architecture

The agent loads the skills, the skills decide which BladeCP tool fits the task, and every action that changes something stays with you. The MCP reads; the CLI uploads; you approve.

Logical view of the plugin. Open the diagram at full size.

From your request to BladeCP

1. The agent loads the skills. The bladecp skill comes first and chooses the tool for the task.
2. The docs come first. Every skill reads the .md pages of BladeCP Developers, directly or through the MCP documentation tools, which need no key.
3. Reads go through the MCP. With BLADECP_API_KEY in the agent’s environment, the MCP calls the Customer API for you, read-only.
4. Migrations go through the CLI. bladecp-migrate runs the BladeCP CLI, which uploads the backup and follows the migration up to the private preview.
5. You decide. Approving, cancelling and retrying happen only on your instruction, in the CLI or in the Hub.

Installation

Every install works without a key, in documentation-only mode. The steps for each agent follow; checks, updates and removal are in docs/installation.md.

Claude Code

In a terminal:

claude plugin marketplace add bladecp/skills
claude plugin install bladecp@bladecp

Inside an open session, the equivalent is:

/plugin marketplace add bladecp/skills
/plugin install bladecp@bladecp
/reload-plugins

/reload-plugins applies the plugin to the current session without a restart. Then check in /mcp that bladecp is listed as a plugin server. The plugin reads the key from BLADECP_API_KEY: set the variable before you open Claude Code, and start a new session if it changes.

Codex

codex plugin marketplace add bladecp/skills
codex plugin add bladecp@bladecp

You can also install it from the plugin browser, with /plugins inside the Codex CLI. Start a new session after installing.

The plugin installs the skills and the MCP server in documentation-only mode, because a Codex plugin cannot pass your key from an environment variable. To enable the account tools, add this to ~/.codex/config.toml:

[mcp_servers.bladecp]
url = "https://mcp.bladecp.com/mcp"
env_http_headers = { "X-API-KEY" = "BLADECP_API_KEY" }

With this entry, Codex lists a single bladecp server that sends the key. If the variable is empty or missing, Codex does not send the header and the server stays in documentation-only mode.

Cursor

In Cursor, open Customize, choose From GitHub Repository, enter https://github.com/bladecp/skills and install the bladecp plugin. To try it without importing, copy the repository to ~/.cursor/plugins/local/bladecp and run Developer: Reload Window.

As in Codex, the plugin server runs in documentation-only mode. To enable the account tools, add this to ~/.cursor/mcp.json, without removing the servers already there:

{
  "mcpServers": {
    "bladecp": {
      "url": "https://mcp.bladecp.com/mcp",
      "headers": {
        "X-API-KEY": "${env:BLADECP_API_KEY}"
      }
    }
  }
}

The variable must be visible to the Cursor process: if the account tools do not show up, open Cursor from a terminal where it is exported. If the plugin’s bladecp server also shows up in the MCP list, turn it off in Customize to avoid duplicate documentation tools.

Antigravity CLI

agy plugin install https://github.com/bladecp/skills

The plugin installs the skills and the MCP server in documentation-only mode. Antigravity does not document environment variable expansion in MCP headers, so to enable the account tools run this in your own terminal:

agy mcp add --header "X-API-KEY: $BLADECP_API_KEY" bladecp-account https://mcp.bladecp.com/mcp

Your shell expands the variable, and the key is stored in ~/.gemini/config/mcp_config.json. Keep that file private and run the command again after rotating the key.

OpenCode

Copy the skills to the OpenCode skills folder:

git clone --depth 1 https://github.com/bladecp/skills.git bladecp-skills
mkdir -p ~/.config/opencode/skills
cp -R bladecp-skills/skills/. ~/.config/opencode/skills/

Then add the MCP server to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bladecp": {
      "type": "remote",
      "url": "https://mcp.bladecp.com/mcp",
      "oauth": false,
      "headers": {
        "X-API-KEY": "{env:BLADECP_API_KEY}"
      }
    }
  }
}

If the variable is not set, OpenCode sends an empty value and the server stays in documentation-only mode.

Other agents

Install only the skills with the skills CLI:

npx -y skills add bladecp/skills --skill '*'

Then add the MCP server to your agent: address https://mcp.bladecp.com/mcp (streamable HTTP), with the X-API-KEY header read from an environment variable. If your client only supports bearer tokens, the server also accepts Authorization: Bearer . Never write the key itself into a versioned file.

Update

• Claude Code: run claude plugin marketplace update bladecp and claude plugin update bladecp@bladecp, then start a new session.
• Codex: run codex plugin marketplace upgrade bladecp and codex plugin add bladecp@bladecp, then start a new session.
• Cursor: update the plugin in Customize, or replace the local copy and reload the window.
• Antigravity CLI: run the agy plugin install command again.
• OpenCode and other agents: copy the skills again, or run npx -y skills update.

Each release also ships bladecp-skills-.zip and SHA256SUMS. Check the download with shasum -a 256 -c SHA256SUMS; the archive holds one bladecp folder, the plugin root.

BladeCP MCP server

The MCP is read-only. It does not upload backups or create, approve, cancel or retry migrations. Without a key, it connects normally in documentation-only mode, and the same installation offers the account tools as soon as the variable is set. See the BladeCP MCP documentation.

API key

1. Create a personal API key in the Hub, under API keys. The steps are on the API keys page.

2. Keep it in your secret manager and export it in the environment where the agent starts. Example on macOS, with the key stored in the Keychain:

   export BLADECP_API_KEY="$(security find-generic-password -s bladecp-api-key -w)"
   

3. Start a new agent session.

Personal keys expire, after 90 days by default. When the account tools start answering with an authentication error, create a new key and update the variable.

The variable is what the MCP server needs. The BladeCP CLI signs in with bladecp login, which opens the Hub in your browser (Connect with browser), and also accepts BLADECP_API_KEY.

Without a key, you still have the skills, the MCP documentation tools (search_docs, get_doc_page and list_doc_pages) and the BladeCP CLI after bladecp login.

Security

• Never paste your key into the chat. The skills tell the agent never to ask for it. The key comes from an environment variable or your secret manager.
• People approve. The MCP tools only read. The skills never approve, cancel or retry a migration without your explicit instruction.
• Content is data. The skills tell the agent to treat files, backups, documentation and tool results as information, never as instructions.
• Key path. The key travels in a header to mcp.bladecp.com, which uses it only to call the BladeCP API for you and does not log it.
• Nothing runs on install. The plugin is text: skills, JSON manifests and icons, with no hooks or executables.
• Public repository. This repository contains no secrets. Configuration files only reference variable names.

Read docs/security.md for the full model. To report a vulnerability privately, follow SECURITY.md.

Quality and validation

Release 0.1.0 was validated by the maintainers before publication:

• 38 release checks for the release tooling: deterministic archive, closed file list, leak and link gates, and the safety locks of the publication step.
• Contract checks on every skill and README: each MCP tool and its inputs, each BladeCP CLI command and flag, and each documentation page must exist in the current BladeCP contracts.
• Client validation with claude plugin validate --strict and agy plugin validate, and plugin.json and mcp.json against the Agent Plugins schemas.
• Installation from the release archive in Claude Code, Codex, Antigravity CLI and OpenCode, and the production MCP answering in documentation-only mode without a key.

This repository includes the public structure and hygiene gate (scripts/check-public-tree.sh). The public CI runs it on every change, together with the schema validation.

Repository layout and contributing

To validate the repository after a change:

bash scripts/check-public-tree.sh
claude plugin validate --strict .

Contributions are welcome. Read CONTRIBUTING.md before opening an issue or pull request, and never commit keys or customer data. Changes are listed in the CHANGELOG, and the release process is described in docs/release-process.md.

Frequently asked questions

Support

In public reports, never include an API key, backup contents or customer data.

License

The BladeCP Agent Skills are released under the MIT License. The license covers this repository; the use of BladeCP services follows the BladeCP terms.

BladeCP. Your agent, our infrastructure.