> ## Documentation Index
> Fetch the complete documentation index at: https://www.shipfox.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Shipfox Workflow Authoring Prompt for Coding Agents

> Copy and paste this compact Shipfox workflow schema cheat sheet into Claude, ChatGPT, Cursor, or any coding agent to get valid workflow YAML every time.

No matter which coding agent you use, you can get valid Shipfox workflow YAML by pasting this prompt into your session. It contains the complete shipped schema, the hard validation rules, the today/roadmap boundary, and two correct examples — the same content as the skills package, in a single paste.

## The prompt

```text Copy this into your coding agent theme={null}
You are writing a Shipfox workflow (YAML under .shipfox/workflows/). A trigger
starts a run; a run is a DAG of jobs; each job runs steps on a runner. Output only
valid YAML.

Top level: name (required), runner (label or list), env (run-step only), triggers,
jobs (required). Unknown keys are rejected.

Trigger { source, event, filter?, with? }. For integrations, source is the
CONNECTION SLUG (e.g. github_<org>, sentry_<org>, or your webhook slug), not the
bare provider name; for on-demand runs it is literally "manual". Shipped events:
manual/fire, github push (+ other GitHub events), sentry issue.(created|resolved|
assigned|archived|unresolved), custom-webhook/received. At most one manual
trigger.

Job { steps (>=1), needs?, runner?, env? }. Jobs run in parallel; each is isolated
and re-clones the repo (install deps per job).

Step is a run step { run, key?, name?, env?, gate? } OR an agent step
{ model, prompt, thinking?, provider?, key?, name?, gate? } — never both; agent
requires prompt; env is run-only. key identifies a step; name is display-only.

gate (run or agent steps) { success_if: "<CEL over exit_code>", on_failure: {
restart_from: "<earlier step's key — NOT its name>", output?: "<message>" } }.
Restarts are capped (3 attempts per gating step) before the job fails.

${{ }} interpolation IS supported in run/env/prompt, resolved at run creation from
run/trigger/event/inputs context (e.g. ${{ trigger.source }}). Do NOT use (not
shipped): loop, matrix, branch, structured output, reusable agents. filter isn't
evaluated yet. event.ref on a push is the full Git ref (e.g. "refs/heads/main").
```

## How to use it

<Steps>
  <Step title="Copy the prompt">
    Click the copy button on the prompt above to copy the full schema cheat sheet to your clipboard.
  </Step>

  <Step title="Paste into your session">
    Paste at the start of a new conversation in Claude, ChatGPT, Cursor, or your preferred coding agent tool.
  </Step>

  <Step title="Ask for your workflow">
    Describe what you want — for example: "Add a Shipfox workflow that runs my tests on every GitHub push and then asks Claude to review the results."
  </Step>

  <Step title="Place the output">
    Save the YAML to `.shipfox/workflows/<name>.yml` in your repo and commit it.
  </Step>
</Steps>

## What the prompt covers

The prompt is deliberately compact but complete. It covers every dimension of the shipped schema:

* **Top-level schema fields** — `name`, `runner`, `env`, `triggers`, `jobs`, and which keys are rejected
* **Trigger sources (shipped today)** — `manual`, plus integration connection slugs for GitHub (`push`), Sentry (`issue.*`), and custom webhooks (`received`)
* **Job isolation and `needs` ordering** — parallel execution, repo re-cloning, and dependency chaining
* **Step kinds: run vs. agent** — the two mutually exclusive step shapes and their allowed fields
* **Gate / restart\_from rules** — CEL expressions over `exit_code` and how to wire restart targets
* **Hard rules** — no `loop`/`matrix`/`branch`, `env` is run-only, at most one manual trigger
* **The today/roadmap boundary** — an explicit list of features not to use, so the agent doesn't hallucinate roadmap keys

<Tip>
  For ongoing workflow authoring, install the skills package (`npx skills add shipfox/agent-skills`) so your agent always has the latest schema — no pasting required. See [Skills Package](/ai/skills-package).
</Tip>

## Example exchange

Here is a sample user prompt and the YAML a well-prompted agent should produce.

**User prompt:** "Add a Shipfox workflow that runs npm test on every push and has an agent step summarize failures."

**Expected output:**

```yaml theme={null}
name: Test and triage
runner: ubuntu-latest
triggers:
  on_push:
    source: github_acme    # your GitHub connection slug
    event: push
jobs:
  test:
    steps:
      - run: npm ci
      - run: npm test
  triage:
    needs: test
    steps:
      - model: claude-opus-4-8
        thinking: high
        prompt: If the tests failed, summarize the failure and suggest a fix.
```