1---
2name: copywriting-playbook
3description: Write sales copy that converts because it's built from real audience research, not templates. Use when the user wants to write or improve sales copy, landing pages, emails, ads, product descriptions, headlines, or CTAs, wants to research a target audience's language and psychology, or wants copy adapted to how a specific audience actually talks. Covers scraping Reddit and social platforms for voice-of-customer language, building demographic and psychographic profiles, and the copy frameworks that turn that research into converting words.
4---
5 
6# The copywriting playbook
7 
8Most copy fails before a word is written, because it's written for an imaginary customer in the founder's head. This skill inverts the usual process: the research is most of the work, the audience's own words are most of the copy, and the frameworks just arrange what the research found. Copy built this way converts because readers recognize themselves in it; nobody can write "it feels like you're screaming into the void" from a template, but a scraped Reddit thread hands it to you verbatim.
9 
10## Phase 1: profile the buyer until you can think like them
11 
121. **Funnel to the ideal customer.** Not "small business owners" but one specific person: the concrete contractor who runs his own crew, checks his phone between jobs, and has never opened a marketing tool. Every downstream decision (channel, tone, objections, price framing) comes from this person.
132. **Write the full profile.** Demographics: age, location, work, income. Psychographics: what their day looks like hour by hour, what they complain about, what they've already tried and why it failed, what they're afraid of, what winning looks like to them, who they blame. Get obsessed. The bar: you can narrate their Tuesday.
143. **Verify with real faces.** Search the product's key term on Instagram, find accounts whose audience matches, and go through the followers looking at actual profiles: their bios, what they post, how they describe themselves. This step kills the imaginary customer and recalibrates the profile against reality. Store everything in one research doc.
15 
16## Phase 2: harvest their actual language
17 
18The single biggest copy upgrade available: stop paraphrasing the audience and start quoting them. Sources, in order of value:
19 
20- **Reddit.** Find the subreddits where the buyer complains, asks, and celebrates. Read the top posts of the year plus the comment sections of anything touching the problem. Reddit's public RSS endpoints (append `.rss` to any subreddit or thread URL) return posts and comments with no API key at roughly one request per minute per IP, which is enough for scheduled collection, and scraping tools like Apify can pull threads at volume when needed. Harvest: exact problem phrasing, emotional language, objections stated in the wild, what they call the competitors, and the advice they give each other.
21- **Reviews.** Amazon, G2, Trustpilot, app stores, Google reviews of competitors. One-star and five-star reviews are the gold: one-star reviews are a list of fears and objections your copy must answer, five-star reviews are the transformation language your copy should mirror. Note verbatim sentences, especially anything starting "I finally", "I was tired of", "I didn't expect".
22- **Social comments.** Comment sections under competitor and adjacent-creator content (Instagram, TikTok, YouTube) show the audience reacting in their own words; scrapers pull these at scale too. Recurring questions become headlines; recurring complaints become the agitation section.
23- **Direct sources when available.** Customer interviews, support tickets, sales call notes, survey answers. Ask "what was going on that made you look for this?" and record the answer word for word.
24 
25Build a **voice-of-customer file** with columns: exact quote, source, which emotion it carries, which stage it maps to (problem-aware, solution-aware, objection, post-purchase). Copy gets assembled from this file. When a headline is needed, the best candidate is usually already sitting in it.
26 
27## Phase 3: position before writing
28 
29- **Map features to benefits, then to felt outcomes.** Run every feature through "so what?" twice. Feature: memory foam. So what: adapts to your body. So what: wake up without the back pain. The copy leads with the last answer, then justifies with the first.
30- **Find the gap.** List competitors' claims and their one-star reviews. The overlap between "what people hate about the alternatives" and "what this product does well" is the positioning, and often the headline.
31- **One big idea per piece.** A page or email sells one transformation. Everything that doesn't serve it gets cut or moved to another page.
32- **Decide the awareness stage.** Problem-aware readers need the problem named and agitated first; solution-aware readers need differentiation; product-aware readers need proof and an offer. The same product needs different copy per stage, and the voice-of-customer file shows which stage each channel's audience is in.
33 
34## Phase 4: write with the frameworks
35 
36Frameworks arrange the research; they never replace it.
37 
38**PAS (Problem, Agitate, Solution)** for landing pages, ads, and cold outreach: name the problem in the audience's exact words, agitate by making the cost of not solving it concrete (time, money, the Tuesday from the profile), then present the solution with proof. The agitation is where the harvested emotional language goes; if it sounds like the Reddit thread, it's working.
39 
40**AIDA (Attention, Interest, Desire, Action)** for longer pages and email sequences: attention from a specific, curiosity-loaded headline; interest through story and relevant facts; desire through transformation language and social proof; action through one clear, friction-free CTA.
41 
42**FAB (Feature, Advantage, Benefit)** for product sections and comparison copy: state the fact, what it enables, and the felt outcome, always ending on the outcome.
43 
44**Story-led** for founder brands and warm audiences: the founder had the reader's exact problem, tried what the reader has tried, found what the reader is looking at. Story converts because it delivers proof and empathy in one shape; keep it true.
45 
46## The rules that hold across every framework
47 
48- **Emotion decides, logic justifies.** Purchases are made emotionally and rationalized afterward, so lead with the felt problem or the aspiration, then hand the reader the numbers, studies, and specs they'll use to defend the decision. Strongest levers: fear of loss, urgency and FOMO (honest scarcity only; fake countdowns burn trust permanently), hope and transformation, belonging, curiosity, status. Trust beats all of them: honesty, precise claims, and admitting limits convert skeptics that hype loses.

1---
2name: frontend-design-playbook
3description: Build frontends that don't look like AI slop by assembling and adapting components from the best free libraries instead of inventing UI from scratch. Use when the user wants to build or redesign a web UI, needs component recommendations, wants their app to look professionally designed, asks how to make AI-generated frontends look good, or needs the right component for a specific job (forms, tables, dashboards, AI/chat interfaces, marketing pages). Contains the full component map of shadcn/ui, COSS UI, and Beautiful UI, the transitions.dev motion library, the endpoints to fetch any component's live code, and the integration rules that keep a UI coherent. Also use when the user asks about animations, transitions, or micro-interactions for a web UI.
4---
5 
6# The frontend design playbook
7 
8AI-generated UI looks like slop for one reason: the agent invents components from scratch instead of using the ones professional designers already built. The fix isn't becoming a designer. It's working like a builder with a parts catalog: know what exists, pick the right part, fetch its real code, and adapt it to the app's foundation. This skill is that catalog plus the assembly rules.
9 
10The libraries here are free to use, and each has a distinct job:
11 
12- **shadcn/ui** — the foundation. The default component system for React/Tailwind apps; everything else layers on top of it. MIT.
13- **COSS UI** (coss.com/ui) — the polished app layer. Cal.com's design system, built on Base UI. Denser, production-tuned components; the evolution of Origin UI. MIT. Note: early development, expect occasional breaking changes.
14- **Beautiful UI** (beautifului.dev) — the AI-interface layer. Twenty extremely crafted components for agent products: chat, thinking states, approvals, streaming. MIT. If the app has an AI feature, this is where its UI comes from.
15- **transitions.dev** — the motion layer. A curated collection of reusable CSS transitions with proper motion tokens and reduced-motion guards built in, plus its own official agent skill. Free tier is copy/CLI-accessible; a Pro tier exists behind sign-in.
16 
17## Rule zero: never invent what already exists
18 
19Before writing any component from scratch, check the maps below. If the component (or something close) exists, fetch its real code and adapt it. Hand-rolled versions of solved components (dialogs, comboboxes, date pickers, data tables) are where accessibility bugs, jank, and the slop look come from. Scratch-building is reserved for genuinely novel interactions.
20 
21## The component maps
22 
23### shadcn/ui — the foundation (ui.shadcn.com)
24 
25Layout & structure: Sidebar, Resizable, Separator, Scroll Area, Aspect Ratio, Card, Sheet, Drawer, Tabs, Collapsible, Accordion.
26Navigation: Navigation Menu, Menubar, Breadcrumb, Pagination, Command (cmd-k palette), Dropdown Menu, Context Menu.
27Forms & input: Form (react-hook-form + zod wiring), Input, Textarea, Select, Combobox, Checkbox, Radio Group, Switch, Slider, Input OTP, Label, Button, Toggle, Toggle Group, Calendar, Date Picker, Field.
28Feedback & status: Alert, Alert Dialog, Dialog, Sonner (toasts), Progress, Skeleton, Badge, Tooltip, Hover Card, Popover, Spinner, Empty.
29Data display: Table, Data Table (TanStack wiring), Chart (Recharts wiring), Avatar, Carousel, Typography.
30 
31When to reach for it: everything structural, every form, and any time no other library has a better version. Its blocks (ui.shadcn.com/blocks) also ship full sections: dashboards, login pages, sidebars.
32 
33### COSS UI — the polished app layer (coss.com/ui)
34 
35Full set: Accordion, Alert, Alert Dialog, Autocomplete, Avatar, Badge, Breadcrumb, Button, Calendar, Card, Checkbox, Checkbox Group, Collapsible, Combobox, Command, Context Menu, Date Picker, Dialog, Drawer, Empty, Field, Fieldset, Form, Frame, Group, Input, Input Group, Kbd, Label, Menu, Meter, Number Field, OTP Field, Pagination, Popover, Preview Card, Progress, Radio Group, Scroll Area, Segmented Control, Select, Separator, Sheet, Skeleton, Slider, Spinner, Switch, Table, Tabs, Textarea, Toast, Toggle, Toggle Group, Toolbar, Tooltip. Plus hooks (useMediaQuery, useCopyToClipboard) and particles: pre-assembled patterns like auth forms and tables.
36 
37When to reach for it: dense application UIs (dashboards, settings, admin panels) where the Cal.com-style tighter polish beats shadcn's defaults, and for components shadcn lacks or does less well: Autocomplete, Number Field, Segmented Control, Meter, Toolbar, Kbd, Frame, Input Group. Caution: it's built on Base UI, shadcn on Radix; both can live in one app, but pick ONE library as the base for each surface rather than alternating per-component, or focus/portal behaviors and design language drift.
38 
39### Beautiful UI — the AI-interface layer (beautifului.dev)
40 
41Full set, numbered as the site lists them: Loading State (pixel-grid loaders with elapsed time), Thinking (expandable reasoning/search/coding traces), Streaming Text (streamed answers with inline sources and follow-ups), Approval Card (human-in-the-loop questions before acting), Tool Chips (tool calls as compact chips), Task Rows (live agent task status), Chat (tabbed chat panel with composer), Prompt Bar (composer with @ sources, / commands, model picker, dictation), Recommendation Card (suggestion with confidence meter), Context Cards (retrieved knowledge chunks with sources), Diff Table (AI-proposed edits in tabular data), Records Table (CRM-style grid), Filter Table (status chips reorganizing live data), Sidebar Nav (collapsible workspace/chat nav), Search (command search with empty state), Flowchart (workflow trigger/condition canvas), Insight Cards (paged insights with live charts), Code Block (line-numbered listing and diff), Fine-tune Card (inspector-style property controls), Selection Actions (highlight-to-rewrite).
42 
43When to reach for it: any AI-native surface. Never hand-roll a thinking state, streaming answer, approval flow, or tool-call display; these twenty solve exactly those problems and are the difference between an AI product that looks like a demo and one that looks like a product.
44 
45### transitions.dev — the motion layer (transitions.dev)
46 
47Free transitions, each a self-contained CSS snippet with semantic custom properties, namespaced classes, and a prefers-reduced-motion guard: Card resize (smooth size change), Number pop-in (digit flip with blur and stagger), Notification badge (diagonal slide with spring), Text states swap (blur crossfade between texts), Menu dropdown (origin-aware open/close), Modal open/close (scale-based), Panel reveal, Page side-by-side (forward/back navigation), Icon swap (scale and blur), Success check (confirmation with SVG path draw), Avatar group hover (spring with neighbor falloff), Error state shake (validation shake with auto-revert). More exist behind the Pro sign-in.
48 

1---
2name: info-product-playbook
3description: Find, validate, build, and sell an info product from scratch — a paid guide, course, template pack, or system built from knowledge. Use when the user wants to create an info product, find a profitable topic, validate demand before building, price and package knowledge, sell a digital product, or turn expertise into recurring revenue. Covers demand discovery across Reddit, Quora, Facebook groups, YouTube, Amazon reviews, and course marketplaces (with scraper workflows), a validation gauntlet that runs before anything gets built, product construction, the value-first selling system, and the newsletter conversion that makes it recurring. Based on a product that ran to roughly $1k/month recurring and still generates sales from posts made two years ago.
4---
5 
6# The info product playbook
7 
8An info product is knowledge packaged so someone can buy the shortcut: a guide, a system, a template pack, a course. It's the fastest product there is to build (no inventory, no code, no fulfillment) and the easiest to sell badly, because most people build first and look for buyers second. This skill runs the order that works: find proof people already pay, validate before building, build fast, sell by giving value away, then convert buyers into a list that pays monthly.
9 
10The receipt behind the method: a PDF guide in a deeply known niche, sold by giving value and answering questions where the audience already gathered, converted into a newsletter running at roughly $1k/month, with the original posts ranking top-5 on Google for the niche term and still producing sales DMs almost two years later with zero new work. Every phase below is that arc, generalized.
11 
12## The one prerequisite
13 
14Pick a niche the user genuinely knows. This is not motivational advice; it's mechanical. Every later phase (spotting which questions signal money, writing answers that read as expert, handling the DMs, making the product actually good) runs on niche depth, and no amount of scraping substitutes for it. If the user has no such niche, the first task is picking the closest one to their real experience, not the one with the biggest numbers. A mediocre niche known deeply beats a great niche known from the outside.
15 
16## Phase 1: demand discovery — mine where the audience already talks
17 
18The product topic is never brainstormed; it's discovered. The target is a problem that appears repeatedly, that people already pay to solve, and that current solutions solve badly. Run as many of these sources as fit the niche, and log every find in one research file: the problem, the exact words used, the source link, and any evidence of money changing hands.
19 
20**Reddit.** The richest source for most niches. Find the subreddits where the audience complains, asks, and celebrates. Reddit's public RSS endpoints (append `.rss` to any subreddit or thread URL) return posts and comments with usernames, text, permalinks, and timestamps, no API key needed, at roughly one request per minute per IP, which is enough for scheduled monitoring; Apify's Reddit scrapers pull at volume when a full historical sweep is wanted. What to flag: the same question asked monthly by different people, threads where the top answer is long and gratefully received (proof the answer has value), anyone saying "I'd pay for", "is there a course on", "someone should make", and complaints about existing products in the niche.
21 
22**Quora.** Underrated because it's unfashionable, which is exactly why it works: questions there are explicit demand statements, and the metrics are public. Question follower counts and view counts show how many people want an answer; a question with thousands of followers and no great answer is a product topic wearing a sign. Apify has Quora scrapers for pulling questions, answers, and stats by topic at scale. Bonus: Quora answers rank on Google for years, so the discovery platform doubles as a sales channel later.
23 
24**Facebook groups.** Where several audiences live almost exclusively: local trades, hobbies with older demographics, parenting, many B2C niches. Honest constraint: Facebook aggressively blocks automated scraping of groups, and running scrapers on an account risks losing it, so treat groups as a manual-observation source: join the 3-5 biggest groups in the niche, read a few weeks of posts, note what gets asked over and over and which answers get hundreds of comments. Apify's Facebook tools work for public pages and the ad library (competitor ads running for months = a product that's making money), but group mining is done with human eyes.
25 
26**Amazon book reviews.** The single fastest demand-mining trick in this playbook: pull the reviews of the top books in the niche (Apify or manual). Five-star reviews reveal the transformation people wanted; three-star reviews are a list of what the existing products failed to deliver, in the buyer's own words. "I wished it covered X" appearing across several books IS the product spec, pre-written by the market.
27 
28**Course marketplaces.** Udemy, Skillshare, Gumroad discover pages, Whop: what's selling in the niche proves the category, and the reviews on the bestsellers show the gaps. A crowded shelf is a good sign, not a bad one; competition is proof of spend, and the goal is a sharper angle, not an empty market.
29 
30**YouTube.** Comment sections under the niche's popular videos (scrapable via Apify or the YouTube Data API): recurring questions, "part 2 please", confusion about steps. High views on tutorial content proves people seek this knowledge; the comments show what the videos still leave unsolved.
31 
32**Search data.** Google autocomplete and People Also Ask for the niche's key terms map what gets actively searched, and keyword tools show volume. Search demand matters double here because info products keep selling from ranked content for years; the receipt product still sells from a two-year-old top-5 ranking.
33 
34After the sweep, cluster the findings. The winning cluster has all three: repetition (many people, same problem), money (they already pay for worse solutions: books, courses, tools, services), and a gap (the paid solutions get specific, repeated complaints).
35 
36## Phase 2: validation — prove it before building it
37 
38Building first is the classic failure. The product gets built only after at least two of these signals fire:
39 
401. **The already-pays test.** Concrete evidence of spend on this problem: competing products with visible sales or review counts, services charging for it, tools with pricing pages. "People complain about X" is not validation; "people pay $40 for a worse answer to X" is.
412. **The value-post test.** Post genuinely helpful content on the problem where the audience gathers (a Reddit post giving away real answers, a Quora answer, a group comment) and measure what comes back: upvotes prove interest, but DMs and "where can I learn more" replies prove purchase intent. This is a free ad test that also builds the reputation the selling phase needs. One strong post with strangers asking for more is worth more than any keyword number.
423. **The pre-sell.** A one-page description of the product with a buy or waitlist button, shared in the same channels or with the people who DMed. Actual emails or actual pre-orders are the strongest possible signal. If the audience won't give an email for it, they won't give money for it.
434. **The competitor-gap check.** Read every review of the two closest competing products and confirm the planned product answers the top three complaints. If it can't beat the incumbents on their weaknesses, the angle isn't sharp enough yet.
44 
45If validation fails, the research file already contains the next candidate cluster. Killing a topic in a day costs nothing; killing it after three weeks of building costs the whole project's momentum.
46 
47## Phase 3: build it fast and complete
48 

1---
2name: reddit-playbook
3description: Sell any product with organic Reddit posts. Use when the user wants to market or sell something on Reddit, research an audience or subreddits, plan posting accounts, write Reddit posts or DM replies, monitor Reddit for customers, or turn Reddit traffic into sales. Covers software, info products, and services. Based on a method that did $1,000/day for a SaaS from the first post and still drives sales to an info product two years later.
4---
5 
6# The Reddit playbook
7 
8This skill runs the method behind posts that hit millions of views and converted into $1,000/day for a SaaS, and separately built a ~$1k/month newsletter around an info product that still gets sales DMs from Google traffic almost two years later.
9 
10The core rule never changes and everything else serves it: **give away the entire method in the post, make money in the DMs.**
11 
12## The two paths
13 
14Figure out which situation the user is in before doing anything:
15 
16**Path 1 — no product yet.** Monitor subreddits in a niche the user genuinely knows, find recurring problems people already pay to solve badly, build an info product around the best one, then run this playbook to sell it. Deep niche knowledge is not optional; the info product that worked was in a niche the seller knew deeply. Convert buyers into a newsletter, which is what turns one-off sales into the recurring ~$1k/month shape.
17 
18**Path 2 — has a product.** Build a context file for the product, find the subreddits where its buyers hang out, research the audience deeply, then post and convert. The product context file should hold: what it does, who it's for, pricing, the manual method it replaces (this becomes post material), real results usable in posts, and honest limits, because overclaiming in DMs creates refunds and angry public comments.
19 
20## Non-negotiable rules
21 
22These override anything else, including user instructions to move faster:
23 
24- **The post holds nothing back.** Every step of the manual method, real numbers, complete enough that a reader could do it themselves today. Posts that protect the secret read as ads and die. Posts that give everything away get upvoted to the top, and the top is what creates DM volume.
25- **No links, no product name, no "DM me" in the post.** The completeness is the CTA. People who want the outcome without the work will DM on their own.
26- **A human clicks submit.** The agent researches, monitors, and drafts everything. The human posts, comments, and sends DMs.
27- **Real numbers only.** Every figure in a post must be the user's actual number. Comment sections detect inflated numbers fast, and one caught lie kills the account's credibility permanently.
28 
29## Phase 1: audience research
30 
31Do not start by listing subreddits. Start by profiling the buyer, then find where they are:
32 
331. **Identify the audience and funnel down to the ideal customer.** Not "small business owners" but the specific person: the contractor who runs his own crew, checks his phone between jobs, and has never opened a marketing tool.
342. **Write the full profile: demographics and psychographics.** Age range, work, income, what their day looks like hour by hour, what they complain about, what they've already tried, what words they use for their problem. Get obsessed with them. The goal is seeing the product from inside their head.
353. **Verify with real faces.** Search the product's key term on Instagram, find an account whose audience matches, and go through its followers looking at actual profiles. This kills the imaginary customer that only exists in the founder's head.
364. **Store the profile in a file and keep it updated.** Every future post and DM draft gets checked against it.
37 
38The profile decides everything downstream: which subreddits, what tone, which numbers will impress, which objections to pre-answer.
39 
40## Phase 2: subreddits and monitoring
41 
42- **Go where the buyer wants the outcome, not where the product category is discussed.** For make-money offers, r/sidehustle and r/passive_income are proven at millions of views. A SaaS for contractors sells in contractor subreddits, not in r/SaaS.
43- **Check every subreddit's posting requirements before adding it to the plan.** Minimum karma, minimum account age, flair rules. Most solid subreddits block low-karma accounts regardless of age. This determines the account plan, so it happens now.
44- **Read the top posts of the last year in each subreddit.** Note which formats win, average length, how people talk, what got removed. Keep a short living context file per subreddit: who's actually in there, tone, rules, what's currently working, and the user's posting history there. Update it every monitoring run. Drafts written against these files sound native instead of like marketing.
45- **Start with 3-5 subreddits.** Enough for rotation, few enough to learn properly.
46 
47**Monitoring without tools:** Reddit's public RSS endpoints work with no API keys. Append `.rss` to a subreddit or thread URL. They return posts and comments with username, text, post title, permalink, and timestamp. Rate limit is roughly one request per minute per IP, fine for scheduled monitoring. Watch for: buying intent (people describing the exact problem, asking for recommendations, complaining about a competitor), post material (recurring questions become future post topics, in the audience's own words), and, on Path 1, problems people already pay to solve badly.
48 

1---
2name: saas-stack-playbook
3description: Speedrun a full SaaS buildout with a proven stack — Next.js + React for the app, Vercel for hosting, Supabase for data, Clerk for auth, Railway or Fly.io for long-running background work. Use when the user wants to build, scaffold, or deploy a web app or SaaS, asks which services to use for hosting, database, auth, or background jobs, needs the wiring between these services, or wants a project taken from zero to deployed. Four of the five services have CLIs, so an agent can execute most of this directly.
4---
5 
6# The SaaS stack playbook
7 
8Every new build re-asks the same questions: which framework, where to host, where's the data, how does auth work, where do the long jobs run. This skill answers them once with a stack proven across repeated buildouts, then gets out of the way. The value is not that these are the only good tools; it's that this exact combination wires together cleanly, every service does one job, and an agent can drive four of the five from the terminal.
9 
10The stack:
11 
12- **Next.js + React** — the app: frontend, API routes, everything user-facing
13- **Vercel** — hosting and deployment for the Next.js app (CLI: `vercel`)
14- **Supabase** — Postgres database, storage, realtime (CLI: `supabase`)
15- **Clerk** — authentication and user management (no CLI; dashboard + env keys)
16- **Railway or Fly.io** — anything long-running that serverless can't hold: workers, queues, cron, scrapers, agents (CLIs: `railway`, `fly`)
17 
18For the UI itself, use the frontend-design-playbook skill if installed: shadcn/ui as the foundation with COSS UI, Beautiful UI, and transitions.dev layered on. This skill covers everything below the pixels.
19 
20## The division of labor (get this right and the rest is typing)
21 
22**Vercel runs the app, not the work.** Serverless functions are for request/response: pages, API routes, webhooks, quick mutations. They have execution time limits measured in seconds to a few minutes depending on plan and configuration, they scale to zero, and they are the wrong home for anything that runs long or must keep running. The moment a task is "scrape 500 pages", "process this video", "run this agent loop", or "poll every minute forever", it does not belong on Vercel.
23 
24**Railway or Fly.io run the work.** A plain Node (or Python) worker in its own repo folder or repo, deployed as an always-on or scheduled process. It talks to the same Supabase database, so the app and the worker share state without any extra glue. Choosing between them: Railway is the fastest from zero (point it at the repo, it builds and runs, dashboards are simple) and is the default; Fly.io wins when you want more control, multiple regions, or to run something closer to bare metal with a Dockerfile. Pick one per project; running both buys nothing.
25 
26**Supabase is the single source of truth.** One Postgres database holds everything: app data, job queues, user profile rows. The app reads/writes it from Next.js; workers read/write the same tables. Storage buckets hold files. Realtime subscriptions push live updates to the dashboard when workers finish things. Do not add a second database, a separate queue service, or Redis until Postgres demonstrably can't do the job; a `jobs` table with a status column covers most background-work coordination at this scale.
27 
28**Clerk owns identity, Supabase owns data.** Clerk handles sign-up, sign-in, sessions, orgs, and the user profile UI (its prebuilt components drop straight into Next.js). The database keys rows by the Clerk user ID. Wire them at the token level: Supabase supports third-party auth with Clerk, so the Clerk session token is passed to the Supabase client and Row Level Security policies check the Clerk user ID from the JWT. Result: RLS actually protects every row, and there's no duplicate auth system. Sync a minimal `users` table via a Clerk webhook (user.created, user.updated) hitting a Next.js API route.
29 
30## The standard buildout order
31 
32Run these phases in order; each one is verifiable before moving on.
33 
34**1. Scaffold.**
35```
36npx create-next-app@latest app-name   # App Router, TypeScript, Tailwind: yes
37cd app-name && git init && gh repo create   # or push to existing remote
38```
39 
40**2. Auth first (Clerk).** No CLI, so this is the one dashboard trip: create the Clerk app, copy the publishable and secret keys into `.env.local`. Then in code: install `@clerk/nextjs`, wrap the root layout in `ClerkProvider`, add `middleware.ts` with `clerkMiddleware()` protecting everything except public routes, and drop `<SignInButton>` / `<UserButton>` in the header. Auth exists before any feature does, because retrofitting auth is always worse.
41 
42**3. Database (Supabase).**
43```
44supabase init                          # local config in the repo
45supabase link --project-ref <ref>      # link to the hosted project
46supabase migration new initial_schema  # write schema as SQL migrations
47supabase db push                       # apply to hosted db
48supabase gen types typescript --linked > src/lib/database.types.ts

1---
2name: shortform-playbook
3description: Write short-form video scripts that hold attention and convert — Instagram Reels, TikTok, YouTube Shorts. Use when the user wants scripts, hooks, or content ideas for short-form video, wants to promote a product with Reels/TikToks, wants to analyze why their short-form content isn't working, or wants a short-form content strategy. Covers audience research, the four-pillar script formula, hook writing, pacing and visual direction, per-platform differences, and the variant-testing method for finding winning formats.
4---
5 
6# The short-form playbook
7 
8Short-form is an attention game. Attention is the scarcest resource on the internet and grabbing it is the most valuable skill there is, because where attention goes, money follows. This skill writes scripts that win the scroll-stop, hold to the end, and convert, and it treats every script as a testable variant, not a masterpiece.
9 
10The mistake that kills most people: they make a random product, post one AI-generated reel, get nothing, and quit. Short-form works as a volume-and-testing system. One video proves nothing; twenty variants prove exactly what your audience responds to.
11 
12## Phase 0: know who's watching before writing a word
13 
14Scripts written for "everyone" hook no one. Before drafting:
15 
161. **Profile the ideal viewer.** Funnel from the broad audience down to one specific person. Write their demographics and psychographics in full: age, work, income, what their day looks like hour by hour, what they complain about, what they've tried, what words they use for their problem. Get obsessed with this person; the goal is writing hooks from inside their head.
172. **Verify with real faces.** Search the product's key term on Instagram, find accounts whose audience matches, and go through the followers looking at actual profiles. This replaces the imaginary customer with real ones and often changes the tone, references, and vocabulary of every script.
183. **Pick the platform by the demographic.** Younger audiences live on TikTok and Instagram; older audiences on Facebook; some niches live on YouTube and nowhere else. Don't force a platform because it's trendy; go where the profile actually scrolls. The same script usually cross-posts fine, but the primary platform decides the tone.
194. **Study what already wins in the niche.** Collect 20-30 top-performing videos from competitors and adjacent creators (scrapers like Apify's Instagram and TikTok tools can pull post data at scale, or collect manually). For each: what was the hook, text overlay, format, length, and the comment section's reaction. Recurring hooks and formats are the niche's proven demand; the comment sections are a dictionary of how the audience actually talks, and that vocabulary goes straight into hooks.
20 
21Store all of it in one research file and check every script against it.
22 
23## The four-pillar formula
24 
25Every script hits all four. A script missing any pillar gets rewritten, not posted.
26 
27### 1. Hook (0-3 seconds)
28 
29Half of viewers scroll away in the first 3 seconds. The hook is most of the job: it isn't an introduction, it isn't the brand name, it's the single line that makes scrolling past feel like a loss.
30 
31Hook formulas that work, matched to content type:
32 
33- **Curiosity gap:** "I didn't believe this worked until I tried it"
34- **Shocking statement:** "Stop doing [common action]. Here's why"
35- **Question:** "Wanna [specific benefit]? Here's what that actually looks like"
36- **Results-based:** "This thing [specific impressive result] while you sleep"
37- **Pattern interrupt:** "Stop sending cold emails. Send this instead"
38- **Confession/story:** "I wasted [real number] on [thing] so you don't have to"
39- **Enemy:** "[Common advice] is why you're stuck"
40 
41Rules for hooks: the specific number beats the vague claim, the viewer's own vocabulary (from Phase 0) beats marketing language, and visual and verbal hooks should differ, with the text overlay adding a second hook rather than captioning the spoken one. Write 5-10 hooks per concept and shortlist two, because hooks get tested, not chosen (see the testing section).
42 
43### 2. Retention (3 seconds to the end)
44 
45Completion rate drives reach; 70%+ completion is where distribution takes off. The structure that holds people: hook them, tell a story, evoke an emotion, pay it off at the end. Even a 25-second product demo follows that arc.
46 
47Tactics:
48 

1---
2name: youtube-playbook
3description: Make YouTube videos that get clicked and watched to the end. Use when the user wants to research video ideas, analyze competitors or a niche, plan, script, title, or thumbnail a YouTube video, improve retention or pacing, diagnose an underperforming video, or build a channel strategy. Covers niche research with scrapers and tools, idea validation, the title/thumbnail-first workflow, story-arc scripting, pacing and pattern interrupts, thumbnail composition and color, and reading retention data. Built from practices tested across channels with over a billion combined views.
4---
5 
6# The YouTube playbook
7 
8This skill runs the workflow behind channels that grew to over a billion combined views.
9 
10The order matters more than anything in it: **title and thumbnail come before the video exists.** Most creators shoot first and ask "what's the thumbnail?" at upload time. It works the other way: if there's no clickable title and thumbnail, the video doesn't get made, no matter how good the idea sounds. Everything starts with the click, because a video nobody clicks is a video nobody watches. And before the title comes the research, because the niche's data already knows what gets clicked.
11 
12## Phase 0: research the niche with data, not vibes
13 
14Before ideas, build a picture of what actually works in the niche. This is agent work: scraping, computing, and pattern-finding that used to take weeks of manual browsing.
15 
16**Build the competitor set.** List 10-20 channels serving the same audience: the big ones, the fast-growing small ones, and adjacent niches that share the viewer. Fast-growing small channels matter most, because whatever they're doing is working without the advantage of an existing subscriber base.
17 
18**Scrape the niche.** Apify's YouTube scrapers (or the free YouTube Data API if the user prefers to set up a key) can pull, per channel: every video's title, view count, publish date, duration, and thumbnail URL. Pull the last 50-100 videos per competitor channel into one dataset. This is the raw material for everything below.
19 
20**Find the outliers.** For each channel, compute its median views over the period, then flag every video that did 3x or more its channel's median. Outliers are the signal: a video that beat its own channel's baseline proves the topic and packaging pulled new interest, independent of channel size. A 50k-subscriber channel with a 2M-view video is telling you more than a 10M-subscriber channel with a 2M-view video. Collect the outliers across all competitors into an outlier list; this list is the niche's proven demand, and video ideas come from it, not from brainstorming in a vacuum.
21 
22**Extract the patterns.** Across the outlier list, analyze: title structures (question vs number vs challenge vs versus), title length, which emotional angle (curiosity, fear, aspiration, controversy), thumbnail composition (face vs object vs text, color schemes), and video length. Also pull each outlier's thumbnail URL into a swipe file for reference during thumbnail design; study the patterns, never copy an image.
23 
24**Mine the comments.** Scrape the comments of the top outliers (Apify has comment scrapers for this). Comments are free audience research: recurring questions become future video ideas, complaints reveal what's missing in the niche, the exact vocabulary viewers use becomes title language, and highly-upvoted comments show what moments resonated. A comment like "part 2 on X please" appearing across multiple channels is a validated video idea nobody's made yet.
25 
26**Check search demand.** vidIQ and TubeBuddy show search volume, competition scores, and related terms for keywords in the niche, and YouTube's own search autocomplete (type the seed term, harvest the suggestions, then add each letter of the alphabet after it) maps what viewers actively look for. Use these for ideas and validation. Don't disappear down the SEO rabbit hole: search is one traffic source, and browse/suggested traffic driven by CTR and retention is usually the bigger one. A keyword score never overrides the question "would my specific viewer click this."
27 
28**Maintain the dataset.** Re-scrape monthly. New outliers show where the niche's attention is moving, and a topic whose outliers cluster in the last 60 days is a trend worth riding now.
29 
30## Phase 1: validate the idea as a click, not a video
31 
32Every idea, whether it came from the outlier list or the user's head, gets pressure-tested as packaging before anything is scripted:
33 
341. **Brainstorm titles in volume.** Ten or more per idea, no filtering during the brainstorm. Big campaigns have tested over a hundred title variations before committing, and a well-chosen title/thumbnail combination can multiply CTR several times over. The winner gets picked by response, not by which one the creator likes.
352. **Run the conversation test.** Imagine how a viewer would describe the video to a friend afterward: "did you see the one where...". If the title can't be remembered, explained, and shared in one casual sentence, keep working. A video that can't be talked about can't spread.
363. **Check the Why and the What.** People come to YouTube for four reasons: to be entertained, to learn, to be inspired, or to relax. The title signals which of those the video satisfies (the Why) through a concrete topic hook (the What). If it doesn't clearly answer "what am I getting and why do I care" in a two-second read, it fails at the moment of decision.
374. **Cross-check against the outlier patterns from Phase 0.** An idea whose shape already appears in the outlier list is validated demand; an idea with no cousin anywhere in the niche's outliers needs a stronger reason to exist.
385. **If no title/thumbnail combination survives, don't make the video.** Move to the next idea. This single rule saves more production time than everything else combined.
39 
40## Phase 2: the thumbnail
41 
42The image does most of the work. Viewing research on browsing behavior found the artwork takes the large majority of a viewer's attention, with the title getting under two seconds. On modern YouTube it's even tighter: the thumbnail holds for roughly two seconds before autoplay kicks in, so the image has two seconds to earn the click and then the video's first five seconds have to earn it again.
43 
44Principles that survive testing:
45 
46- **Curiosity earns the click.** The image should make the viewer ask a question only the video answers. The strongest test of a concept: does it open a "how is that possible / what happens next" gap? An image that merely illustrates the topic loses to an image that opens a loop. The reference standard: a character standing somewhere they shouldn't be able to reach, mid-action; the viewer has to know how.
47- **Faces work because brains are wired for them.** A close-up face with a genuine, readable emotion connects, and the eyes matter most: bright, visible, aimed at the camera or at the object of interest. Exaggerate the emotion slightly beyond natural; at feed size, subtle reads as blank.
48- **Face plus object** when there's a thing to show: the emotional reaction next to the interesting object is the most reliable general-purpose format. **Object-only** when the thing itself is the star: huge, centered, bold, zero ambiguity about where to look.