commission-video-format-skill

Use when you want to commission new ad-format molecule skills in bulk from a public video-ad taxonomy (or any source where each "format" has a definition + a handful of example videos). Different from create-video-implementation-workflow because the output is a Linear ticket, not a workflow plan or a rendered video.

Purpose

Turn a batch of (format_name, definition, example_videos[]) tuples into Linear tickets that commission new molecule skills in skills/molecules/<target_category>/. Each ticket is self-contained — a fresh Claude Code agent reading just the ticket can start work without pinging anyone for context.

The workflow we're codifying:

Watch every example video via /watch:watch and synthesize per-format DNA
Scout 5–7 publicly accessible external reference videos per format from YouTube, Meta Ad Library, iSpot, brand FB video archives
Fill a hard-schema ticket template per format (Summary / Format DNA / Local refs / External refs / Skill to create / Composed atoms / Inputs / Workflow with 2 human gates / Decision rules / Quality checks / Failure modes / Validation criteria / Estimated work / Open questions / Notes for the implementing agent)
One human gate: user reviews ticket drafts before Linear push
Push to Linear via mcp__linear-server__save_issue, or fall back to markdown files in output_dir

Inputs

Required:

formats[] — list of {name, definition_source, example_videos[]}
- name (string) — e.g. "Product Specs", "Vignette". Used in ticket title + skill folder slug.
- definition_source (one of):
  - {kind: "url", value: "https://..."} — WebFetch'd at runtime
  - {kind: "text", value: "..."} — used verbatim
- example_videos[] — list of absolute local paths (mp4/mov/webm). 2–4 per format is the sweet spot; 1 leaves the DNA underspecified, 5+ adds analysis cost without much new signal.
linear_project — name OR ID OR slug (e.g. "Goose Ads - Sprint 2")
linear_team — name OR ID (e.g. "Gooseworks")
linear_assignee — name / email / displayName (e.g. "hbamoria")

Optional (with autonomous defaults):

linear_state — "Backlog" (default) | any team state name
output_dir — default 0xhbam/plans/linear-tickets-<batch-slug>/
external_ref_count — default 6 (range 5–7)
skill_target_category — default "ad-format" — where the commissioned molecules should live under skills/molecules/<category>/
batch_slug — default = ISO date + first-format-name slug
ticket_title_prefix — default "[<linear_project>] Build " followed by backtick-quoted skill name
taxonomy_source — short string to credit in tickets (e.g. "Common Thread Co"). Default: extracted from first definition_source URL if URL, else blank.

Prerequisites:

/watch:watch skill installed and ~/.config/watch/.env has a Whisper API key (Groq preferred, OpenAI fallback)
linear-server MCP available in the session, OR user accepts markdown-only output
All example_videos[] paths exist and are readable (skill auto-handles TCC by copying to .tmp/ first if direct access fails)

Composed Atoms

This molecule is unusual in that most of its work is orchestrating subagents and direct MCP calls, not chaining other atoms in skills/atoms/. The composed pieces:

/watch:watch (skill, not atom) — invoked by every analysis subagent to transcribe + extract frames from each example video. Whisper-key dependency lives here.
atoms/review/watch — equivalent atom-form of /watch:watch; subagents may use either depending on availability.
atoms/source/source-brand-assets — analogous "scrape brand assets from public web" pattern; references subagent reuses its WebFetch + Wikimedia + curl conventions.
atoms/planning/create-storyboard-html — reference for how to structure the per-format storyboard artifacts cited inside drafted tickets.
atoms/planning/create-video-implementation-workflow — sibling planning atom; produces a workflow plan rather than a Linear ticket. Cross-reference when synthesizing the commissioned-skill Workflow section.
mcp__linear-server__save_issue — Linear MCP call (not an atom under skills/atoms/, but a tool composed by this molecule).
mcp__linear-server__get_project, list_users, list_issue_statuses — Linear MCP preflight calls used in Phase 0.

Plus parallel Agent subagents (general-purpose) for analysis + references scouting, and WebFetch for taxonomy URLs.

Do NOT use: Klap, Whisper directly (use /watch:watch), Seedance, Veo, Soul ID, any video-generation atoms. This skill produces plans, not videos.

Workflow

1 human gate only (front-loaded). See sub-phases below.

Phase 0 — Preflight + input validation

Agent does all of this without asking the user:

Validate every formats[i].example_videos[j] path exists. If a path is in ~/Downloads and ls returns "Operation not permitted" (macOS TCC), cp each file to .tmp/format-research-<batch-slug>/videos/ (direct cp works even when ls is denied) and rewrite paths to the working copies.
Run python3 ~/.claude/plugins/cache/claude-video/watch/*/scripts/setup.py --check. On non-zero exit, surface to user with the install command — do not proceed.
Call mcp__linear-server__get_project with linear_project. If MCP missing or project not found, surface to user with "fall back to markdown only?" prompt. If user accepts, set linear_mode = "markdown".
Call mcp__linear-server__list_users + list_issue_statuses to resolve assignee user ID + state state ID. If either fails, surface and abort.
Compute batch_slug if not provided.
Create <output_dir>/ and .tmp/format-research-<batch-slug>/.

Phase 1 — Parallel format analysis + reference scouting

Fire all subagents in a single message (parallel):

N analysis subagents (1 per format) — each:

Receives: format name, definition snippet, list of working-copy video paths
Invokes /watch:watch <path> for each video; reads every returned frame
Writes analysis-<format-slug>.md following the schema in references/format-dna-analysis-template.md — per-video table, format DNA (shared rules), variants (divergences), production tier, asset inventory, autonomous-sourcing plan
Returns a <300-word summary to the parent

1 references subagent:

Receives: list of format names + 1-line definitions + brand examples from videos
Sources 5–7 publicly accessible video links per format using WebSearch + Meta Ad Library URLs + YouTube + iSpot + brand FB archives
Writes external-references.md per references/external-reference-sourcing-guide.md
Returns a <200-word summary to the parent

1 definitions subagent (only if any definition_source.kind == "url"):

WebFetches each unique URL
Writes definitions.md mapping each format name → extracted definition + structural guidance + quoted phrases
Returns a <300-word summary

Concurrency cap: Max 4 parallel subagents. If N(formats) + 2 > 4, batch the analysis subagents.

Output: All artifacts land in .tmp/format-research-<batch-slug>/. If a subagent reports it couldn't write the file (rare TCC issue we hit on 2026-05-27), the parent writes the file from the subagent's returned summary.

Phase 2 — Draft tickets

For each format, the parent agent:

Reads analysis-<format-slug>.md, definitions.md (if present), and the per-format slice of external-references.md
Fills the hard-schema template at references/ticket-template.md. Every section listed there must be present and non-empty. Substitute the slug commissioned_skill_slug = create-<format-slug>-ad.
Writes <output_dir>/<NN>-<format-slug>.md (NN zero-padded by format order)

🚦 HUMAN GATE — Ticket draft review

Show user:

List of <NN>-<format-slug>.md files with absolute paths
One-line summary per ticket: format name + commissioned skill name + ticket length
Linear push target: project + team + assignee + state
Confirmation prompt: "Push N tickets to Linear?" with options [push all] | [push selected: 1,3] | [edit drafts first] | [markdown only, skip Linear]

User approves → Phase 3 push. User edits → re-read updated files, re-render the summary, re-prompt. User cancels → exit cleanly, preserve drafts.

Phase 3 — Push to Linear (or markdown-only fallback)

If linear_mode == "linear":

For each ticket, call mcp__linear-server__save_issue in parallel:
- title = H1 of the markdown file (without leading # )
- description = full markdown content
- team, project, assignee, state from inputs
Capture each returned issue URL.
Write <output_dir>/README.md indexing the drafts + final Linear URLs.

If linear_mode == "markdown":

Markdown files already exist in <output_dir>/. Write a README.md with the one-line summaries + a note explaining the Linear MCP was unavailable + steps to create the tickets manually.

Phase 4 — Report

Reply to user with:

Total tickets created (and N URLs) OR markdown-only output path
Total cost (Whisper minutes ÷ Groq rate, ~$0.01-0.05/min)
Wallclock (typical: 7–15 min for 4 formats)
Anything that needed surfacing (subagent retries, low ref counts, format flagged as ambiguous)

Decision Rules

One gate, not two. The format analyses + references are intermediate artifacts; the ticket draft IS the reviewable output. Adding a 2nd gate (analyses-only review) slows the loop without improving quality — confirmed on 2026-05-27 batch.
Hard schema enforced on ticket template. Every section listed in references/ticket-template.md must be present and non-empty. Validate before showing the user.
Parallel subagents capped at 4. Per Higgsfield concurrency learnings and to keep parent context manageable. Batch when N(formats)+2 > 4.
Subagents write files directly when possible; parent picks up the slack if write fails. On 2026-05-27 the Vignette subagent's Write was rejected for unknown reasons; parent reconstructed from returned summary. Build for this.
Always copy videos out of ~/Downloads to .tmp/. macOS TCC blocks ls on that directory but cp works. Subagents can't reliably access user-Downloads paths; working copies in .tmp/ are universal.
External references are URL-verified for shape (HTTP resolves, not 404), NOT visually verified. YouTube's HTML is JS-rendered and WebFetch returns nav chrome only. Disclaim this in every ticket's references section.
Markdown fallback is silent — not a failure. If Linear MCP is missing, write the drafts and tell the user. Don't insist on the MCP being present.
Estimate spend upfront. Whisper transcription dominates cost. Compute sum(video_duration_minutes) × $0.05 and surface in the Gate prompt.
Format slugs are derived deterministically from name: lowercase, ASCII, hyphenated, no special chars. "Product Specs" → product-specs, commissioned skill name = create-product-specs-ad.
Definitions: prefer text > URL. If definition_source.kind == "text", skip the WebFetch step for that format. URL is fine but adds time + 1 subagent slot.
Don't pad weak external reference sets. If only 3 strong refs surface for a format, ship 3 with a caveat note rather than 7 with weak links. Validated on Vignette format 2026-05-27.

Output

<output_dir>/
  README.md                           # Index + Linear URLs OR manual-paste guide
  01-<format-slug>.md                 # Ticket 1
  02-<format-slug>.md
  ...
  NN-<format-slug>.md

.tmp/format-research-<batch-slug>/
  videos/                             # TCC-safe working copies of example mp4s
    <format>_NN_<brand>.mp4
  analysis-<format-slug>.md           # Per-format DNA, from parallel subagents
  definitions.md                      # If any URL-sourced definitions
  external-references.md              # 5-7 publicly accessible links per format

Quality Checks

(Verify all of these before declaring done.)

Every formats[i] produced an analysis file ≥100 lines
Every analysis covers: per-video table, format DNA (shared rules), variants, production tier, asset inventory, autonomous-sourcing plan
Every format has 5–7 external reference links (or <5 with a documented caveat)
Every ticket has all schema sections present and non-empty
Every local mp4 path in tickets is the working copy in .tmp/format-research-<batch>/ AND the original ~/Downloads/... path as alternate
Every ticket lists 2 human gates inside the commissioned skill workflow (not to be confused with this skill's 1 gate)
Linear URLs returned successfully (linear mode) OR README.md has paste-guide (markdown mode)
Total spend reported to user
No subagent silently failed (check via TaskList / completion notifications)

Failure Modes

Failure	Cause	Recovery
User's video paths in `~/Downloads`, `ls` returns "Operation not permitted"	macOS TCC blocks Downloads access for the Claude process	`cp` each file by exact path (works even when `ls` doesn't) to `.tmp/format-research-<batch>/videos/`; rewrite all path refs to working copies
/watch:watch missing API key	Whisper key not in `~/.config/watch/.env`	Surface to user with the setup command; do not generate analyses without transcription
Linear MCP not connected in this session	`.mcp.json` not loaded or trust dialog not accepted	Surface; offer markdown-only fallback; do not block on this
Subagent `Write` tool rejected for analysis file	Unclear (observed on 2026-05-27 Vignette agent)	Parent reads subagent's returned text result and writes the file itself
Subagent times out on one video (>15 min)	Whisper API stall or very long video	Continue other subagents; surface this format as "analysis incomplete, ticket draft used what was available"
External-references agent finds <3 strong links for a format	Format is hard to keyword-search (e.g. "Vignette")	Ship the ticket with what was found + a flagged caveat in the references section; do not pad
Linear `save_issue` returns 4xx	Project / team / assignee / state name mismatch	Re-resolve via `list_*` MCPs; if still failing, write markdown and surface
Subagent claims it wrote a file but file doesn't exist on disk	TCC, permissions, or path mismatch	Parent re-checks every claimed file in Quality Checks step; recovers missing files from subagent summaries
User edits a ticket between gate-shown and push	Markdown re-edited in place	Re-read the file at push time; do not cache the pre-edit content

Open Questions (validate on N=2+ runs before promoting to Decision Rules)

Optimal external_ref_count? 6 worked on the 2026-05-27 batch. For very well-documented formats (Specs), 7 was easy. For obscure formats (Vignette), 5 was a stretch. Adaptive default?
Should the skill auto-update the parent project's CLAUDE.md (e.g. add a routing table entry) for each new commissioned format? Probably yes, but the implementing agent in the commissioned skill ticket can do it.
Should the analysis subagent also extract a "minimal viable brand input" structured object (logo URL needed Y/N, product image Y/N, music brief Y/N) so downstream tooling can validate brand inputs before invoking the commissioned skill? Likely yes for v2.
Concurrent subagent batching strategy — fire N at once vs N-1 + 1 references agent vs ceiling(N/4) batches. Tested only the all-at-once pattern (4 + 1 = 5, exceeded the cap but ran fine in practice).
Definitions URL caching — multiple formats from the same taxonomy URL means N WebFetch calls for the same page. Should cache and split. Not critical for small batches.

Spend Reference (validated 2026-05-27, batch of 4 formats from CTC)

Item	Count	Per-unit	Subtotal
Whisper (Groq) — 12 videos, ~3 min total	1 batch	~$0.05/min	~$0.15
Parallel subagent LLM time (4 analysis + 1 refs + 1 def)	6 subagents	~$0.15-0.30	~$1.20
Parent agent draft synthesis (4 tickets)	—	included	—
Linear MCP calls	4	$0	$0
Total			~$1.40

Wallclock: ~12 min from input to Linear URLs (including ~5 min subagent parallel work and one human-gate pause).

Skill Location & Related

This molecule: skills/molecules/planning/commission-video-format-skill/

Related:

skills/atoms/planning/create-video-implementation-workflow — produces a workflow plan, not a Linear ticket
skills/molecules/brand-research/research-new-brand — same "scout + synthesize + output" shape, different output type (brand brief, not ticket)
0xhbam/plans/linear-tickets-video-formats/ — the worked example from 2026-05-27 (4 tickets: GOOSE-1783 through 1786). Use as the reference for what good output looks like.

Related memory rules to read before invoking:

feedback_use_skill_library.md — scan atoms/ before writing custom code
feedback_higgsfield_concurrent_limits.md — concurrency cap rationale (not 1:1 applicable but same spirit)
feedback_media_pipeline_gates.md — the multi-gate philosophy this skill deviates from (1 gate not 3)

Notes for the Implementing Agent

The hard schema in references/ticket-template.md is the contract. Every ticket output by this skill must match it. If you find yourself wanting to vary the structure, update the template once and let all tickets inherit — don't fork per-format.
Subagent prompts must include the analysis schema verbatim. Hand them references/format-dna-analysis-template.md as part of the prompt or they will produce inconsistent shapes.
The 1-gate philosophy assumes the ticket draft is the reviewable artifact. If you find users frequently rejecting at the gate AND citing problems in the analyses (not the synthesis), promote analyses to a 2nd gate. Don't preemptively add it.
TCC handling is non-negotiable. macOS Sonoma+ blocks Claude's ls on ~/Downloads by default. cp works. Always copy to .tmp/ first.
Don't generate tickets for formats the user didn't ask for. Even if a taxonomy URL lists 30 formats and the user provided 4, only process the 4.