Showoff

!node "${CLAUDE_SKILL_DIR}/scripts/project-context.mjs"

showoff

Turn a project, a GitHub PR URL, a URL-backed app, or a supplied evidence path into a polished showcase video with a poster and share copy. You are the orchestrator. Worker lanes are read-only researchers that return findings to you. You are the only writer of shared artifacts.

Execution mode

Run the orchestrator inline in the main conversation so the media checkpoint and preview approval can receive real user input. Do not fork the entire workflow. Use the Agent tool only for the read-only worker lanes, launching all selected lanes for a phase in parallel.

Boundary (state this precisely; never overstate it)

ShowOff never automatically publishes or uploads the finished artifacts. It may contact supplied PR/app hosts, Claude Code, HyperFrames update sources, and explicitly approved Media OS providers. Media providers receive only the approved requests you send them; ShowOff never reads credential files and never uploads project evidence without an explicit approved Media OS request. Do not overstate privacy or imply the tool never reaches the network.

Model work runs exclusively through Claude Code agent primitives. Do not call the Anthropic API directly and do not hard-code a model name.

Arguments

Parse $ARGUMENTS directly as a string. Supported flags (double-dash) and one positional:

| Flag | Values | Default | |------|--------|---------| | --tone | any preset or freeform phrase (e.g. casual, professional, bold) | professional | | --format | landscape, vertical, square | landscape | | --duration | integer 10-90 (seconds) | 25 | | --audience | any phrase (e.g. devs, execs, general) | general | | --goal | demo, pitch, update, tutorial | demo | | --narration | flag, no value; enables voice-over script, captions, transcript | off | | --media | auto, approved, none | auto | | --title | quoted string | infer from source | | positional | path to a project root, a GitHub PR URL, or an app URL | cwd |

Unknown flags: warn and continue. Conflicting values: last one wins. Duration outside 10-90: clamp to the nearest bound and warn. Only the flags in the table above are accepted; warn on anything else.

Resume semantics: The positional argument may be an existing timestamped run directory.

• If the directory is an incomplete run (state is not done) and the user plainly asks

to resume, repair, or finish it, continue writing into that same directory. Add or repair only missing or stale artifacts; do not delete or wholesale rewrite validated artifacts.

• If the directory is a done run, treat it as source material and create a new

timestamped sibling directory under showoff-output\. Never mutate a completed run.

• There is no resume flag. The instruction is given in plain language (for example:

"resume this run and re-render the poster").

Platform Note

When running on Windows, use Windows-style paths with backslashes in every file path, every shell command, and every output artifact. Do not use bash-specific syntax (&&, $(), backtick subshells). Prefer PowerShell-safe one-liners or the Node scripts bundled with this skill for any shell work.

Output Layout

Create a timestamped subdirectory under the project root for every normal invocation:

\showoff-output\\
  evidence-dossier.md
  showoff-plan.md
  composition\               (HyperFrames project)
  showoff.mp4
  showoff.jpg
  share-copy.md
  showoff-manifest.json
  captions.vtt               (narration only)
  transcript.md              (narration only)

Run vs. resume distinction:

• Normal invocation (path is a project root, PR URL, or app URL): create a new

timestamped subdirectory.

• Incomplete run (positional path points to an existing run directory whose state is

not done, and the user asks to resume/repair/finish it): write into that same directory. Repair or add only missing or stale artifacts; do not delete or wholesale rewrite artifacts that already passed their gate.

• Done run (positional path points to a run directory in done state): treat it as

source material only, create a new timestamped sibling under showoff-output\, and never write into the completed run.

Never overwrite or delete a completed prior run. If showoff-output\ already exists, read it for prior runs. Collect the timestamp once at skill start and reuse it for the directory name and the manifest. Produce captions.vtt and transcript.md only when --narration is set.

Orchestration

See [orchestration](references/orchestration.md) for the complete state machine, lane matrix, and route history rules. Working summary:

1. Sense state - run scripts/validate-output.mjs against the

newest existing output directory (if any). Parse its state field into one of: cold, has-evidence, has-plan, composing, rendered, has-poster, done, or broken.

1. Select lanes - from the selection matrix in

[orchestration](references/orchestration.md), include only lanes whose corresponding section is missing or stale. When the run is cold, all five lanes are selected. On resume, select only the lanes needed for the missing or stale sections.

1. Launch parallel - fire all selected lanes for a phase in ONE assistant response (a

single batch of Agent-tool calls) so they run in parallel. No lane depends on another lane's output. Each lane reads the source directly and RETURNS structured findings to you; lanes never write shared files or private scratch paths.

1. Reconcile and write - after all selected lanes return, you (the orchestrator)

reconcile their findings, mechanically verify every claim you intend to use, then write evidence-dossier.md and showoff-plan.md. You are the only writer.

1. Gate check - after each gate, re-sense from disk by re-running

validate-output.mjs. Route forward on pass, to repair on failure, or halt on oscillation.

1. Oscillation guard - maintain a route-history list. If the same state label appears

twice in succession, or repair attempts reach 3, stop immediately and report the last error list. The maximum number of repair attempts is 3 everywhere.

Worker Lanes (read-only researchers)

Five independent lanes. Each reads the source directly and returns findings to the orchestrator. No lane reads another lane's output, and no lane writes any file. At cold state all five run in parallel in one batch.

evidence-investigator

Collect raw facts only. No narrative, no opinion.

• Project path: read README (any capitalisation), the primary manifest

(package.json, pyproject.toml, Cargo.toml, go.mod, etc.), any CHANGELOG, and up to 5 representative source files. Record the source path for every fact.

• PR URL: fetch PR title, body, diff summary, and any linked issue titles.
• App URL: fetch page title, meta description, and visible heading text.
• Return every fact with its source path or URL. Detail rules:

[project-inspection](references/project-inspection.md).

product-narrator

Build story structure by reading the source directly and citing its own sources.

• Infer the hook: one sentence naming the concrete user benefit (no vague adjectives).
• Build a 3-beat arc: problem / solution / proof.
• Map beats to --duration using the formula in [narrative](references/narrative.md).
• Draft the narration script ONLY when --narration is in $ARGUMENTS.
• Return the Narrative findings (and narration cues if applicable) with source citations.

visual-curator

Identify available visual evidence on disk. Never fabricate or download assets.

• Glob for images: *.png, *.jpg, *.jpeg, *.gif, *.webp under the project root.
• Glob for recordings: *.mp4, *.mov, *.webm.
• Score each file: 1 = icon/logo, 2 = screenshot, 3 = demo recording, 4 = annotated demo.
• If --media none, report "no external media requested" and list on-disk assets only.
• Return a scored table of real file paths for the Visual Assets section.

proof-auditor

Run an independent evidence-risk and claim-verification inventory. This lane does NOT consume another lane's dossier; it inspects the source itself.

• Enumerate every load-bearing factual claim the source could support (metrics, counts,

capabilities) and locate the exact file and line that backs each one.

• Mark any claim with no locatable source as UNVERIFIED.
• UNVERIFIED claims must not appear on screen or in narration.
• Return a claim / source / PASS|UNVERIFIED inventory for the Proof Audit section.

taste-director

Produce style guidance from the flags and a direct read of the source's visual language.

• Design read (one line), then set the three dials (see [taste](references/taste.md)):

DESIGN_VARIANCE, MOTION_INTENSITY, VISUAL_DENSITY.

• Color, typography, pacing, and opening-motion direction.
• Return the Taste findings.

Orchestrator reconciliation

After the lanes return, you reconcile and verify before writing anything:

• Cross-check the narrator's and auditor's claims against the investigator's facts and the

source itself. Keep only claims you can mechanically verify.

• Drop or downgrade any UNVERIFIED claim so it never reaches the screen or narration.
• Resolve conflicting findings by re-reading the cited source; synthesize one canonical

version per section.

• Write evidence-dossier.md, then showoff-plan.md from the reconciled findings, using

[templates/showoff-plan.md](templates/showoff-plan.md) as the structure.

Workflow Gates

Gate checks are run via scripts/validate-output.mjs. Full specification in [orchestration](references/orchestration.md).

| # | Gate | Artifact | Hard blocker | |---|------|----------|--------------| | 1 | Evidence dossier | evidence-dossier.md | No sourced claims found | | 2 | Showoff plan | showoff-plan.md (all required sections) | Any required section missing | | 3 | Taste + story review | Orchestrator self-review checklist | Hook unclear or UNVERIFIED claim in plan | | 4 | Composition brief + handoff | composition-brief.md and composition\ project | Brief missing or project marker absent | | 5 | HyperFrames check | npx hyperframes check exits 0 | Any error in check output | | 6 | Preview approval + render | showoff.mp4 exists and nonzero | Missing/zero-byte file, or preview not approved | | 7 | Poster | showoff.jpg extracted from verified frame 0 | File missing, zero bytes, or pixel MAE vs frame 0 exceeds 3.0 | | 8 | Share copy | share-copy.md (nonempty) | File empty | | 9 | Manifest | showoff-manifest.json (required fields) | Missing required fields |

Gate 3 - Taste/Story Review (orchestrator self-review)

Before writing the composition brief, confirm ALL of the following:

• [ ] Hook names a concrete user benefit; no vague adjectives.
• [ ] Every on-screen text claim appears in evidence-dossier.md with a source path.
• [ ] Total duration fits within --duration (clamped to 10-90 s).
• [ ] Visual Assets section lists at least one real on-disk file, OR --media none.
• [ ] Proof Audit has zero UNVERIFIED rows in any text that will be visible on screen.

Fail any check: repair the plan, re-run gate 2. Do not proceed to gate 4 until all pass.

Gate 4 - Composition brief and HyperFrames routing

Read [composition](references/composition.md) and write composition-brief.md from [templates/composition-brief.md](templates/composition-brief.md). Choose the HyperFrames route by the source material first (not by --goal):

| Source material | HyperFrames route | |-----------------|-------------------| | GitHub PR URL or code change | pr-to-video | | Website, web app, or product URL | product-launch-video | | Anything else (path, footage, brief) | general-video |

Do not route a tutorial goal to a faceless explainer when the source is a product; the source decides the route. Hand --format, --duration, --tone, and the Visual Assets list to HyperFrames through the brief. HyperFrames owns composition mechanics, check, preview, and render. The HyperFrames project is created under composition\.

HyperFrames project scaffolding: initialize the project directly inside composition\ so that marker files (package.json, hyperframes.json, BRIEF.md) land at composition\package.json and so on. From the run directory run:

npx hyperframes init composition

or equivalently, change into the directory first and initialize the current path:

cd composition && npx hyperframes init .

Do not run npx hyperframes init from inside composition\; that creates a nested composition\\ subdirectory and copies no marker files upward. The validator requires a recognizable marker directly in composition\.

Media opportunity checkpoint (after plan, before composition)

Read [media](references/media.md). Run exactly one media-opportunity pass on the plan, after gate 3 and before the composition brief is handed off:

• --media none: skip Media OS entirely; use only on-disk project assets.
• --media approved: skip the ask and approve the grounded opportunities the pass surfaces.
• --media auto: consolidate every grounded opportunity into one message and ask once.

Media OS owns asset resolution and generation, and only after explicit approval. Narration stays off unless --narration is explicit; approving media does not enable narration.

Gate 5 and 6 - Check, preview approval, render

Run npx hyperframes check before any render (mandatory; resolve every error first). Then run a preview pass and obtain preview approval before the final render. HyperFrames renders showoff.mp4 into the run directory.

Gate 7 - Poster selection and baking

Review the settled candidate snapshots from the composition, select the strongest (text fully rendered, no motion blur, representative of the content), and set that visual as frame 0 of the composition. Re-run npx hyperframes check and re-render so frame 0 is verified, then extract showoff.jpg from the verified frame 0:

ffmpeg -i showoff.mp4 -vframes 1 -q:v 2 showoff.jpg

A later settled frame is never acceptable. Do not use -ss to seek to a later timestamp (for example -ss 3.5) to extract the poster; that decodes a later frame, not frame 0, and will fail the pixel-match check in validate-output.mjs. If frame 0 is not fully settled -- for example it is a dim pre-animation state -- modify the composition's initial state so the first rendered frame is already fully settled, then re-render and re-extract from the new frame 0.

Do not claim that ffmpeg can embed a thumbnail into an already-rendered MP4 without re-composition; the poster must correspond to the actual frame 0 of showoff.mp4. validate-output.mjs decodes both files to raw rgb24 and rejects the run if the mean absolute error exceeds 3.0.

Gate 9 - Manifest

Write showoff-manifest.json using the single comprehensive schema in [delivery](references/delivery.md). Required top-level keys:

{
  "schema_version": "1",
  "showoff_version": "0.1.0",
  "produced_at": "",
  "project": { "subject": "", "source": "", "route": "" },
  "config": { "tone": "", "format": "", "duration_s": 25, "audience": "", "goal": "", "title": "" },
  "dials": { "DESIGN_VARIANCE": 5, "MOTION_INTENSITY": 5, "VISUAL_DENSITY": 5 },
  "design_read": "",
  "narration": false,
  "outputs": {
    "video": "showoff.mp4",
    "thumbnail": "showoff.jpg",
    "plan": "showoff-plan.md",
    "brief": "composition-brief.md",
    "share_copy": "share-copy.md",
    "captions": null,
    "transcript": null
  },
  "gates": {},
  "reproducibility": { "hyperframes_version": "", "brief_hash": "", "evidence_sources": [] },
  "media_assets": [],
  "claims": [],
  "external_services_used": [],
  "published": false
}

`reproducibility.hyperframes_ver

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shyamsridhar123
• Source: shyamsridhar123/ShowOff
• License: MIT

Install and usage instructions live in the source repository linked above.