Shiplight AI Documentation

View as Markdown

Agents author tests. Humans stay in control.

Shiplight gives your coding agent eyes and hands in a real browser — it verifies UI changes and becomes the primary author and maintainer of YAML E2E tests. Humans stay in control because the tests are readable, live in your repo, and can be hand-tuned with the local debugger when a flow gets complex.

For a deeper look at the full Agent Workflow — MCP, Skills, YAML E2E tests, local debugging, and CI — 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 have your agent write YAML E2E tests by walking through your app in a real browser. Tests run locally with npx shiplight test, and the generated YAML is readable enough to review like a spec.

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 have your agent reproduce failures, diagnose root causes, and maintain the YAML E2E 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.

For complex UI flows, open the local debugger to step through the test, inspect screenshots and traces, edit YAML, and hand-tune the parts that need human judgment.

Step 5: Run in CI (optional)

Enterprise teams can run the same local YAML E2E tests on Shiplight-hosted CI runners and manage results in Shiplight. See the CI runner guide for the workflow setup.

Add a Shiplight CI runner workflow for ./tests and publish results after every run.

Configuration

Local MCP browser automation and YAML E2E test authoring do not require a Shiplight account or API token.

Next Steps

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