Skip to main content
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

Copy this into your coding agent
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

1

Copy the prompt

Click the copy button on the prompt above to copy the full schema cheat sheet to your clipboard.
2

Paste into your session

Paste at the start of a new conversation in Claude, ChatGPT, Cursor, or your preferred coding agent tool.
3

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.”
4

Place the output

Save the YAML to .shipfox/workflows/<name>.yml in your repo and commit it.

​
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
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.

​
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: 
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.