# Shiplight AI Documentation

<div class="view-markdown-wrapper">
<ViewMarkdown />
</div>

### 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?](/getting-started/what-is-shiplight).

## Step 1: Add MCP and Skills

Skills install via [`skills`](https://www.npmjs.com/package/skills); the MCP server installs via [`add-mcp`](https://www.npmjs.com/package/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`).

<details>
<summary><strong>Claude Code</strong></summary>

```bash
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
```

</details>

<details>
<summary><strong>Cursor</strong></summary>

```bash
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.

</details>

<details>
<summary><strong>VS Code</strong></summary>

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

```bash
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
```

</details>

<details>
<summary><strong>Codex</strong></summary>

```bash
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
```

</details>

<details>
<summary><strong>Gemini CLI</strong></summary>

```bash
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
```

</details>

<details>
<summary><strong>Copilot CLI</strong></summary>

Requires **Copilot Pro+** — select **GPT-5.4** or **Claude Opus 4.6** as your model. Install [Copilot CLI](https://github.com/features/copilot/cli) first.

```bash
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
```

</details>

<details>
<summary><strong>Claude Desktop</strong></summary>

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

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

</details>

<details>
<summary><strong>Zed</strong></summary>

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

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

</details>

<details>
<summary><strong>OpenCode</strong></summary>

```bash
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
```

</details>

<details>
<summary><strong>Antigravity</strong></summary>

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

```bash
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
```

</details>

### Other agents

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

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

See the [full list of agents](https://github.com/vercel-labs/skills#supported-agents).

### Manual MCP config

For agents that [`add-mcp`](https://www.npmjs.com/package/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):

```json
{
  "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:

```bash
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](https://app.shiplight.ai/settings/api-tokens), 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](https://app.shiplight.ai/settings/api-tokens). | —       |

## Next Steps

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