Tips for using sscc with AI.

The skill is a 12-step workflow with three editorial gates that fire beforeany composition is built. Without it, agents tend to jump from “the user wants screenshots” straight to sscc new, which produces bland, generic listings. With it, the agent enumerates visual ingredients panel-by-panel, gets your approval on the plan, then scaffolds.

The four sscc catalog commands (templates, bezels, presets, fonts) return the canonical ids the rest of the CLI accepts. Agents that skip this step hallucinate bezel names like “iphone-15-pro” (the real id is iphone-17-pro-deep-blue-portrait).

# In the agent's first scaffold pass:
sscc catalog bezels  --json > .sscc/bezels.json
sscc catalog presets --json > .sscc/presets.json
sscc catalog fonts   --json > .sscc/fonts.json

# Then have the agent grep these files for valid ids
# instead of inventing them.

Every mutating command takes --id <uuid>. Agents that don’t capture --emit-id output spend the next ten tool calls re-discovering UUIDs via sscc show. Persist them in a scaffold file:

# Map every (platform, panel) → composition UUID once,
# in a file the agent can re-read between turns.
declare -A IDS
for plat in mac iphone ipad; do
  for n in 01 02 03 04 05; do
    IDS[$plat-$n]=$(sscc composition add MyApp.screenshot \
      --platform $plat --title "$n" --emit-id)
  done
done

printf '%s\n' "${!IDS[@]}" "${IDS[@]}" \
  | jq -Rsn '[inputs] | _nwise(2) | { (.[0]): .[1] }' \
  | jq -s add > DraftTemplates/<slug>/ids.json

sscc validate proves the file is well-formed JSON. It does not prove the bundle will render correctly: a headline can fit the JSON schema and still clip past its frame, a background can be silently dropped, an asset can be referenced but missing.

The create-screenshot-file skill ships a verify.sh script that runs three classes of jq checks before you spend render time. Wire it into the agent’s loop:

# After every batch of mutations, BEFORE sscc export.
bash .cursor/skills/create-screenshot-file/references/verify.sh \
  DraftTemplates/<slug>

# Exit code is 0 when:
#  - every composition has its background image attached
#  - no headline's font-size × line-count × 1.2 exceeds its frame height
#  - no plan-side PNG is missing from the bundle
#
# Re-render only after this exits 0.

Agents that skip the visual audit ship listings with width-wrapped headlines, font fallbacks, and decorative assets in the wrong z-order. The agent should always:

1. rm -rf audit/ && sscc export --output audit/ (clean folder — stale PNGs lie).
2. Open at least one PNG per platform.
3. Count the lines in every rendered headline against the design plan. If the plan said 2 lines and the PNG shows 3, the frame is too narrow at the chosen font size — narrow the typography and re-render.
4. Confirm every decorative asset, every device bezel, and every wallpaper the plan called for is visibly present.

Every command supports --json and returns a stable envelope. Parse the envelope, never the human text. The agent should also surface data.warnings[] — a FONT_FALLBACK warning means the PNG shipped with the wrong typeface.

OUT=$(sscc layer add text MyApp.screenshot \
  --composition "$COMP" --content "Hello" \
  --frame 100,100,800,200 --emit-id --json)

if [ "$(jq -r '.ok' <<<"$OUT")" != "true" ]; then
  echo "Failed: $(jq -r '.error.message' <<<"$OUT")"
  exit 1
fi

LAYER_ID=$(jq -r '.data.id' <<<"$OUT")
jq -r '.warnings[]?.message' <<<"$OUT"

When the agent drafts a design plan, it should describe what it actually wants— not what’s easy to scaffold, not what the catalog already ships with. “Hand-drawn coral arrow pointing from headline to device screen, ~-10° rotation” is a valid plan ingredient. The realization step (image generation + adding a non-bezel image layer) handles it.

Constraint thinking belongs afterthe plan, not during it. The agent should never silently drop a planned ingredient because it “can’t do arrows” — it can.

The skill convention is to keep every in-progress listing under DraftTemplates/<slug>/ at the repo root, with this shape:

DraftTemplates/<slug>/
├── README.md                     # status + intent
├── design-plan.md                # the per-panel ingredient plan
├── refs/                         # reference screenshots (input)
├── assets/                       # generated backgrounds, decorations
├── captures/<platform>/          # placeholder captures, swapped later
├── scaffold.sh                   # idempotent rebuild from the plan
├── <ListingName>.screenshot/     # the saved bundle
└── audit/                        # freshly rendered PNGs

tmp/ is gitignored and used only by the template-author skill for downloaded App Store screenshots. Putting the design plan there means it disappears between sessions.

Every composition and layer has a stable UUID. Titles are display-only and can collide. Agents that match by title occasionally edit the wrong composition once two panels share an “Hero” title.

Re-rendering the whole listing for a one-panel fix is slow. --composition takes a UUID and is repeatable:

# Tightened the Mac hero headline. Re-render that panel only.
sscc layer set MyApp.screenshot --id "$MAC_HERO_HEADLINE" \
  --content "Your day,\non one screen."

sscc export MyApp.screenshot --output audit/ \
  --composition "$MAC_HERO_COMP" --opaque --overwrite