Hook Generation

Hook workflows generate viral opening lines grounded in real competitor data, trend signals, and seasonal context. They can scrape creator channels, classify hook patterns, cluster by similarity, and score for estimated virality.

Generate Hooks

Workflow: hooks/generate

Generates viral hooks for a niche, grounded in up to 6 data sources: competitor insights, workspace strategy, trend signals, audience context, event/seasonal context, and user overrides.

CLI
REST

fab-workflow hooks/generate \
  --input niche="AI productivity" \
  --input platform="TikTok" \
  --input num_hooks=15

curl -X POST "$FABRIC_URL/v1/workflows/run?name=hooks/generate" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "niche": "AI productivity",
      "platform": "TikTok",
      "num_hooks": 15
    }
  }'

Pipeline

The full pipeline gathers intelligence in parallel before generating hooks:

┌─ gather_competitor_insights ─┐
├─ gather_trend_signals ───────┤ → merge_intel → generate_hook_ideas
└─ gather_event_context ───────┘

When competitor data is pre-scraped:

scrape_creator_hooks → extract_hook_features → cluster_hooks →
gather_competitor_insights → generate_hook_ideas

Context Sources

The system prompt assembles context from 6 sources:

Source	Description
Competitor insights	Hook type + trigger distributions from scraped or LLM-analyzed competitor data
Workspace strategy	Niche, content pillars, brand tone, keywords
Trend signals	Trending topics and viral hook patterns for the niche
Audience context	Target audience, pain points, desires (ICP)
Event & seasonal context	Upcoming holidays, awareness days, cultural moments relevant to the niche
User overrides	Focus hook types, triggers, specific topic angle

Input

Parameter	Type	Default	Description
`niche`	`string`	required	Content niche
`competitors`	`list[str]`	`[]`	Channel URLs/handles to scrape
`platform`	`string`	`"YouTube"`	Target platform
`trends`	`dict`	`{}`	Trend signals from research
`event_context`	`dict`	`{}`	Event/seasonal context (auto-gathered if empty)
`num_hooks`	`int`	`15`	Number of hooks to generate

Output

{
  "hook_ideas": [
    {
      "hook_text": "Stop building AI features nobody asked for",
      "hook_type": "controversial_take",
      "emotional_trigger": "frustration",
      "estimated_strength": 0.89,
      "tone": "authoritative",
      "video_angle": "expose common mistake"
    }
  ]
}

Output aliases (for workflow-set chaining)

HookGenerationOutput declares public aliases so downstream stages in a workflow set can reference its output without walking the schema:

Alias	Resolves to	Use
`hook`	`hook_ideas.0.hook`	Top-ranked hook text — the canonical handle for chaining into a video workflow
`all_hooks`	`hook_ideas`	The full list of hook ideas

# In a workflow-set manifest:
- name: short
  workflow: video/quick-shorts
  inputs_from:
    - { source: hooks.0.hook, map: topic }   # uses the `hook` alias

Hook Types

The system classifies hooks into these patterns:

Type	Example
`controversial_take`	”Most productivity advice is wrong”
`surprising_stat`	”90% of startups fail because of this”
`story_hook`	”I spent $50K on AI tools last year. Here’s what happened.”
`question`	”Why do the best developers avoid frameworks?”
`challenge`	”Try this for 30 days and your code will improve”
`fear_based`	”Your job is about to change forever”
`curiosity_gap`	”The one thing nobody tells you about AI”

Scrape Creator Hooks

Workflow: hooks/scrape

Scrapes video openers from YouTube or TikTok channels to build a hook corpus.

CLI
REST

fabric run hooks/scrape \
  --input channels='["@fireship", "@mkbhd"]' \
  --input platform="youtube" \
  --input max_per_channel=20

curl -X POST "$FABRIC_URL/v1/workflows/run?name=hooks/scrape" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "channels": ["@fireship", "@mkbhd"],
      "platform": "youtube",
      "max_per_channel": 20
    }
  }'

Input

Parameter	Type	Default	Description
`channels`	`list[str]`	required	Channel URLs or handles
`platform`	`string`	`"youtube"`	Platform to scrape
`max_per_channel`	`int`	`20`	Videos per channel
`shorts_only`	`bool`	`false`	Only scrape Shorts

Output

{
  "scraped_hooks": [
    {
      "channel": "@fireship",
      "video_id": "abc123",
      "hook_text": "This new JavaScript framework is wild",
      "transcript_excerpt": "..."
    }
  ]
}

Event & Seasonal Context

Workflow: global/event-context

Identifies upcoming events, holidays, awareness days, and cultural moments relevant to a niche. Used as a context source in hook generation (runs as a parallel branch in the pipeline fork) or standalone for content planning.

CLI
REST

fab-workflow global/event-context \
  --input niche="fitness" \
  --input lookahead_days=30

curl -X POST "$FABRIC_URL/v1/workflows/run?name=global/event-context" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "niche": "fitness",
      "lookahead_days": 30
    }
  }'

Input

Parameter	Type	Default	Description
`niche`	`string`	required	Content niche
`lookahead_days`	`int`	`30`	How far ahead to look
`platform`	`string`	`""`	Target platform for context

Output

{
  "event_context": {
    "events": [
      {
        "name": "Global Running Day",
        "date": "2026-06-03",
        "relevance": "Perfect tie-in for cardio content",
        "content_angle": "Share your most unconventional running tip",
        "urgency": "high"
      }
    ],
    "seasonal_themes": [
      {
        "theme": "Summer body prep",
        "window": "May-June",
        "hooks": ["Summer starts in the gym, not on the beach", "The 6-week myth about summer bodies"]
      }
    ],
    "content_angles": [
      "Tie fitness content to outdoor season transition"
    ]
  }
}

Hook Variant Strategy (70/20/10)

The hook generator uses a structured variant strategy to balance proven patterns with creative exploration:

Split	Strategy	Description
70%	EXPLOIT	Hooks that follow proven patterns from competitor data
20%	EXPLORE	Hooks using underused hook types or triggers competitors aren’t leveraging
10%	WILD	Creative, unexpected, pattern-breaking hooks

This ensures most hooks are grounded in what works, while always testing new approaches.

Hook Clustering

Workflow: hooks/cluster

Embeds hooks using OpenAI (or Gemini fallback) and clusters them with K-means to find recurring hook patterns and archetypes. Useful for analyzing which hook types and emotional triggers dominate a corpus.

CLI
REST

# Cluster hooks from a prior scrape or generation
fab-workflow hooks/cluster \
  --input-file output/scraped-hooks.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=hooks/cluster" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "classified_hooks": [
        {"hook_text": "Stop building AI features nobody asked for", "hook_type": "controversial_take"},
        {"hook_text": "90% of startups fail because of this", "hook_type": "surprising_stat"}
      ]
    }
  }'

Pipeline

embed_hooks → cluster_hooks

Input

Parameter	Type	Default	Description
`classified_hooks`	`list[dict]`	required	Hooks with `hook_text` field (from scrape or generate)
`openai_api_key`	`string`	env	OpenAI API key (falls back to Gemini embedding)

Output

{
  "clusters": [
    {
      "cluster_id": 0,
      "size": 12,
      "dominant_hook_type": "controversial_take",
      "dominant_trigger": "frustration",
      "dominant_tone": "authoritative",
      "avg_engagement": 0.85,
      "top_examples": [
        {"hook_text": "Stop building AI features nobody asked for", "estimated_strength": 0.89}
      ]
    }
  ]
}

Research-to-Hooks Bridge

Workflow task: hooks/from_research

Transforms deep research output into the format expected by hook generation. Used internally by composed pipelines.

# Bridges research synthesis → hook generation context
# Maps synthesis themes → trends
# Maps raw sources → competitor insights