Shiplight AI Documentation

View as Markdown

AI does the work. Humans take control.

Shiplight gives your coding agent eyes and hands in a real browser — it builds features, verifies they work, and auto-generates regression tests, all in one flow. No manual testing, no context switching, no account needed.

For a deeper look at everything included (free browser automation vs optional AI/cloud features), see What is Shiplight AI?.

Step 1: Add MCP and Skills

Skills install via skills; the MCP server installs via add-mcp. Add -g to either command for a user-level (global) install. Restart your agent after install.

Common agents

Each block below is copy-paste ready (non-interactive via -y).

Claude Code

npx -y skills add ShiplightAI/agent-skills -a claude-code -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a claude-code -y

Cursor

npx -y skills add ShiplightAI/agent-skills -a cursor -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a cursor -y

Cursor disables newly-added MCP servers by default. Enable it: Cursor → Settings… → Cursor Settings → Tools & MCPs → Installed MCP Servers → shiplight (Disabled) — toggle the switch to enable.

VS Code

VS Code reads skills via the GitHub Copilot extension. Install skills under github-copilot and the MCP server under vscode:

npx -y skills add ShiplightAI/agent-skills -a github-copilot -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a vscode -y

Codex

npx -y skills add ShiplightAI/agent-skills -a codex -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a codex -y

Gemini CLI

npx -y skills add ShiplightAI/agent-skills -a gemini-cli -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a gemini-cli -y

Copilot CLI

Requires Copilot Pro+ — select GPT-5.4 or Claude Opus 4.6 as your model. Install Copilot CLI first.

npx -y skills add ShiplightAI/agent-skills -a github-copilot -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a github-copilot-cli -y

Claude Desktop

Claude Desktop consumes MCP tools but doesn't run skills. MCP only:

npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a claude-desktop -g -y

Zed

Zed consumes MCP tools but doesn't run skills. MCP only:

npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a zed -y

OpenCode

npx -y skills add ShiplightAI/agent-skills -a opencode -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a opencode -y

Antigravity

Antigravity's MCP config is user-level only, so add-mcp needs -g:

npx -y skills add ShiplightAI/agent-skills -a antigravity -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a antigravity -g -y

Other agents

skills supports 40+ agents — Windsurf, Warp, Roo, Continue, Junie, Kiro, Trae, OpenHands, and more. Install skills via:

npx -y skills add ShiplightAI/agent-skills -a <agent> -y

See the full list of agents.

Manual MCP config

For agents that add-mcp doesn't cover, add the MCP server manually. Paste this into your agent's MCP config file (location varies — check your agent's docs):

{
  "mcpServers": {
    "shiplight": {
      "command": "npx",
      "args": ["-y", "@shiplightai/mcp@latest"],
      "env": {
        "PWDEBUG": "console"
      }
    }
  }
}

Updating

The MCP server always runs the latest release via npx -y @shiplightai/mcp@latest — no update step needed.

Skills are pinned locally. Update them with:

npx -y skills update -p   # project-level
npx -y skills update -g   # user-level (global)

Step 2: Verify UI changes

After your coding agent makes frontend changes, use /verify to have it open a browser, inspect the page, and confirm the result.

Update the navbar to include "Pricing" and "Blog" links, then use /verify to confirm they appear correctly on localhost:3000.

Step 3: Create regression tests

Use /create-tests to scaffold a test project and write YAML tests by walking through your app in a real browser. Tests run locally with npx shiplight test.

Use /create-tests to set up a test project at ./tests and write a login flow test for localhost:3000.

Step 4: Triage failing tests

When tests break after UI changes, deployments, or flow updates, use /triage to automatically reproduce failures, diagnose root causes, and fix the YAML tests. If the application itself is broken, triage reports the bug without modifying tests.

Use /triage to fix failing tests in ./tests after the latest deployment.

Step 5: Sync to cloud (optional)

With a Shiplight account, use /cloud to sync local tests to the cloud for scheduled runs, team collaboration, and result tracking. Set SHIPLIGHT_API_TOKEN in your project's .env to enable cloud tools.

Use /cloud to sync all test cases in ./tests to Shiplight cloud.

Configuration

Variable	Required	Description	Default
SHIPLIGHT_API_TOKEN	For cloud features	Shiplight API token — enables cloud sync tools. Get your token from app.shiplight.ai/settings/api-tokens.	—

Next Steps

• Browser Automation - Full reference for browser automation tools and actions
• Understanding YAML Test Format - Statement types, actions, conditionals, loops, variables, and templates
• Local Testing - Export tests as standalone Playwright files for local or CI execution
• Cloud Testing - Create test cases, trigger cloud runs, and analyze results