Create Goose Graphics Format

Authors a new graphics format and publishes it to the central Gooseworks library via npx gooseworks formats publish. The output is a working directory with a gooseworks-format.json manifest plus at least one rendered example PNG paired with an existing style.

When to use this skill

Use when the user wants a new named format with its own content rules — a story cover, a podcast cover, a square testimonial — that maps to one of the seven built-in canvas sizes (carousel, infographic, slides, poster, story, chart, tweet). The new format defines new rules and a new slug; it inherits dimensions from one of those canvases.

Custom canvas dimensions are not supported. If the user wants a canvas size that isn't in the seven built-ins (e.g. LinkedIn banner 1584×396, US Letter 2550×3300), tell them honestly — that requires a code change to the goose-graphics skill pack's FORMAT_CONFIGS and is out of scope for this skill. Suggest the closest existing canvas instead.

Always check first: run npx gooseworks formats list (or formats search "banner" etc.) to see whether a community-published format already covers the use case. If one fits, just use it via the regular goose-graphics flow.

Prerequisites

• The goose-graphics skill must be installed in the same workspace — this skill uses goose-graphics/screenshot/screenshot.js to render examples and pulls style specs via npx gooseworks styles get <slug>. Install via:

  npx gooseworks install --claude --with goose-graphics

  (Swap --claude for --cursor or --codex as needed.) See the install page on the hub for the canonical command: https://skills.gooseworks.ai/skills/goose-graphics
• The screenshot tool's dependencies must be installed (goose-graphics/screenshot/node_modules/ must exist). If not:

  cd <path-to>/goose-graphics/screenshot && npm install && npx playwright install chromium

• The user must be signed in to gooseworks (npx gooseworks login) for publish to authenticate.

Inputs

• A brief describing the canvas: dimensions, intended use (platform / surface), and content density rules.
• Optional: a reference image showing the desired layout.

Outputs (in a working directory)

<working-dir>/
  gooseworks-format.json    # manifest (see "Manifest format" below)
  example-1.png             # at least one rendered example (REQUIRED)
  example-2.png             # optional; recommend 2–3 examples across styles
  example-3.png

The backend rejects publish with an empty examples array — at least one rendered example is mandatory.

Workflow

Step 1 — Pick a canvas (from the fixed allow-list) and confirm intent

A new format is a new slug + new content rules over one of the seven built-in canvas sizes — not a new canvas. Custom dimensions are not supported: every renderer in the system (CLI screenshot tool, hub, other agents) is locked to this allow-list, and creating a format with custom width/height would produce something nobody can render.

Pick the canvas the new format should use:

Then ask the user:

• Which canvas best fits the use case? (Pick from the table above.)
• What is this format for? (Surface, platform, audience.)
• What is the maximum content density? (Title length, body length, item counts, whether it's single-panel or multi-panel.)

The new format inherits the canvas's width/height exactly. Set the manifest's width/height fields to the canvas's dimensions verbatim (e.g. 1080/1350 for a poster-canvas format). Do not invent new dimensions — the publish step will reject anything that doesn't match one of the seven canvases.

If the user wants a canvas that isn't in the list (e.g. LinkedIn banner 1584×396), tell them honestly: that's a code change to the goose-graphics skill pack's FORMAT_CONFIGS and is out of scope for this skill. Suggest the closest existing canvas instead.

Step 2 — Pick a name and slug

Suggest 2–3 descriptive names that lead with the platform / surface (e.g., linkedin-banner, story-cover, podcast-cover, event-flyer-letter). Slug must be lowercase-kebab-case ([a-z0-9-]+).

Collision check: run npx gooseworks formats get <slug> — if the catalog returns a hit, the slug is taken. Suggest an alternative.

(The user may omit slug from the manifest; the backend auto-generates one. On 409 the CLI prompts you to accept the server's suggested slug; pass --yes at publish time to auto-accept.)

Step 3 — Draft contentRulesMd

This is the load-bearing field — it teaches future agents how to fill the canvas. Cover, in this order:

• When to use this format vs the alternatives. One or two sentences.
• Maximum content density. Exact limits: title word count, body word count, number of items / panels / slides, whether images are required or optional.
• Per-section content rules. Header, body, CTA, footer — what goes where, what shape, what size. If the format is single-panel, list the elements (title, hero, byline, etc.) and their max sizes.
• Typography signals. Recommended display font sizes and hierarchy at this canvas size (e.g., "Display hero ~140–180px on a 1584×396 banner").
• Spacing and rhythm. Padding, margins, vertical rhythm.

Aim for at least 50 chars (the minimum) but 300–800 chars is the sweet spot. Treat contentRulesMd as the spec a fresh agent would read to render this format correctly without further guidance.

Step 4 — Render at least one example

Pair the new format with an existing published style. Recommended: render 2–3 examples across different styles so the catalog tile demonstrates the format's flexibility.

For each example:

1. Pick a style: npx gooseworks styles list | head and choose 2–3 with contrasting moods (e.g., matt-gray, neon-dashboard, brutalist).
2. Fetch its slim spec: npx gooseworks styles get <slug>.
3. Generate HTML at the exact target dimensions, using the chosen style's palette, fonts, and signature visual moves. The HTML rules from the goose-graphics rendering pipeline apply:
   • Self-contained single HTML file with inline <style> block + Google Fonts <link>.
   • Fixed pixel sizes only — no vw/vh/%/rem/em/clamp().
   • Outer dimensions match exactly: html, body { width: <W>px; height: <H>px; overflow: hidden; }.
4. Render via the screenshot tool from the goose-graphics skill pack, passing the canvas slug (carousel/infographic/slides/poster/story/ chart/tweet — the one chosen in Step 1), not the new format's slug:

   node <path-to>/goose-graphics/screenshot/screenshot.js \
     --format <canvas-slug> \
     --input <path-to-html> \
     --output <working-dir>/example-N.png \
     --font-delay 1500

   This works out of the box — the new format inherits the canvas's dimensions, so no code changes are needed anywhere.

Step 5 — Write gooseworks-format.json

Match the shape documented in goose-graphics/SKILL.md §17.2. Required:

{
  "name": "Story Cover",
  "slug": "story-cover",
  "description": "1080×1920 vertical cover slide for Instagram and TikTok stories. Single hero panel, 5-word title max, optional brand mark in the lower 10%. Use for product launches and event reminders where the viewer scrolls past in 2 seconds.",
  "width": 1080,
  "height": 1920,
  "contentRulesMd": "## Rules\n\n- Title: 5 words max, large display, centered or top-left\n- One hero element (image, stat, or large icon) in the upper 70% of the canvas\n- Optional brand mark in the lower 10%, ≤8% of canvas height\n…",
  "tags": ["story", "vertical", "social", "instagram", "tiktok"],
  "examples": [
    { "file": "./example-1.png", "styleSlug": "matt-gray", "caption": "Paired with matt-gray" },
    { "file": "./example-2.png", "styleSlug": "neon-dashboard" }
  ]
}

Constraints to respect:

• name: 1–120 chars
• description: 20–1000 chars (required). See guidelines below.
• width / height: must match one of the seven built-in canvases exactly (1080×1080, 1080×1350, 1920×1080, 1080×1920, or 1080×variable for infographic). Custom dimensions will render fine locally if you stretch the rules but will fail for any other agent that pulls the format later, since their screenshot.js only accepts the built-in canvas slugs.
• contentRulesMd: minimum 50 chars (required)
• tags: 3–10 lowercase strings. See guidelines below.
• examples: minimum 1 (required); styleSlug is optional but recommended.

Step 6 — Publish

cd <working-dir>
npx gooseworks formats publish

The CLI reads gooseworks-format.json, validates it client-side, uploads the manifest plus the example PNGs, and registers the format in the catalog.

Slug-collision UX: if the slug is taken, the CLI prompts Slug 'X' is taken. Use 'Y' instead? with the server's suggestion. Pass --yes to auto-accept (useful for scripted runs):

npx gooseworks formats publish --yes

Success output:

Published format: <slug>
https://skills.gooseworks.ai/formats/<slug>

Exit codes: 0 success, 1 transient/auth (network, 401, 5xx), 2 user error (400 validation, 403 not owner, 413 file too large, declined 409).

Amending a published format later:

npx gooseworks formats update <slug>

Same manifest format; no slug-collision retry (the slug is locked).

Step 7 — Confirm

Tell the user:

• The published slug and the URL where the format lives in the catalog.
• The dimensions and the styles used for the examples.
• How any agent can now use it:

  /goose-graphics --style <any-slug> --format <new-slug> --brief "..."

Description-writing guidelines

Same shape as styles — 50–200 words, keyword-dense — but lead with canvas and content density instead of mood.

• Lead with canvas + surface: "1080×1080 square testimonial card for X feed posts."
• Mention single-panel vs multi-panel and approximate text limits.
• Mention intended platform / surface (Instagram Stories, LinkedIn, print event flyer, etc.).
• Mention audience and use case ("Use for product launches and event reminders where the viewer scrolls past in 2 seconds.").
• Avoid generic adjectives. Be concrete: pixel counts, word counts, surfaces.

Example:

"1080×1920 vertical canvas for Instagram and TikTok stories. Single-panel composition, 5-word title max, large hero image or stat, optional brand mark in the lower 10% of the canvas. Use for quick announcements and engagement posts where the viewer scrolls past in 2 seconds."

Tag-writing guidelines

3–10 lowercase tags. Common format tags:

• Aspect: vertical, square, portrait, landscape, banner, panoramic
• Structure: single-panel, multi-slide, multi-panel
• Surface: story, feed, cover, flyer, presentation, print
• Use: social, ad, editorial, event
• Platform fit: linkedin, instagram, tiktok, youtube, twitter

Skip tags that just restate the slug.

Anti-patterns to avoid

• Don't ship without rendered examples. The backend rejects empty examples. Render at least one — recommend 2–3 across contrasting styles.
• Don't bake style decisions into contentRulesMd. The format describes canvas + content density; the style describes palette + typography. Keep them separate so any style can pair with any format.
• Don't skip the dimensions sanity-check. A typo here is permanent — every agent rendering against the format will produce off-size output.
• Don't reference local files in this skill pack in the published manifest. All paths in examples[].file are relative to the working directory and live on the user's machine, not in this repo.
• Don't publish without checking npx gooseworks formats list first — if the format already exists, point the user at it instead of publishing a duplicate.