For your agent
You were never going to read all this.
Fair enough. Copy a prompt, paste it into Claude Code, Cursor, Copilot or whatever is typing for you today, and it will wire Shipseal into your repo properly. The prompts below tell it where the real docs are and which mistakes to avoid, so it checks instead of guessing.
Humans are also allowed here. The quick start takes about four minutes.
Set it up
paste into any agent# Task
Add Shipseal to this repository so publishing a GitHub release automatically generates and
attaches social images.
# Context
Shipseal is an open source CLI and composite GitHub Action.
Docs: https://shipseal.dev Machine readable: https://shipseal.dev/llms.txt
Package: shipseal on npm, Node 22+, MIT. Renders with Takumi, no browser and no image model.
# Steps
1. Run `npx shipseal@latest init --yes` at the repository root. It detects the brand
(name, tagline, colours, logo, fonts) and writes .shipseal/brand.json and
.shipseal/config.json. Commit both.
2. Open .shipseal/brand.json and check the colours. Any colour it could not detect is
reported as a built-in default in the init output, so fix those by hand.
3. Add .github/workflows/shipseal.yml:
name: Shipseal
on:
release:
types: [published]
permissions:
contents: write
jobs:
visuals:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: akii09/shipseal@v0.0.6
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
4. Add .shipseal/output/ to .gitignore.
5. Verify locally with `npx shipseal@latest release --dry-run`, which prints the facts it
collected without rendering anything.
# Constraints
- fetch-depth: 0 is required. Without full history and tags the release facts are incomplete.
- Do not invent values in brand.json. If a colour is not found in the project, leave the
default in place and tell me which ones need my attention.
- Do not add an image generation dependency, and do not add a headless browser. Shipseal is
deterministic on purpose.
- Do not edit files under .shipseal/output. They are generated.
# Done when
- .shipseal/brand.json and .shipseal/config.json exist and are committed.
- The workflow file exists with fetch-depth: 0 and contents: write.
- `npx shipseal@latest release --dry-run` prints facts with no error.
- You have told me every colour that fell back to a built-in default.Something looks wrong
debugging# Task
A Shipseal card came out wrong. Diagnose it from evidence, not from guesses.
# Gather evidence first, change nothing yet
1. Run `npx shipseal@latest doctor`. It checks Node, git, a shallow clone, brand.json,
fonts, the logo and the renderer.
2. Run `npx shipseal@latest release --dry-run --json`. This prints every collected fact
with its provenance and renders nothing.
3. Read .shipseal/output/<tag>/manifest.json. Every file, fact, computed value, warning and
missing fact is listed there.
Read these before changing anything:
- A wrong number is a source problem, never a template problem. Find the fact in the
manifest and check its `ref`.
- A "fit-warning" means text was shrunk or truncated. Shorten the copy rather than widening
the template.
- A missing element is listed under `missing` with the fact that caused it.
- Wrong colours mean detection failed. The init output names every colour that fell back to
a built-in default.Facts an agent needs
The short version
- Package
- shipseal on npm, Node 22 or newer, MIT
- Action
- akii09/shipseal@v0.0.6, composite, needs fetch-depth: 0
- Commands
- init, release, milestone, bench, doctor
- Config
- .shipseal/brand.json and .shipseal/config.json
- Output
- .shipseal/output/<event-id>/ plus manifest.json
- Rendering
- Takumi. No headless browser, no image model
Machine readable: llms.txt, which agents that support it read instead of scraping this page. An MCP server is not available yet, so point your agent at these prompts for now.
If your repo has an AGENTS.md
Drop this in
## Release visuals
This repo uses Shipseal (https://shipseal.dev) to generate release images.
- Brand config lives in .shipseal/brand.json. Edit it rather than hard-coding colours.
- Never put a number on a card by hand. Numbers come from sources with provenance and
land in manifest.json.
- After changing a template or the brand, run `npx shipseal@latest release --dry-run`
and read the facts before rendering.
- .shipseal/output/ is generated. Do not commit it.