goose-graphics

## 1. Overview

`goose-graphics` is a portable visual skill pack for the Agent Skills ecosystem. Styles and formats live in the central Gooseworks library — fetched on demand via `npx gooseworks` instead of bundled into this repo. The skill pairs that catalog with an extract-style workflow for reference images, an Unsplash + ASCII art image-sourcing layer, and a Playwright-based HTML-to-PNG export pipeline.

It loads in any host that reads `SKILL.md` — Claude Code agents calling it for automated render, Goose pipelines wiring it into content generation, Cursor/Codex projects picking it up via `.cursor/rules/` or `~/.codex/skills/`. Each style ships a slim DESIGN.md spec via `npx gooseworks styles get <slug>`, which can also be uploaded directly into Claude Design as a design-system scaffold.

Format templates, image-sourcing helpers, and the screenshot pipeline live in this skill pack. Styles, formats, and example renders are fetched on demand from the central library — no slugs are baked in.

## 2. Invocation

This skill supports **three invocation modes** — all-args, partial-args, and interactive. Pick the fastest path for the ask.

### 2.1 Full-args invocation (fastest path)

```
/goose-graphics --style <slug> --format <format> [--brief "..."] [--ref <image-path>]
```

- `--style <slug>` — any community-published style slug. Discover with `npx gooseworks styles list` / `search`. Required for style-selected generation. Omit to let the user pick interactively.
- `--format <format>` — any community-published format slug (e.g., `carousel`, `story`, `infographic`, `slides`, `poster`, `chart`, `tweet`, plus any community additions). Discover with `npx gooseworks formats list`. Required for format-selected generation.
- `--brief "..."` — the topic / content description. Replaces the Content Discovery phase.
- `--ref <image-path>` — if present, extract an ad-hoc style from the reference image for this single render instead of using a preset. When `--ref` is provided, `--style` is ignored. **For creating a persistent published style that other agents can discover, use the dedicated `/goose-graphics-create-style` skill instead.**

**Three branches:**

1. **All required args present** (`--style` + `--format` + `--brief` OR `--ref` + `--format` + `--brief`) → skip discovery, skip style selection, proceed directly to §7 (Set Output Path) and §8 (Generate HTML).
2. **Partial args** → ask only for the missing pieces. If `--style` is set but `--format` is not, ask only for format. If `--brief` is missing, ask only for the topic/content.
3. **No args** → run the interactive flow from §3 onward.

### 2.2 Examples

```bash
# Full args — one-shot generate
/goose-graphics --style matt-gray --format carousel --brief "How founders find their first 100 customers in 2026"

# Reference-driven — extract a one-off style from an image and build with it
/goose-graphics --ref ~/Desktop/mood.png --format poster --brief "Summer studio open house, August 14"

# Partial — Claude asks for the missing brief
/goose-graphics --style deep-ocean --format slides

# No args — full interactive flow
/goose-graphics
```

To **create a persistent published style** (slim spec + hero render + a few additional examples, pushed to the central library so other agents can discover it), use the dedicated `/goose-graphics-create-style` skill instead.

### 2.3 Defaults when args are partial but unambiguous

- If `--brief` is missing but clearly inferable from subsequent user text, don't block — proceed.
- If `--format` is missing, default to asking (there is no safe default across formats).
- If `--style` is missing and `--ref` is missing, ask — style is load-bearing.

## 3. Discovering styles and formats

Styles and formats live in the central Gooseworks library, not in this skill pack. **Always list or search before assuming a slug exists** — the catalog is community-driven and changes over time.

```bash
# List or search styles
npx gooseworks styles list
npx gooseworks styles search "warm editorial"
npx gooseworks styles list --mood "Organic & Warm" --tag warm

# Fetch a specific style's DESIGN.md (the slim spec) — pipe into Claude Design,
# or include in the agent context for HTML generation
npx gooseworks styles get <slug>

# Same shape for formats
npx gooseworks formats list
npx gooseworks formats search "vertical"
npx gooseworks formats get <slug>
```

When the user names a style or format, run `list` / `search` first, then `get` the spec for the chosen slug. Never assume a slug exists from memory — slugs come and go as the community publishes and retires entries.

## 4. Publishing your style

When the user creates a new aesthetic via `extract-style.md` (or via the dedicated `/goose-graphics-create-style` skill) and is happy with it, publish it to the community library so other agents and users can discover it:

```bash
cd <directory-with-rendered-examples>
npx gooseworks styles publish
```

The CLI expects a `gooseworks-style.json` manifest in the working directory plus the referenced PNG files. See **§13 Manifest format** for the exact shape.

### 4.1 Description-writing guidelines (load-bearing)

The description is what makes the style discoverable by AI agents searching the catalog. Treat it as a search index, not flavor text.

- **50–200 words, keyword-dense.**
- **Lead with mood + use case.** "Bold magazine-cover energy for product launches and event posters."
- **Mention typography signals.** "Massive condensed sans-serif headlines paired with a delicate body serif."
- **Mention palette signals.** "Rust orange + cream + near-black."
- **Mention industry / audience fit if relevant.** "DTC beauty, indie publishing, event flyers."
- **Avoid generic adjectives alone.** "Beautiful," "modern," "clean" mean nothing without concrete signals — pair them with palette, typography, or industry context.

### 4.2 Tag-writing guidelines

- **3–10 lowercase tags.**
- Cover: **mood** (warm, dark, energetic), **density** (sparse, dense), **fo