interface:
  display_name: "Suede Video"
  short_description: "Suede rights-aware video planning and production"
  default_prompt: "Use $suede-video on [target]. The user is planning, scripting, or repurposing video content for marketing or social. Work through format selection, hook structure, short-form pacing, scripting, and repurposing one shoot into many cuts, ground every recommendation in evidence the user can check, and return the decisions, the reasoning, and what to measure next."
policy:
  allow_implicit_invocation: true

{
  "skill_name": "suede-video",
  "evals": [
    {
      "id": 1,
      "prompt": "We need a 2-minute product demo video for our SaaS homepage. What's the fastest way to produce it?",
      "expected_output": "Should check for product-marketing.md first. Should walk through the Product Demo Video workflow: script the key features and value props (cross-reference `suede-copy`), screen record the product flow, programmatic overlay with Hyperframes or Remotion for titles, callouts, and transitions, optional AI B-roll for establishing shots, voiceover via recording or an approved avatar workflow, and export at platform-appropriate specs. Should recommend a programmatic approach when it fits the verified runtime. Should remind: do not use AI for product UI screens because models can hallucinate UI; use real screen recording. Should make captions an accessibility default and require current account data before stating a sound-off viewing rate.",
      "assertions": [
        "Checks for product-marketing.md",
        "Walks through Product Demo workflow steps",
        "Uses real screen recording, not AI generated UI",
        "Recommends programmatic overlay tool",
        "Mentions captions",
        "Cross-references suede-copy"
      ],
      "files": []
    },
    {
      "id": 2,
      "prompt": "We want to make weekly product update videos. About 60 seconds each. Don't want to be on camera. Recommend a setup.",
      "expected_output": "Should consider an AI-avatar workflow for the recurring no-camera requirement, but first discover currently callable tools and verify authenticated access, current official features, price, output rights, and voice or likeness consent. If no avatar tool is available, it should return a vendor-neutral manual workflow using an approved script, user-operated upload, export checklist, and recorded-voice or camera fallback. It should outline a reusable pipeline from product context through script, approved presenter, optional overlay, review, captions, and export. It should explain the authenticity tradeoff and avoid hard-coded vendor rankings or plan claims.",
      "assertions": [
        "Recommends AI avatar approach",
        "Discovers and verifies current authorized avatar tooling",
        "Provides a manual fallback when no connector is callable",
        "Requires voice and likeness consent",
        "Identifies as a recurring use case",
        "Warns about authenticity tradeoff"
      ],
      "files": []
    },
    {
      "id": 3,
      "prompt": "I want to generate a 10-second clip of a person typing on a laptop in a coffee shop for our landing page. Which AI tool?",
      "expected_output": "Should discover which image-to-video or text-to-video tools are currently callable and authorized, then compare only those using current official documentation, cost, duration, output rights, and motion-control needs. If none is available, it should provide a vendor-neutral prompt and licensed-stock or original-footage fallback. The prompt should follow Subject + Action + Camera + Style + Mood. It should warn about vague prompts, missing camera direction, unverified readable text, and unapproved likenesses.",
      "assertions": [
        "Compares only currently available authorized generators",
        "Provides structured video prompt example",
        "Follows Subject + Action + Camera + Style + Mood pattern",
        "Warns about common prompt mistakes",
        "Provides a manual or licensed-footage fallback"
      ],
      "files": []
    },
    {
      "id": 4,
      "prompt": "We just did a 60-minute webinar. How do we get short clips out of it for social?",
      "expected_output": "Should apply the Repurposing Workflow: long-form source to transcript-based cleanup, bounded clip selection, captions and platform styling, then approved distribution. Should explain when each available tool fits and verify current access, cost, and rights before use. Should make captions an accessibility default without asserting a universal sound-off rate. Should treat aspect ratio and opening-hook timing as platform and account hypotheses to verify. Should cross-reference `suede-social` for channel strategy.",
      "assertions": [
        "Applies repurposing workflow",
        "Maps the workflow to discovered tools or a manual edit fallback",
        "Uses captions as an accessibility default",
        "Treats aspect ratios as current platform requirements to verify",
        "Treats opening-hook timing as a testable hypothesis",
        "May cross-reference suede-social"
      ],
      "files": []
    },
    {
      "id": 5,
      "prompt": "We need to generate 50 personalized intro videos for sales outreach. Each one mentions a different company name and pain point.",
      "expected_output": "Should treat this as a rights-sensitive batch workflow. Before recommending automation, it should discover currently callable avatar and rendering tools, verify access, price, output rights, personalization consent, and approved company claims. It should prepare a master template and run a bounded pilot sized to reveal quality and reply-signal problems before producing all 50; the pilot size must be justified by cost and review capacity rather than hard-coded. If no tools are callable, it should return scripts, variables, asset manifest, captions, and manual editor instructions. It should track replies and cost against an approved baseline without asserting the videos must outperform email.",
      "assertions": [
        "Discovers current authorized avatar and rendering tools",
        "Provides a manual production fallback",
        "Suggests template + loop approach",
        "Recommends a justified bounded pilot before the full batch",
        "Mentions reply tracking / ROI",
        "Mentions captions"
      ],
      "files": []
    },
    {
      "id": 6,
      "prompt": "Should I use Hyperframes or Remotion for programmatic video?",
      "expected_output": "Should first verify whether Hyperframes and Remotion are installed or callable and read their current official documentation and licenses. It should compare the verified runtime, authoring model, animation needs, rendering path, hosting cost, licensing, and the user's stack. If neither is available, it should provide a renderer-neutral storyboard, asset manifest, and timing spec. It should not assert ownership, license, hosting, or scale claims from memory.",
      "assertions": [
        "Compares the two with the When to Pick Which table",
        "Verifies both current runtimes and official documentation",
        "Compares rendering and hosting paths",
        "Compares current licenses",
        "Provides a renderer-neutral fallback",
        "Asks about stack or animation needs"
      ],
      "files": []
    },
    {
      "id": 7,
      "prompt": "There's a TikTok edit style I love — fast cuts, one-word captions that pop, a whoosh on every scene change. I have my own talking-head clip. Break down how that edit works so I can replicate the style. Here's the reference: [link]",
      "expected_output": "Should apply references/edit-anatomy.md, not just describe the reference. It should first discover a currently callable authorized media viewer, local-file inspector, or browser. If none is available, it should request the media, screenshots, or a timecoded export and provide a manual frame-sampling checklist. It must not claim to have seen frames it did not render. It should extract the edit anatomy into both a per-beat sheet and a concise style summary, present the sheet for review before execution, map execution to a currently available editor or a manual handoff, and copy only editing grammar applied to the user's own footage and message.",
      "assertions": [
        "Applies the edit-anatomy reverse-engineering method, not a plain description",
        "Discovers an authorized viewer or uses a supplied-media manual fallback",
        "Extracts the edit anatomy across the dimensions and expresses patterns (not a raw list of cut timestamps)",
        "Outputs a per-beat beat sheet AND a style summary of the signature moves",
        "Presents the beat sheet for a review-once approval before executing",
        "Maps execution to an available editor or manual handoff",
        "Applies the originality guardrail — copies editing grammar applied to the user's own footage, never the reference's footage/script/music"
      ],
      "files": []
    }
  ]
}

# Suede AI Video Prompting Guide

How Suede writes testable prompts for any currently callable and authorized AI
video model.

---

## Prompt Structure

A strong video prompt follows this formula:

```
[Subject] + [Action] + [Camera movement] + [Visual style] + [Lighting/mood] + [Technical specs]
```

### Example Prompts by Use Case

**Product hero shot:**
```
A sleek laptop on a minimal white desk, screen glowing with a dashboard UI,
camera slowly orbits 180 degrees around the desk,
soft volumetric lighting from the left, shallow depth of field,
cinematic commercial aesthetic, 4K
```

**Lifestyle B-roll:**
```
A woman in a modern co-working space smiling while looking at her phone,
natural window light, candid documentary feel,
camera handheld with subtle movement, warm color grading
```

**Abstract/brand:**
```
Flowing liquid gold particles forming the shape of a network graph,
dark background, particles catch light as they move,
slow-motion macro photography style, dramatic rim lighting
```

**SaaS explainer scene:**
```
An overhead shot of a team around a conference table pointing at charts,
camera slowly pushes in, bright modern office,
clean corporate style, even lighting, 1080p
```

---

## Camera Movement Vocabulary

Use these terms — video models understand them:

| Term | Effect |
|------|--------|
| **Static** | Locked camera, no movement |
| **Pan left/right** | Camera rotates horizontally |
| **Tilt up/down** | Camera rotates vertically |
| **Dolly in/out** | Camera moves toward/away from subject |
| **Orbit** | Camera circles around subject |
| **Tracking shot** | Camera follows moving subject |
| **Crane/aerial** | Camera rises or descends |
| **Handheld** | Subtle shake, documentary feel |
| **Zoom** | Lens zoom (different from dolly) |
| **Slow push** | Gradual dolly in — builds tension/focus |

---

## Style Keywords

### Cinematic
- "cinematic color grading"
- "anamorphic lens flare"
- "shallow depth of field"
- "film grain"
- "35mm film"

### Commercial/Corporate
- "clean commercial lighting"
- "bright and airy"
- "professional corporate aesthetic"
- "even, diffused lighting"

### Documentary
- "handheld documentary style"
- "natural lighting"
- "candid, unposed"
- "observational camera"

### Social/Trendy
- "vertical 9:16"
- "fast-paced cuts"
- "bold text overlays"
- "high contrast, saturated colors"

---

## Model-Specific Verification

Do not carry model capability, quality, duration, price, or prompt-length claims
from memory. For each currently callable candidate:

1. Read its current official documentation and the authenticated account limits.
2. Record the controls actually exposed: text-to-video, image reference, camera,
   duration, audio, seed, edit, and export.
3. Run the same bounded prompt and reference frame where terms allow.
4. Compare visual fit, continuity, instruction adherence, render time, failure
   rate, rights, and total cost.
5. Keep model-specific advice only when the current docs or test output supports
   it, and attach the source date.

If no model is callable and authorized, deliver prompts, reference-frame briefs,
and a manual test matrix. Do not claim that generation occurred.

---

## Common Prompt Mistakes

| Mistake | Why It Fails | Fix |
|---------|-------------|-----|
| "A person using our app" | Too vague, no visual detail | Describe the person, setting, lighting, camera |
| Including text/logos | Generated typography may not meet accuracy requirements | Add reviewed text in a verified editor |
| "Make it viral" | Not a visual instruction | Describe the visual style you want |
| Unbounded prompt detail | Important constraints can become hard to diagnose | Start concise, then add one tested constraint at a time |
| No camera direction | Uncontrolled camera behavior | Specify or test movement when the current model supports that control |
| "Realistic" alone | Not specific enough | "Photorealistic, natural lighting, shot on RED camera" |

---

## Prompting Workflow

1. **Reference first** — find a real video that looks like what you want
2. **Describe it** — break down: subject, action, camera, style, mood
3. **Generate a bounded comparison set** — same concept, one controlled variable
4. **Iterate on the selected result** — refine from recorded evidence
5. **Composite** — combine AI footage with programmatic text/overlays

---

## Aspect-Ratio Verification

Read current destination documentation and preview the authenticated composer
before choosing a ratio. The rows below are starting test candidates, not
current platform requirements:

| Placement hypothesis | Starting ratio candidate | Starting resolution candidate |
|----------------------|--------------------------|-------------------------------|
| Long-form video | 16:9 | 1920x1080 |
| Short-form full-screen | 9:16 | 1080x1920 |
| Feed placement | 1:1 or 4:5 | 1080x1080 or 1080x1350 |
| Website hero | Match the approved component | Match rendered display and performance budget |
| Professional feed | 16:9, 1:1, or another supported ratio | Verify in current composer |

---

## Cost Control

- Verify current pricing, included credits, failed-generation treatment, and
  commercial rights before generating.
- Set a run-level budget cap and maximum comparison count.
- Test lower-cost preview settings only when current docs say they preserve the
  decision-relevant characteristics.
- Test image-to-video against text-to-video; do not assume it is cheaper or
  better on the current model.
- Batch only when the account terms, cost model, and review capacity support it.
- Reuse footage only when source and derivative rights permit it.

# Reverse-Engineering an Edit (The Beat Sheet)

A reference video's outcome may reflect its edit, footage, audience,
distribution, topic, or account history. This reference isolates the editing
choices into a **reusable edit spec** so they can be tested on original footage
without claiming the edit caused the observed performance.

This is the tool-agnostic half of "copy any viral edit": the *decomposition*. The generation is whatever you edit with afterward — CapCut, Premiere, Remotion/Hyperframes, or an AI restyle tool. The spec is the deliverable.

## When to use it

- A competitor's or creator's edit keeps stopping your scroll and you want to understand *why* and replicate the technique
- You have raw footage (a talking-head clip, a demo) and a reference edit whose style you want to match
- You're briefing an editor or a template and need the edit decisions written down, not vibes

Don't use it to copy someone's actual creative — this extracts the *editing grammar* (structure, rhythm, caption treatment), not the script, footage, or brand. Same rule as mining organic content for vocabulary in the hook system: take the technique, never the creative.

## Step 1 — Pull the reference so you can actually read the edit

You cannot decompose an edit from a description alone. First discover whether a
currently callable, authorized media viewer, local-file inspector, or browser
can expose the frames and timing.

- If available, inspect the actual media and sample frames at cut points.
- If only a public post is available, use an authorized browser or source reader
  within the platform's terms.
- If no tool is available, ask the user for the media file, screenshots, or a
  timecoded export and give them a manual frame-sampling checklist.
- Never claim to have seen frames that were not actually rendered or supplied.

Note the total duration and roughly how many cuts there are before you start — cuts-per-second is the single most telling number about an edit's energy.

## Step 2 — Extract the anatomy, beat by beat

Walk the reference from 0:00 and log every editing decision. The dimensions that define a short-form edit:

| Dimension | What to read off the reference |
|---|---|
| **Shot & framing** | Talking head / screen recording / b-roll / text card; close-up vs. wide; headroom, rule-of-thirds, or dead-center |
| **Cut rhythm** | Where each cut lands and how fast (cuts-per-second); is it on the beat, on the word, or on the breath? |
| **On-screen text** | The words, when each appears/disappears, and *where* on the frame (top-third caption vs. big centered statement) |
| **Caption style** | Font, weight, color, outline/box, and animation (word-by-word pop, karaoke highlight, whole-line) |
| **Motion** | Punch-ins / zoom pushes, shakes, whip-transitions, speed ramps — where and how aggressive |
| **B-roll & overlays** | Cutaways, stickers, arrows, emoji, screenshots, meme inserts — what's laid over the base footage and when |
| **Sound design** | Music choice and where it hits, SFX (whooshes, dings, risers), and deliberate silence before a beat |
| **Hook (first 2s)** | The single most-copied element — what's on screen and said in the opening two seconds, before anyone's committed |
| **Pacing curve** | Does it stay frantic, or fast-hook → slower-body → fast-CTA? Map the energy over the runtime |

Read the *pattern*, not just the instances: "a hard cut + punch-in on every new sentence," "caption is one word at a time, yellow, karaoke-highlighted, bottom third," "a whoosh SFX on every scene change." Patterns are what make an edit replicable; a list of 40 individual cuts is not.

## Step 3 — Write the beat sheet

Two artifacts: a per-beat table and a short style summary.

**The beat sheet** — one row per beat (a beat = a cut or a distinct edit event):

```
| Beat | Time      | Shot            | On-screen text        | Caption style        | Transition / motion   | Audio            |
|------|-----------|-----------------|-----------------------|----------------------|-----------------------|------------------|
| 1    | 0:00–0:02 | CU talking head | "STOP doing this"     | word-pop, yellow, ctr| hard in, slow push    | music in + riser |
| 2    | 0:02–0:04 | screen record   | (caption only)        | karaoke, white, btm  | hard cut + whoosh     | click SFX        |
| …    |           |                 |                       |                      |                       |                  |
```

**The style summary** — the 3–5 *signature moves* that make this edit recognizable, stated so they're reusable:
- e.g. "Every sentence gets a hard cut + a 5% punch-in." / "Captions are one word at a time, bottom-third, karaoke-highlighted." / "A whoosh SFX on every cut; music drops out for 0.5s before the CTA." / "The hook is a bold centered statement on frame 1, no logo."

The signature moves are the real deliverable — someone can apply those five rules to any footage and get the style. The table is the detailed backup.

## Step 4 — Review once, then execute

Show the beat sheet before anyone edits anything — the same review-once gate as the ad-creative creative review page. The reviewer checks two things:

- **The on-screen text says what you want** (mapped to your message, not the reference's)
- **The scene changes land where you want them** (your footage's beats, not a blind copy of the reference's timing)

Approve, then execute the spec with your footage:
- **Remotion / Hyperframes** — when you want the edit templated and data-driven (see the programmatic-video section in SKILL.md); the beat sheet *is* the composition spec.
- **CapCut / Premiere / an editor** — hand off the beat sheet + style summary as the brief.
- **An AI restyle tool** — feed the style summary as the target style.

## Originality guardrail

You are copying the *edit*, not the content. The beat sheet describes technique (cut rhythm, caption treatment, motion, sound design) applied to **your** footage and **your** message. General editing techniques and style cues are usually reusable — U.S. copyright protects expression, not procedures or methods (17 U.S.C. §102(b)) — but the reference's specific creative expression is not, and closely reproducing a finished video's exact selection and arrangement of choices can still create risk. So copy the grammar, not the finished work: use your own footage, message, script, voiceover, licensed music/SFX/samples, and brand elements. If the reference's "style" is really a specific bit or sketch, that's their creative — draw inspiration, don't reproduce it.

## Common mistakes

- **Describing instead of reading** — you cannot extract caption style or cut
  timing from a transcript alone; inspect supplied or actually rendered frames.
- **Logging instances, not patterns** — 40 cut timestamps isn't a spec; "hard cut + punch-in per sentence" is.
- **Copying the reference's timing onto different footage** — beats land on *your* words and *your* cuts; the reference gives you the grammar, not the calendar.
- **Skipping the hook** — the first 2 seconds carry most of the retention; decode them in the most detail.
- **Reproducing the creative** — matching the edit is fine; re-shooting their exact bit, script, or using their footage/music/SFX is not.

# Programmatic Renderers: React Path and Renderer Selection

Read this when the repo already uses React, or when a renderer choice between an
HTML/CSS path and a React path has to be justified before any install
authorization is requested. The HTML/CSS example and both authorization gates
live in SKILL.md; this file only carries the React sample and the selection
table.

---

## React renderer sample

Remotion may fit a React-based workflow. Verify the installed or callable
version, current documentation, license, rendering path, and hosting cost before
recommending it. React components express timed visuals and props drive
content; confirm whether rendering is local or uses an authorized hosted
renderer.

```tsx
export const ProductDemo: React.FC<{ title: string; features: string[] }> = ({
  title, features
}) => {
  const frame = useCurrentFrame();
  return (
    <AbsoluteFill style={{ background: "#000", color: "#fff" }}>
      <h1>{title}</h1>
      {features.map((f, i) => (
        <Sequence from={i * 30} key={i}>
          <p>{f}</p>
        </Sequence>
      ))}
    </AbsoluteFill>
  );
};
```

**Candidate fit:** complex animation, interactive previews, or batch rendering
when the verified runtime supports them.

---

## When to Pick Which

| Factor | HTML/CSS renderer | React renderer |
|--------|-------------------|----------------|
| Existing stack | Browser and CSS capability | React and renderer capability |
| Animation needs | Test required transitions | Test required timeline primitives |
| Batch rendering | Verify local or hosted path | Verify local or hosted path |
| Team fit | Inspect maintainability in this repo | Inspect maintainability in this repo |
| Rights and cost | Verify current license and runtime cost | Verify current license and runtime cost |

Neither column is a default. Pick the renderer the repo can already run, and
record the evidence for that call in the handoff.