SHIP

View saved version →

---
name: ship-agent-runs
description: Use when the user wants to read an agent's log, find why a run failed, follow a run live or stop an agent. It reads and controls the agent runs of SHIP missions, and each run is one agent in its own sandbox. List the runs of a mission or of the organization, and read the status, resource use and cost of one run. Read what the agent did from its log, follow one run live until it ends, and stop one run. For example, the user asks "what did the builder do on SHIP-412", "why did the QA run fail" or "show me the agent log". Also use it when the user says "stop that agent", or to find the run that makes a mission slow or expensive.
---

# Read and control agent runs

A mission is the work that SHIP does for one issue. The agents of a mission do that work in runs. A run is one agent
in its own sandbox, for example one Planner run, three Builder runs and one QA run. The id of a run is its sandbox id,
such as `builder-ship-412-3f9c41aa-coding-1`.

This skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at
<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do
the setup too. If its `version` is older than `ship --version`, run `ship init --force`.

| Command | Token scope |
| --- | --- |
| `ship run list`, `ship run get`, `ship run logs`, `ship run watch` | `sandboxes:read` |
| `ship run stop` | `sandboxes:stop` (an org admin's token) |

## When to use it

- The user asks what an agent does now, or what it did.
- You must wait for a run to end before your next step.
- A run failed, and you must find the cause before you send an instruction to the mission.
- A mission costs more or takes longer than the user expects, and you must find the run that is the cause.
- The user asks you to stop one agent.

To read the state of the mission itself, or to send it feedback, use the `ship-missions` skill.

## Find the runs of a mission

```bash
ship status SHIP-412
ship run list --mission SHIP-412
```

`ship status` lists the runs of the mission, oldest first, with the id of each run. The current run has the mark
`(current)`. `ship run list` gives the same runs with their harness and start time, newest first.

You can also find runs across the organization. A list covers every project of the token, unless `--project` names one.
`SHIP_PROJECT_ID` does not narrow a list.

```bash
ship run list --status running
ship run list --mission SHIP-412 --role qa
ship run list --status failed --limit 20 --json
ship run list --status failed --limit 20 --cursor eyJhIjoxfQ
```

When more runs match, the last line gives the `--cursor` for the next page. Give the same filters with it. A status is `running`, `completed`, `stopped`, `failed` or `stale`. A `stopped` run ended on purpose before it finished,
for example because a newer run replaced it. A `stale` run closed without a report, after its time limit. A role is
`planner`, `builder`, `reviewer` or `qa`.

## Read one run

```bash
ship run get builder-ship-412-3f9c41aa-coding-1
```

The command prints the mission and the role of the run, its status, and the reason when a run ended early. It also
prints the harness and the size of the sandbox, the start and end time, and the latest CPU, memory and disk use. The
`session` line is the session of this run, with its outcome and its cost. The `other` line names the sessions of other
runs with the same role. Their cost is not part of the cost of this run.

## Watch a run live

```bash
ship run watch builder-ship-412-3f9c41aa-coding-1
ship run watch qa-ship-412-77d0e2c1-qa-1 --max-seconds 300
ship run watch qa-ship-412-77d0e2c1-qa-1 --since 118
```

The command prints the last events of the agent. Then it prints each new event on one line, for example a thought, a
tool call or an error. It also prints a line when the mission moves to another stage.

When the run ends, the command exits 0 if the run completed, and 7 if it ended in a

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: ship-delegate
description: Use when the user wants to hand a plan, a spec or an open pull request to SHIP. It hands work to the SHIP AI agent team from this repository. Delegate a plan or a spec that you wrote, so SHIP builds it. Delegate a branch with an open pull request, so SHIP runs code review and tests on it and makes it ready to merge. For example, the user says "delegate this", "hand this to SHIP", "let SHIP build this", "let SHIP review this" or "ship this spec". Also use it when the user finishes a plan or a change and asks what to do next.
---

# Hand work to SHIP

Two hand-offs, each one command. SHIP starts a mission for the work, and its agents plan, build, review and test it.

This skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at
<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do
the setup too. If its `version` is older than `ship --version`, run `ship init --force`.

| Command | Token scope |
| --- | --- |
| `ship delegate plan` | `missions:run` |
| `ship delegate pr` | `missions:run` |

## When to use it

- The user wrote a plan or a spec and wants SHIP to build it, not you.
- The user finished code on a branch and wants SHIP to review it, test it and make it ready to merge.

Do not delegate work that you are in the middle of, unless the user asks. Finish or stop first, so that the hand-off
has a complete plan or a complete branch. To read the state of a mission or to send it feedback after the hand-off,
use the `ship-missions` skill.

## Hand over a plan

Write the plan to a file first, then delegate it. SHIP skips its own Planner and builds from your spec as you wrote it.

```bash
# For an issue that already exists
ship delegate plan SHIP-412 --file docs/plan.md

# No issue yet: create one and start the mission in the same call
ship delegate plan --title "Rate-limit the search endpoint" --file docs/plan.md
```

If you know the files that the plan changes, name them with `--file-plan <path.json>`. The file is a JSON array of
`{path, action, description}`. Without it, the Builder chooses the files.

## Hand over a branch

Open the pull request yourself, then delegate it. SHIP never pushes a branch or opens a pull request for you. If the
`gh` CLI is available, the command reads `--pr` from the current branch.

```bash
ship delegate pr SHIP-412              # review, then test, then merge
ship delegate pr SHIP-412 --at qa      # already reviewed: only test it
ship delegate pr                       # no issue: SHIP names the mission after the pull request
```

If CI fails on that pull request, SHIP fixes the failure before the review. That is expected, not an error.

## Choose the harness, model or sandbox for one mission

These flags change how this one mission runs. They take priority over the `ship.yml` of the project and do not change
the file. They apply to the role that the mission starts at: the Builder for `delegate plan`, and the Reviewer or the
QA agent for `delegate pr`.

```bash
ship delegate plan SHIP-412 --file docs/plan.md --harness codex
ship delegate plan SHIP-412 --file docs/plan.md --model opus
ship delegate pr SHIP-412 --at qa --harness open-code --model z-ai/glm-5.2
ship delegate plan SHIP-412 --file docs/plan.md --sandbox python-uv --size standard-2
```

The harnesses are `claude-code`, `codex`, `pi`, `kilo-code` and `open-code`. You can give `--model` without
`--harness`, and the configured harness stays. `--sandbox` names a custom sandbox (see the `ship-sandboxes` skill), and
`--size` sets the machine size for this mission.

Use these flags when the user asks for a specific agent, model or sandbox, or to compare two of them on the same work.
Otherwise, leave them out. The configuration of the project is the setting that the team agreed on.

## The configuration of the project

That configuration is `ship.yml` at the root of the repository. It sets the harness and the mo

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: ship-mcp-servers
description: Use when the user wants the SHIP agents to use an MCP server, or asks which MCP servers the agents can use. It lets the SHIP agents use the MCP servers that this repository declares. Bind a server to agent roles with a credential, approve its tools, start an OAuth sign-in, choose the MCP file or remove a binding. For example, the user says "let the SHIP agents use our GitHub MCP server" or "give the planner Linear access".
---

# Give the agents MCP servers

The SHIP agents can use the MCP servers that the repository declares in its MCP file, which is `.mcp.json` by default.
SHIP never loads that file on its own. A server reaches the agents only through a binding. A binding names the agent
roles that may use the server, the tools that they may call, and the credential that SHIP attaches. The agents never
see the credential.

This skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at
<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do
the setup too. If its `version` is older than `ship --version`, run `ship init --force`.

| Command | Token scope |
| --- | --- |
| `ship mcp list`, `ship mcp bindings` | `connectors:read` |
| `ship mcp tools` without flags | `connectors:read` |
| `ship mcp bind`, `ship mcp connect`, `ship mcp remove`, `ship mcp file` | `connectors:write` |
| `ship mcp tools --refresh`, `ship mcp tools --approve` | `connectors:write` |

Changes also need the admin or owner role in the organization. A token never has more access than the person who
created it.

## See what the repository declares

```bash
ship mcp list --project prj_123
ship mcp bindings
```

`ship mcp list` shows the servers in the MCP file of one project and the binding of each. `ship mcp bindings` shows
every binding in the projects of your organization. Neither command shows a credential value. They show only the names
of the fields that are set.

## Bind a server

`--roles` lists every agent that may use the server: `planner`, `builder`, `reviewer` and `qa`, or `none`. The Reviewer
and the QA agent get only the tools that read, and they cannot use a server that runs inside the sandbox.

```bash
ship mcp bind github --roles planner,qa --header-file Authorization=gh.txt
ship mcp bind sentry --roles qa --env-var-file KEY=t --allow-host sentry.io
ship mcp bind linear --roles planner,builder --no-credential
```

Give credentials as files, so that they stay out of the shell history. Do not put a token in a command line.

- `--header-file <Name=path>`: a request header for a remote server. The file holds the complete value, for example
  `Bearer <token>`. You can give the flag more than one time.
- `--env-var-file <NAME=path>` with `--allow-host <host>`: an environment variable for an isolated server, and the hosts
  that the credential may go to. These flags imply `--transport isolate`.
- `--no-credential`: bind with no credential, and remove a stored one.

Without a credential flag, the binding keeps the credential that it has.

`--transport` is `remote`, `isolate` or `local`. With `remote`, SHIP sends requests to the URL of the server. With
`isolate`, SHIP runs the npm package of the server in isolation, so that the server can hold a secret. With `local`, the
server runs inside the sandbox with no credential. The default is what the declaration of the server allows. `--url`
sets a fixed https URL for the server. Without `--transport` or `--url`, the binding keeps its current server.

## Approve the tools

A new binding gives the agents no tools. Approve them after you bind the server:

```bash
ship mcp tools github --refresh
ship mcp tools github --approve get_issue,get_file --attest get_file
```

Without flags, the command prints the last tool list of the server, with the approval of each tool and whether it only
reads. The `--refresh` flag gets the current list from the server first. The `--approve` fl

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: ship-missions
description: Use when the user wants to follow a SHIP mission, check its status, or pass it feedback, review comments or a decision while it runs. It follows, controls and finishes the SHIP missions that you or the user started. List missions, read the state of one, and send it instructions or feedback. Pause, resume, stop, restart, merge or decline a mission, approve a checkpoint or a credit limit, and read its preview, proof and credits. For example, the user asks "what is the status of SHIP-412", "is SHIP done with it" or "tell SHIP to change X". Also use it when the user says "pause that mission" or "merge it", or asks for a change in one line.
---

# Follow and steer a mission

A mission is the work that SHIP does for one issue. Use this skill after a hand-off (see the `ship-delegate` skill), to
read the state of a mission, to send it new information and to finish it. To read what one agent did inside a mission,
use the `ship-agent-runs` skill.

This skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at
<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do
the setup too. If its `version` is older than `ship --version`, run `ship init --force`.

| Command | Token scope |
| --- | --- |
| `ship status`, `ship mission list` | `missions:read` |
| `ship instruct`, `ship mission pause`, `ship mission resume`, `ship mission stop` | `missions:write` |
| `ship mission merge`, `ship mission decline`, `ship mission auto-merge` | `missions:write` |
| `ship mission archive`, `ship mission unarchive`, `ship mission disposition` | `missions:write` |
| `ship mission create`, `ship mission start`, `ship mission approve-ceiling` | `missions:run` |
| `ship mission override get` | `agents:read` |
| `ship mission override set` | `agents:read` and `agents:write` |
| `ship mission override clear` | `agents:write` |
| `ship mission inspect` | `inspect:read` |
| `ship preview list`, `ship preview get` | `environments:read` |
| `ship preview destroy` | `environments:write` |
| `ship artifact list`, `ship artifact get` | `artifacts:read` |
| `ship credits`, `ship credits offers`, `ship credits request`, `ship setup`, `ship notice list`, `ship notice dismiss` | any token |
| `ship credits ledger`, `ship credits buy`, `ship credits plan` | any token, with an owner or admin behind it |

The controls also need a role in the organization that can control missions. Archive and disposition need an owner or
an admin. Without `--project`, the override commands read the project from the mission, so the token also needs
`missions:read`. A token never has more access than the person who created it.

## See the missions

```bash
ship mission list
ship mission list --activity needs_attention
ship mission list --search "rate limit" --json
ship mission list --project prj_123 --offset 25
```

The list shows each mission with what it does now, its stage and its pull request. The `--activity` flag takes the
values of the status filter in the console, for example `building`, `reviewing`, `testing`, `ready_to_merge`,
`needs_attention` or `paused`. The list covers every project of the token, unless `--project` names one.
`SHIP_PROJECT_ID` does not narrow a list. When more missions match, the last line gives the `--offset` of the next
page.

## Read the state of a mission

```bash
ship status SHIP-412
ship status SHIP-412 --json    # for jq
```

The command prints the stage of the mission, its review state, its test state and its pull request. It also lists the
agent runs of the mission, and the run whose artifacts are the proof of the work. Read it before you tell the user that
work is complete.

## Start a mission from a request

When the user asks for a change in one line and there is no plan or branch yet, let SHIP plan it:

```bash
ship mission create --title "Fix the login redirect" --description "- [ ] Login returns to the page it came fro

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: ship-sandboxes
description: Use when the SHIP agents need a runtime or a tool that is not in their sandbox, or a mission waits for an agent slot. It manages the sandboxes that the SHIP agents run in. Add runtimes and tools to a custom sandbox, build it, read its build log and roll it back. Make a sandbox the default of a project, and connect private package registries. Also read how many agents your missions run at the same time. For example, the user says "the agents need Python", "add a JDK to the SHIP sandbox" or "why does my mission wait".
---

# Manage the sandboxes that agents run in

Every SHIP agent runs in a sandbox. The platform base has what the agents need to run. A custom sandbox adds
steps to that base, for the runtimes and tools that a repository needs. Each change to a sandbox is a new version, and
missions start from the active version.

This skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at
<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do
the setup too. If its `version` is older than `ship --version`, run `ship init --force`.

| Command | Token scope |
| --- | --- |
| `ship sandbox list`, `ship sandbox starters`, `ship sandbox versions`, `ship sandbox logs` | `agents:read` |
| `ship sandbox create`, `ship sandbox update`, `ship sandbox build`, `ship sandbox rollback`, `ship sandbox delete` | `agents:read` and `agents:write` |
| `ship sandbox default` | `projects:admin` |
| `ship sandbox registry list` | `connectors:read` |
| `ship sandbox registry set`, `ship sandbox registry remove` | `connectors:write` |
| `ship sandbox capacity` | `sandboxes:read` |

Changes also need the admin or owner role in the organization. A token never has more access than the person who
created it.

## See the sandboxes and starters

```bash
ship sandbox list
ship sandbox starters
```

The `ship sandbox list` command shows each custom sandbox with its active version, its size and whether its last build
is ready. The `ship sandbox starters` command shows the starter definitions for Python, Java, Go, Rust and Ruby. Each
starter has a size that fits it.

## Create a sandbox

```bash
ship sandbox create --name python-uv --starter python --wait
ship sandbox create --name ml --file ml.Dockerfile --size 2x8192x16000
```

The Dockerfile has steps only: `RUN`, `ENV`, `ARG` and `WORKDIR`. The platform supplies the base, so the file has no
`FROM`. There is also no build context, so `COPY` cannot work. The first build starts immediately. With `--wait`, the
command shows the build log until the build finishes, and exits 7 with the reason if the build fails.

`--size` is `standard-1` to `standard-4`, or a custom `<vcpu>x<memoryMib>x<diskMb>`. A custom size has 1 to 4 vCPU and
8000 to 20000 MB of disk. Its memory is at least 3072 MiB for each vCPU, and at most 12288 MiB.

## Change, build and roll back

```bash
ship sandbox update python-uv --file sandbox.Dockerfile --wait
ship sandbox update sbt_1a2b --size standard-4
ship sandbox build python-uv --wait
ship sandbox logs python-uv --follow
ship sandbox logs sbt_1a2b --build tbd_9f8e
ship sandbox versions python-uv
ship sandbox rollback python-uv --to 2
```

A new definition or size becomes the next version. SHIP makes that version active and builds it. A mission that starts
before the build finishes waits for it, and if the build fails, the mission stops with the reason. A new `--name` alone
does not start a build. A sandbox argument can be the id or the name.

The `ship sandbox build` command builds the active version now. If a build is already in progress, the command returns
that build. The `ship sandbox logs` command prints the log of the last build, or of the build that `--build` names. The
`--follow` flag shows the log until the build finishes.

You cannot change a version, but the `ship sandbox rollback` command makes an earlier version active. If
the snapshot of that

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: ship-scheduled-tasks
description: Use when the user wants to schedule a task that SHIP runs every day, week or month, such as a dependency update. It runs SHIP missions on a schedule. Create a scheduled task from a prompt or a template, change its schedule or prompt, or turn it off and on. Run it now, read what its past runs did and cost, and delete it. For example, the user says "every Monday, have SHIP update our dependencies" or "run a flaky test sweep each week". Also use it when the user asks what the last scheduled run did, or which scheduled tasks a project has.
---

# Run missions on a schedule

A scheduled task is a prompt with a cadence. At each run, SHIP files an issue with the prompt as its description, and a
normal mission starts on it. The board, the review, the tests and the proof of that mission are the same as for any
other mission.

This skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at
<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do
the setup too. If its `version` is older than `ship --version`, run `ship init --force`.

| Command | Token scope |
| --- | --- |
| `ship schedule list`, `ship schedule get`, `ship schedule runs`, `ship schedule templates` | `scheduled-tasks:read` |
| `ship schedule create`, `ship schedule update`, `ship schedule delete` | `scheduled-tasks:write` |
| `ship schedule run` | `missions:run` |

Changes also need the admin or owner role in the organization. Each run uses credits, like any mission.

## See the scheduled tasks

```bash
ship schedule list
ship schedule list --project prj_123
ship schedule get aut_123
ship schedule templates
```

`ship schedule list` shows each task with its cadence and its next run. With `--project`, it lists the tasks of one
project. `ship schedule get` also prints the prompt.
`ship schedule templates` shows prepared prompts, each with a suggested cadence.

## Create a scheduled task

```bash
ship schedule create --name deps --template dependency-upgrades
ship schedule create --name triage --file triage.md --every weekly --day monday --time 09:00 --timezone Europe/Amsterdam
ship schedule create --name report --file report.md --every monthly --day 1 --time 06:00 --timezone UTC
```

The schedule is `--every daily`, `weekly` or `monthly`, with `--time` and `--timezone`. A weekly task also needs `--day`
with a weekday. A monthly task needs `--day` with a day from 1 to 28. With `--template`, the task takes the prompt of the
template, and its suggested schedule unless you give one. With `--file` too, the prompt of the file replaces the prompt
of the template. Give `--project <id>`, or set `SHIP_PROJECT_ID`.

Write the prompt like a good issue:

- Write the acceptance criteria as checkboxes, because the QA agent tests against them.
- Say what an empty result is, for example "if no dependency has an update, change nothing".
- Do not ask the agent to change the CI configuration. Nobody watches a scheduled run, and SHIP blocks that change
  without a person.

While the mission of the last run is still open, SHIP skips the next run. Thus a weekly task cannot open a second pull
request that conflicts with the first.

## Change, stop or delete a scheduled task

```bash
ship schedule update aut_123 --file triage.md
ship schedule update aut_123 --every daily --time 07:30 --timezone UTC
ship schedule update aut_123 --disable
ship schedule update aut_123 --enable
ship schedule delete aut_123
```

Only the values that you give change. To change the schedule, give `--every`, `--time` and `--timezone` together, and
`--day` when the interval needs it. `--disable` stops the runs and keeps the task and its history. Delete a task only
when the user asks for it, because its run history goes with it.

## Run a task now, and read its runs

```bash
ship schedule run aut_123
ship schedule runs aut_123
ship schedule runs aut_123 --limit 20 --cursor eyJhIjoxfQ
``

Preview of the first 4,000 characters. Read full instructions →