Zebrafish

Setup (MUST, before any production work)#

1. Run node scripts/context.mjs --json --auto-update (path relative to this skill directory). Read the result: project root, .zebrafish/config.json settings, context docs, installed skill versions, and auto-update status. If autoUpdate.updated is true, restart this setup once so the refreshed instructions are active. If auto-update is skipped for local edits or an error, continue only after noting the recommendation. Set ZEBRAFISH_SKILLS_AUTO_UPDATE=0 before running the setup to disable the automatic update check for a session.

2. Load product/brand context before writing prompts, scripts, claims, or visual direction: get_campaign_knowledge for the campaign when one exists, plus PRODUCT.md / CAMPAIGN.md when present.

3. If there is no campaign, no product doc, and no brief with product facts: STOP and ask for product context. Do not invent product facts to proceed.

4. Read references/tool-belt.md before first use of Zebrafish MCP/API/Studio/workflow tools in a session. Hosted: https://zebrafish.dev/skills/zebrafish/references/tool-belt.md.

Route (pick exactly one)#

Announce the route in one line before executing. If no focused skill fits, continue here with the shared references and the same gates below.

Gates (apply in every route, including this router)#

• Spend gate. Before any purchase_credits, create_studio_generation, run_workflow, or test_run_draft that costs money: state model/workflow or credit top-up, unit count or credit amount, estimated cost from list_models pricing or the purchase request, then get explicit user approval. For purchase_credits, state the credit amount, USD amount, rail, and idempotency key; use it only when the user asks/approves a top-up or an approved task is blocked on credits. Never rotate the idempotencyKey for a retry. One approval can cover a stated batch; it does not cover scope growth (more variants, higher resolution, new asset types, or a larger top-up) — re-ask.

• Claim gate. Every product, compliance, or brand claim traces to a supplied source or carries the literal [unverified] label. Never invent product claims, marketplace compliance facts, customer quotes, metrics, or brand rules.

• Identity gate. No real-person likeness, voice, or persona work without explicit consent, retention, and deletion rules. STOP and ask.

• Publish gate. publish_workflow_revision and answering respond_run_approval happen only after an explicit user decision.

Operating Loop#

1. Intake brief, goal, audience, platform, aspect ratio, duration, brand and product references, constraints, and approval needs. Restate them; get confirmation before spending.

2. Plan route, production workflow, outputs, and required tools.

3. Prepare references: upload or fetch assets, extract campaign knowledge, record source URLs and asset IDs.

4. Produce with Studio generation or workflow tools through the spend gate. Poll every generation and run to a terminal state.

5. Track status, costs, run IDs, generation IDs, prompts, references, and output URLs as you go — these become the Provenance section.

6. Verify against references/verification.md gates. Inspect actual media, not just metadata.

7. Deliver using the delivery template. This step is mandatory and checked.

Delivery (MUST)#

• Write the delivery document in the exact format of references/delivery.md (hosted: https://zebrafish.dev/skills/zebrafish/references/delivery.md), starting with a # Delivery: title line.

• Run node scripts/verify.mjs --strict <delivery file> on it. A non-zero exit means the gate failed: fix findings or move them to ## Unverified with a reason, then re-run until it exits clean. Do not present results while fixable findings remain.

• Final answer shape: output URLs first, then provenance summary, verification summary, unverified gaps, and next action only when useful.

References#

• references/tool-belt.md — Zebrafish tool usage. Read before tool work.

• references/verification.md — verification gates per output type. Read before the verify step of any production.

• references/delivery.md — the required delivery document format.

• Inside this repo only: docs/media-planning.md, docs/zebrafish-skills.md, and shared/media-planning for product taxonomy and boundaries.

Scripts#

Installed copies of this skill ship deterministic helpers under scripts/ (paths relative to this skill directory):

• scripts/context.mjs --json — project/campaign context and config. Part of mandatory setup.

• scripts/verify.mjs <files...> — deterministic checks: delivery-document structure, unverified claims, provider names leaking into copy, missing provenance, leftover TODO/UNVERIFIED markers. Part of mandatory delivery.

• scripts/hook.mjs — backs the optional post-edit hooks installed by npx zebrafish-skills install; surfaces the same verify findings after file edits and never blocks a turn.

Policy#

• Use Zebrafish/FAL production paths for integrated generation today.

• Treat Higgsfield, RunComfy, HyperFrames, Remotion, GPT Image 2, Nano Banana, and Seedance-style workflows as provider candidates unless the runtime already exposes them through approved Zebrafish tools.

• Provider and model names live in provenance, never in user-facing copy.

• Never hide provider/model choice from provenance.

• Prefer repeatable workflows for reusable multi-step work; prefer one-off Studio generations for exploratory or single-asset work.