@muskanmeet/invoicing-design-system 0.1.0

package/.local/secondary_skills/storyboard/.fingerprint

@@ -0,0 +1 @@
+0db6aaec56945f0bdaf338b35da39710

package/.local/secondary_skills/storyboard/SKILL.md

@@ -0,0 +1,558 @@
+---
+name: storyboard
+description: Plan videos with shot lists, scripts, storyboards, and filming guides for social media.
+---
+
+# Storyboarding for Social Content
+
+Shot-by-shot storyboards for TikTok, Reels, YouTube Shorts, and UGC ad scripts. Built around retention physics, not film-school conventions.
+
+## When to Use
+
+Activate this skill when the user says any of the following (or similar phrasing):
+
+### Direct triggers (high confidence)
+
+- "storyboard," "shot list," "shot-by-shot breakdown"
+- "video script," "script for my video," "TikTok script," "Reel script"
+
+- "creator brief," "filming guide," "filming plan"
+- "UGC ad script," "UGC brief"
+
+- "pre-production plan"
+- "hook ideas," "hook variants," "video hooks"
+
+- "plan my next video," "plan a video"
+- "video ad script"
+
+- "content series for video," "plan a video series"
+
+#### Contextual triggers (use when intent is planning/filming, not rendering)
+
+- "plan a TikTok / Reel / Short" — planning what to film, not auto-generating a rendered video
+- "video content plan" — planning a filming schedule, not writing blog posts
+
+- "social media video ideas" — brainstorming video concepts, not written captions
+- "create a TikTok ad" — when the user intends to film it themselves (ask if ambiguous)
+
+- "ad campaign for [product]" — when the user mentions video, filming, or creators (otherwise may be ad-creative for static ads)
+
+##### When to ask for clarification
+
+If the user says "make me a video," "create a TikTok," or "video ad" without specifying whether they want a plan to film or a rendered animation, ask:
+
+> "Would you like me to plan a video for you to film (storyboard with shot list and script), or create an animated video that renders automatically?"
+
+## When NOT to Use
+
+- **Static ad images** → use ad-creative skill instead
+- **Written social media posts, blog content, email copy** → use content-machine skill instead
+
+- **Brand identity (logos, colors, typography)** → use branding-generator skill instead
+- **Code-rendered animated videos** (motion graphics, animated explainers that play automatically) → use video-js skill instead
+
+- **Slide decks / presentations** → use slides skill instead
+- **SEO landing pages** → use programmatic-seo skill instead
+
+### Key Distinction from Similar Skills
+
+| This skill (storyboard) | video-js | ad-creative | content-machine |
+
+|---|---|---|---|
+
+| Plans videos you go **film yourself**|**Renders**animated videos from code | Creates**static ad images**| Writes**text content** (posts, blogs, emails) |
+
+| Output: script + shot list + visual storyboard on canvas + creator brief | Output: playable animated video in browser | Output: designed image files | Output: written copy |
+
+| For real-camera, UGC, creator content | For motion graphics, explainers, animated ads | For display ads, social image posts | For captions, articles, newsletters |
+
+## Platform Specs (2025-2026)
+
+| Platform | Ratio | Resolution | Max duration | Sweet spot | File |
+
+|---|---|---|---|---|---|
+
+| TikTok | 9:16 | 1080×1920 | 10 min in-app / 60 min upload | **21-34 sec** | MP4/MOV, H.264, 287MB mobile / 500MB web |
+
+| Instagram Reels | 9:16 | 1080×1920 | 3 min in-app / 15 min upload | **<90 sec** for Explore boost | MP4/MOV, 4GB |
+
+| YouTube Shorts | 9:16 | 1080×1920 (up to 4K) | **3 min** | 15-60 sec | MP4 |
+
+| YouTube long-form | 16:9 | 1920×1080+ | unlimited | 8-12 min (mid-roll ads) | — |
+
+**Universal safe zone for cross-posting:**Keep all text, faces, logos inside the**center 900×1400** of the 1080×1920 frame. Top 14% + bottom 20-35% are covered by UI on at least one platform.
+
+## The 3-Second Rule (Data-Backed)
+
+TikTok's algorithm scores hook retention **separately** from total watch time. 2025 creator analytics:
+
+| 3-sec retention | View multiplier | Outcome |
+
+|---|---|---|
+
+| **85%+** | 2.8× | Viral tier — FYP push |
+
+| **70-85%** | 2.2× | Optimal reach |
+
+| **60-70%** | 1.6× | Average |
+
+| **<60%** | baseline | Minimal distribution |
+
+**Target: keep ≥65% of viewers past 0:03.** If you're losing >35% in 3 seconds, the hook is broken — rewrite the opening, not the body. 84% of viral TikToks in 2025 used an identifiable psychological trigger in the first 3 seconds.
+
+## Named Hook Formulas
+
+The scroll-stopping element must fire in **0-2 seconds**. Seconds 3-5 expand it. **Never introduce — interrupt.** Banned openers: "Hey guys," "Welcome back," "So today I'm gonna..."
+
+| Hook | Template | Trigger |
+
+|---|---|---|
+
+| **POV** | "POV: you just found out [revelation]" | Puts viewer inside the scenario; personal relevance |
+
+| **Stop-scrolling callout** | "Stop scrolling if you're a [role] who [pain]" | Audience self-selects; filters for high-intent |
+
+| **Contrarian** | "Everyone says X. That's completely wrong." | Cognitive dissonance demands resolution |
+
+| **Unfinished story** | "I almost [drastic action] until I found..." | Open loop — Zeigarnik effect |
+
+| **Negative listicle** | "3 [category] mistakes that are costing you [outcome]" | Loss aversion > gain framing |
+
+| **Number hook** | "$47,000 in 30 days — here's the exact breakdown" | Specificity = credibility |
+
+| **Secret reveal** | "What [authority] doesn't want you to know about X" | Insider info promise |
+
+| **Surprise reaction** | Open on a shocked face, silent beat, then reveal | Viewer's brain asks "what are they reacting to?" |
+
+| **Visual interrupt** | Start mid-action, mid-motion, mid-chaos | Pattern break — no static frame 1 |
+
+**The silent test:** Watch your first 3 seconds on mute. If text overlay + visual alone don't communicate the promise, it fails — ~85% of social video is watched muted.
+
+## Script Structure by Video Type
+
+### Organic short-form (15-60s) — Hook → Value → Loop
+
+```text
+
+0:00-0:02 HOOK Visual interrupt + text overlay with the promise
+
+0:02-0:05 EXPAND Why this matters to YOU (the viewer)
+
+0:05-0:XX DELIVER The value. Pattern-interrupt every 3-5s: cut, zoom, text pop, angle change
+
+0:XX-end LOOP/CTA End mid-sentence OR loop back to frame 1 for rewatch. Soft CTA in caption, not in video.
+
+```
+
+Mid-video retention hooks at ~15s and ~30s ("but here's the part nobody talks about...").
+
+### UGC ad (15-30s) — Direct Response formula
+
+The proven DR structure: **Hook → Problem → Agitate → Solution → Proof → CTA**
+
+```text
+
+0:00-0:02 HOOK "I was about to [give up on X]..."
+
+0:02-0:05 PROBLEM Show/say the pain. Be specific.
+
+0:05-0:08 AGITATE "And it just kept getting worse — [consequence]"
+
+0:08-0:20 SOLUTION Product in hand. Demo it working. Lo-fi > polished.
+
+0:15-0:22 PROOF Green-screen reviews behind you, or "my [authority figure] friend told me..."
+
+0:22-0:30 CTA Verbal + text overlay. "Link in bio" / "Use code X"
+
+```
+
+#### UGC ad writing rules
+
+- Write like you text a friend — contractions, "literally," "obsessed," imperfect grammar
+- One emotion per script (relief / excitement / transformation — pick one)
+
+- Modular shooting: film hook, problem, demo, CTA as separate clips → mix-and-match 3 hooks × 1 body × 2 CTAs = 6 ad variants
+- For TikTok Spark Ads, script must feel organic — get creator authorization codes; Spark Ads keep organic engagement metrics
+
+- Research pain points in TikTok comments / Amazon reviews / Reddit before writing — use their exact words
+
+**Vertical-specific angles:** Beauty → before/after transformation. Fitness → "30 days with X" challenge. SaaS → screen recording solving the problem in <10s. Ecom → unboxing + speed-of-delivery.
+
+## Shot-by-Shot Storyboard Format
+
+| \# | Time | Shot | Visual | On-screen text | VO / Audio | Retention device |
+
+|---|---|---|---|---|---|---|
+
+| 1 | 0:00-0:02 | CU face | Shocked expression, product out of frame | "I was today years old..." | [silence / gasp] | Surprise reaction hook |
+
+| 2 | 0:02-0:05 | MS | Hold up product | "...when I learned THIS" | "So I've been doing X wrong for 3 years" | Text reveal |
+
+| 3 | 0:05-0:08 | POV | Hands demo the product | — | VO continues | Angle change = pattern interrupt |
+
+| 4 | 0:08-0:12 | Split screen | Before / After | "BEFORE → AFTER" | — | Visual proof |
+
+| 5 | 0:12-0:15 | CU face | Direct to camera | "Link in my bio" | "Code SAVE20 — thank me later" | CTA |
+
+**Shot types:** CU (close-up), MS (medium), WS (wide), POV, OTS (over-the-shoulder), Screen recording, Green-screen, B-roll.
+
+## Platform-Specific Adaptations
+
+When the user targets multiple platforms, **always generate platform-tailored cut versions** in addition to the master storyboard. Each platform has different pacing, duration sweet spots, and UI overlays that affect how the same content should be edited.
+
+### Adaptation Strategy
+
+After building the master storyboard, create a **Platform Adaptation Table** on the canvas showing how to re-cut for each target platform:
+
+| Platform | Target Duration | Pacing | Key Adjustments |
+
+|---|---|---|---|
+
+| **TikTok** | 21-34 sec | Fastest — cut every 1.5-2 sec | Tightest edit. Remove any shot >3s. Combine AGITATE into PROBLEM if needed. Text overlays must be larger (thumb-stopping). End with loop or abrupt cut, not fade. |
+
+| **Instagram Reels** | 30-60 sec | Medium — cut every 2-4 sec | Can breathe slightly more. Add a 2nd proof beat if available. Reels rewards saves — add a "save this" text cue. Caption overlay style should match IG aesthetic (cleaner fonts). |
+
+| **YouTube Shorts** | 30-60 sec | Medium — cut every 3-5 sec | Allows the longest version. Can include extra context or a longer demo. Subscribe CTA works better than "link in bio." End screen overlay is supported. |
+
+| **YouTube long-form** | Re-cut to 16:9 | Slowest — cut every 4-8 sec | Horizontal reframe. Can expand into a full explainer. Add intro context (5-10s) before the hook. Mid-roll friendly at 8+ min. B-roll and screen recordings can run longer. |
+
+### How to Generate Adaptations
+
+For each platform the user targets:
+
+1. Start from the master storyboard (all shots)
+2. Note which shots to **trim**, **merge**, or **cut entirely** for that platform's sweet spot
+
+3. Adjust text overlay sizing for the platform's safe zone
+4. Modify the CTA to match platform conventions (TikTok: "link in bio" / YouTube: "subscribe" / Reels: "save this")
+
+5. Add platform-specific retention devices (TikTok: loop endings / Reels: save prompts / Shorts: subscribe nudge)
+
+Render the adaptation table as a separate section on the canvas below the master storyboard.
+
+## Localization & Cultural Context
+
+When the target audience speaks a language other than English or is in a specific cultural region, the storyboard must adapt beyond simple translation. **Always ask the user** what language/region the video targets if not obvious from context.
+
+### Localization Checklist
+
+1. **Language & Slang** — Write the script in the audience's natural language, including local slang, colloquialisms, and informal speech patterns. UGC scripts must sound like how people actually talk in that region, not formal/textbook language.
+
+- Research local expressions: use `webSearch` for "[region] slang [year]" or "[region] TikTok popular phrases" to find current vernacular
+- Example: Dominican Republic → "mano," "vaina," "ta to," "dimelo" — not formal Castilian Spanish
+
+1. **Cultural Pain Points** — The problem/agitate phases must reference culturally specific pain points. What frustrates a young professional in Santo Domingo is different from what frustrates one in Austin.
+
+- Use `webSearch` for "[region] [industry] frustrations" or "[region] Reddit/forum complaints about [topic]" to find authentic pain points
+- Reference local platforms, banks, services, stores by name when relevant
+
+1. **Visual & Setting Cues** — Image prompts for shot generation should reflect the local environment:
+
+- Architecture, street scenes, typical home interiors for the region
+- Clothing, food, vehicles, and brands the local audience recognizes
+
+- Weather and lighting conditions typical of the region
+
+1. **Currency & Numbers** — Always use local currency (RD$, MXN$, R$, etc.) in text overlays and voiceover. Specific local amounts feel more authentic than converted USD figures.
+2. **Music & Audio** — Search for trending sounds specific to that region's TikTok/Reels ecosystem. Regional music trends vary significantly.
+
+- Use `webSearch` for "[country] TikTok trending sounds [month] [year]"
+
+1. **Humor & Tone** — Comedy styles vary by culture. What's funny in the US may not land in Latin America and vice versa:
+
+- Latin America: Self-deprecating humor, exaggeration, family/friend dynamics, "que vaina" moments
+- US: Sarcasm, absurdist, "relatable millennial/gen-z" humor
+
+- Europe: Dry wit, understatement
+- Always research: `webSearch` for "[region] comedy style TikTok" or "[region] viral funny videos [year]"
+
+### Language-Specific Script Format
+
+When writing non-English scripts, format as:
+
+```text
+
+ON-SCREEN TEXT: [text in target language]
+
+VO: [voiceover in target language]
+
+(Translation: [English translation for creator briefs sent to non-local teams])
+
+```
+
+Only include the English translation line if the user indicates the storyboard will be shared with people who don't speak the target language.
+
+## Content Series Planning
+
+When the product or topic supports it, **offer to plan a multi-video content series** instead of a single video. A series builds audience familiarity, improves algorithmic favor (watch-through from video to video), and lets you test angles systematically.
+
+### Series Structure
+
+A content series is 3-6 videos with a shared theme but different angles. Each video is a standalone storyboard but they share:
+
+- **Consistent creator/character** — same person, same setting, recognizable style
+- **Series hook** — a recurring opening pattern viewers learn to recognize ("Part X of things your bank doesn't want you to know")
+
+- **Progressive reveals** — each video teases the next ("but wait until you see what happened when I tried THIS...")
+- **Shared visual identity** — same text overlay style, color accents, caption format
+
+### Series Templates by Goal
+
+#### Product launch (3 videos)
+
+| \# | Video | Angle | Hook Style |
+
+|---|---|---|---|
+
+| 1 | The Problem | Pain-focused, no product mention | Contrarian or Negative Listicle |
+
+| 2 | The Discovery | "I found this thing..." — soft product intro | Unfinished Story |
+
+| 3 | The Result | Transformation proof, hard CTA | Number Hook or Before/After |
+
+##### Ongoing content (weekly, 4-6 videos)
+
+| \# | Video | Angle | Hook Style |
+
+|---|---|---|---|
+
+| 1 | Myth-buster | "Everyone thinks X but actually..." | Contrarian |
+
+| 2 | Quick tip | One actionable tip in <30s | Number Hook |
+
+| 3 | Story time | Personal experience with the pain point | Unfinished Story |
+
+| 4 | Behind the scenes | Show the product/process in action | Visual Interrupt |
+
+| 5 | User proof | Testimonial or user-submitted content | Social Proof |
+
+| 6 | Trend-jack | Adapt a trending format to your niche | Platform-specific |
+
+### Series Canvas Layout
+
+When planning a series, add a **Series Overview** section on the canvas above the individual storyboards:
+
+1. **Series title bar** — series name, total video count, posting cadence, target platform
+2. **Video cards** — one card per video in the series showing: video number, angle, hook type, estimated duration, and how it connects to the next video
+
+3. **Then the full storyboard** for whichever video the user wants to develop first
+
+Always ask: "Would you like me to plan this as a standalone video or as part of a content series?"
+
+## Creator Brief Export
+
+After building the storyboard on the canvas, **always generate a downloadable creator brief** as a clean markdown file. This is what gets sent to the person who will actually film the video.
+
+### Creator Brief Format
+
+Save to `attached_assets/creator_brief_[project_name].md` and present to the user using the file presentation tool.
+
+```markdown
+
+# Creator Brief: [Video Title]
+
+## Overview
+
+- **Product/Brand:** [name]
+- **Platform:** [target platforms]
+
+- **Duration:** [target length]
+- **Tone:** [funny / dramatic / authentic / etc.]
+
+- **Target Audience:** [who]
+
+## Shot List
+
+### Shot 1: HOOK (0:00-0:02)
+
+- **Camera:** [CU / MS / WS / POV]
+- **What to film:** [specific visual direction]
+
+- **On-screen text:** "[exact text]"
+- **Say this:** "[exact voiceover line]"
+
+- **Wardrobe/Setting:** [any specific requirements]
+- **Mood:** [the feeling this shot should convey]
+
+### Shot 2: ...
+
+[continue for all shots]
+
+## Filming Notes
+
+- [ ] Film on phone (no ring light, no DSLR)
+- [ ] Natural light, casual/real setting
+
+- [ ] Film each section (hook, problem, demo, CTA) as separate clips
+- [ ] Total filming time: ~[estimate] minutes
+
+- [ ] Wardrobe: [specific notes or "casual, everyday clothes"]
+- [ ] Props needed: [list any products, phones, items]
+
+## Caption & Hashtags
+
+- **Caption:** [suggested caption text]
+- **Hashtags:** [platform-appropriate hashtags]
+
+- **CTA in caption:** [e.g., "Link in bio for..." ]
+
+## A/B Variants
+
+Film these 3 alternative openings (same body, different hooks):
+
+1. **Hook A ([type]):** "[line]"
+2. **Hook B ([type]):** "[line]"
+
+3. **Hook C ([type]):** "[line]"
+
+## Platform-Specific Notes
+
+[Any re-cut or adaptation notes per platform]
+
+```
+
+## Trending Content Research
+
+Before writing any storyboard script, **always perform trending content research** for the user's niche and target platform. This grounds the script in what's actually working right now, not generic best practices.
+
+### Research Steps
+
+1. **Trending hooks in the niche:**
+
+- `webSearch("[industry] TikTok ad hooks [year]")`
+- `webSearch("[industry] viral video examples [year]")`
+
+- `webSearch("best [industry] UGC ads [quarter] [year]")`
+
+1. **Trending sounds and formats:**
+
+- `webSearch("[platform] trending sounds [month] [year]")`
+- `webSearch("[platform] trending formats [year]")`
+
+- For regional content: `webSearch("[country] [platform] trending sounds [month] [year]")`
+
+1. **Competitor analysis:**
+
+- `webSearch("[competitor brand] TikTok ads")`
+- `webSearch("[industry] top performing social ads [year]")`
+
+- Note what hooks, formats, and CTAs competitors are using
+
+1. **Pain point mining:**
+
+- `webSearch("[product category] complaints Reddit")`
+- `webSearch("[product category] reviews frustrations")`
+
+- `webSearch("[industry] [region] pain points")`
+
+### Research Output
+
+Summarize findings in a **Research Notes** section on the canvas (light-blue note) including:
+
+- 2-3 trending hooks spotted in the niche
+- Current trending sound/format recommendation
+
+- Top competitor ad observations
+- 3-5 authentic pain point phrases sourced from real users
+
+This research informs the script but is also visible to the user so they understand the strategic thinking behind each creative decision.
+
+## Industry Performance Benchmarks
+
+Include relevant benchmarks on the canvas when available. Use `webSearch` to find current data for the user's specific industry and region.
+
+### Common Benchmark Searches
+
+- `webSearch("[industry] UGC ad benchmarks [year]")` — CPM, CTR, conversion rates
+- `webSearch("[industry] TikTok ad performance [year]")` — platform-specific metrics
+
+- `webSearch("[region] social media ad costs [year]")` — regional CPM/CPC data
+- `webSearch("[industry] average video engagement rate [platform] [year]")`
+
+### Benchmark Display
+
+Add a **Performance Benchmarks** note (light-green) on the canvas with:
+
+- Industry average CPM for the target platform and region
+- Average CTR for UGC ads in this vertical
+
+- Expected view-through rate by video length
+- Conversion benchmarks if available (e.g., app installs, sign-ups)
+
+Flag these as reference points, not guarantees. Performance varies based on creative quality, targeting, and budget.
+
+## Visual Output — Always Use the Design Canvas
+
+**Always render the storyboard visually on the design canvas** using the `canvas` skill. Do not just output a text table — build a real, visual storyboard with a generated image for every shot.
+
+### Generated Shot Images
+
+Use the `media-generation` skill to **generate an image for every shot** in the storyboard. Each image should visualize exactly what the camera sees for that shot — match the shot type (CU, MS, WS, POV, etc.), framing, subject, and mood described in the storyboard. These are the storyboard frames, not placeholders.
+
+When the video targets a specific region or culture, image prompts **must** reflect the local environment, people, and visual context (see Localization section).
+
+### Canvas Layout
+
+Each shot is a vertical stack on the canvas, arranged left-to-right as a horizontal timeline:
+
+1. **Shot image** (`image` shape, 400w × 300h) — the generated frame for this shot
+2. **Metadata bar** (`geo` shape, 400w × 60h) — shot number, timestamp, and shot type. Color-coded by purpose: red/orange for hook shots, blue for value delivery, green for CTA.
+
+3. **Script/VO bar** (`geo` shape, 400w × 80h) — the voiceover line, on-screen text, or audio direction for this shot
+
+Use 440px horizontal spacing between shot columns. Add a **title shape** across the top with the video concept, platform, and target duration.
+
+For long storyboards (>8 shots), wrap to a second row.
+
+### Full Canvas Structure (top to bottom)
+
+1. **Title bar** — video concept, platform, duration, tone
+2. **Subtitle** — target audience, angle, script structure
+
+3. **Shot timeline** — images + metadata + scripts (left to right)
+4. **A/B Hook Variants** — 3 alternative openings
+
+5. **Platform Adaptations** — re-cut notes per target platform (if multi-platform)
+6. **Research Notes** — trending hooks, competitor observations (light-blue)
+
+7. **Performance Benchmarks** — industry metrics for reference (light-green)
+8. **Production Notes** — filming instructions (light-blue)
+
+9. **Audio Notes** — music, sound effects, VO direction (light-green)
+
+## Production Notes
+
+- **Cuts:** Every 1.5-3 sec on TikTok, every 3-5 sec on YouTube. Static shots >5s bleed viewers.
+- **Captions:** Always burned-in. Platform auto-captions are unreliable and can't be styled.
+
+- **Audio:** Trending sound at low volume under VO > original audio only. Use `webSearch` for "[platform] trending sounds this week" — shelf life is ~7-14 days.
+- **UGC aesthetic:** Phone camera, natural light, slightly messy background. Ring lights and DSLRs read as "ad" and tank trust. Authenticity converts 3-4× polished.
+
+- **Research:** `webSearch`for current top-performing ad hooks — e.g.`webSearch("[industry] TikTok ad hooks 2026")`or`webSearch("[industry] viral ad examples")`. The TikTok Creative Center (ads.tiktok.com/business/creativecenter) is a useful reference but requires direct browser interaction to filter; search for articles and breakdowns that cite its data.
+
+## A/B Testing Plan
+
+Always deliver 3 hook variants for the same body. Variables to test (change one at a time): Hook type (problem vs. outcome), Proof timing (early vs. late), CTA hardness (soft "check it out" vs. hard "buy now"). Run 7-14 days before picking a winner.
+
+## Deliverables Checklist
+
+Every storyboard project should deliver:
+
+- [ ] Visual storyboard on the canvas with generated images for every shot
+- [ ] 3 A/B hook variants
+
+- [ ] Platform adaptation table (if multi-platform)
+- [ ] Downloadable creator brief (markdown file)
+
+- [ ] Production and audio notes on canvas
+- [ ] Content series plan (if applicable, or offered as option)
+
+## Limitations
+
+- Produces scripts/storyboards only — no video rendering
+- Cannot access live trending sounds (suggest mood + search query)
+
+- Cannot measure retention curves
+- Performance benchmarks are reference data from web search, not guaranteed outcomes
+
+- Localization relies on web research — native speaker review is always recommended for non-English scripts

package/.local/secondary_skills/supplier-research/.fingerprint

@@ -0,0 +1 @@
+d87a13d6cf7f447348992e4223c0dd88