> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/darkzOGx/youtube-automation-agent/llms.txt
> Use this file to discover all available pages before exploring further.

# Script Writer Agent

> Explore how the Script Writer Agent creates engaging, structured video scripts optimized for viewer retention

## Overview

The **Script Writer Agent** transforms content strategies into complete, production-ready video scripts. It uses proven scriptwriting templates, pacing algorithms, and engagement techniques to create scripts optimized for maximum viewer retention.

<Card title="What It Does" icon="file-lines">
  The Script Writer Agent generates fully structured video scripts with hooks, introductions, main content, conclusions, and calls-to-action. Each script is tailored to the content type and optimized for the target audience.
</Card>

## Key Features

<CardGroup cols={2}>
  <Card title="Template Library" icon="layer-group">
    5 scriptwriting templates for different content types
  </Card>

  <Card title="Dynamic Pacing" icon="gauge">
    Adjusts pacing and timing based on content type
  </Card>

  <Card title="Engagement Hooks" icon="hook">
    Creates compelling opening hooks to capture attention
  </Card>

  <Card title="Duration Estimation" icon="clock">
    Calculates estimated video duration with precise timing
  </Card>
</CardGroup>

## Script Templates

The agent includes 5 specialized templates:

<Tabs>
  <Tab title="Tutorial">
    **Structure**: Hook → Introduction → Problem → Solution Steps → Demonstration → Recap → CTA

    **Best For**: How-to guides, educational content

    **Pacing**: Moderate (10-15 minutes optimal)

    ```javascript script-writer-agent.js theme={null}
    tutorial: {
      structure: ['hook', 'introduction', 'problem', 'solution_steps', 
                  'demonstration', 'recap', 'cta'],
      tone: 'educational',
      pacing: 'moderate'
    }
    ```
  </Tab>

  <Tab title="Explainer">
    **Structure**: Hook → Question → Background → Explanation → Examples → Implications → Summary → CTA

    **Best For**: Concept explanations, "What is" videos

    **Pacing**: Steady (5-10 minutes optimal)

    ```javascript script-writer-agent.js theme={null}
    explainer: {
      structure: ['hook', 'question', 'background', 'explanation', 
                  'examples', 'implications', 'summary', 'cta'],
      tone: 'informative',
      pacing: 'steady'
    }
    ```
  </Tab>

  <Tab title="List">
    **Structure**: Hook → Introduction → List Items → Bonus Item → Summary → CTA

    **Best For**: Top 10 lists, countdowns, rankings

    **Pacing**: Quick (8-15 minutes optimal)

    ```javascript script-writer-agent.js theme={null}
    list: {
      structure: ['hook', 'introduction', 'list_items', 
                  'bonus_item', 'summary', 'cta'],
      tone: 'engaging',
      pacing: 'quick'
    }
    ```
  </Tab>

  <Tab title="Review">
    **Structure**: Hook → Introduction → Overview → Pros → Cons → Comparison → Verdict → CTA

    **Best For**: Product reviews, comparisons

    **Pacing**: Detailed (8-12 minutes optimal)

    ```javascript script-writer-agent.js theme={null}
    review: {
      structure: ['hook', 'introduction', 'overview', 'pros', 
                  'cons', 'comparison', 'verdict', 'cta'],
      tone: 'analytical',
      pacing: 'detailed'
    }
    ```
  </Tab>

  <Tab title="Story">
    **Structure**: Hook → Setup → Conflict → Journey → Climax → Resolution → Lesson → CTA

    **Best For**: Personal stories, case studies

    **Pacing**: Dynamic (10-20 minutes optimal)

    ```javascript script-writer-agent.js theme={null}
    story: {
      structure: ['hook', 'setup', 'conflict', 'journey', 
                  'climax', 'resolution', 'lesson', 'cta'],
      tone: 'narrative',
      pacing: 'dynamic'
    }
    ```
  </Tab>
</Tabs>

## Core Methods

### generateScript()

Main method that orchestrates the entire script generation process.

```javascript script-writer-agent.js theme={null}
async generateScript(strategy) {
  this.logger.info(`Generating script for: ${strategy.topic}`);
  
  const template = this.templates[strategy.contentType.toLowerCase()] 
    || this.templates.explainer;
  
  // Generate script components
  const hook = await this.generateHook(strategy);
  const introduction = await this.generateIntroduction(strategy);
  const mainContent = await this.generateMainContent(strategy, template);
  const conclusion = await this.generateConclusion(strategy);
  const cta = await this.generateCTA(strategy);

  const script = {
    title: await this.generateTitle(strategy),
    hook,
    introduction,
    mainContent,
    conclusion,
    callToAction: cta,
    duration: this.estimateDuration(mainContent),
    tone: template.tone,
    pacing: template.pacing,
    keywords: strategy.keywords,
    metadata: {
      strategy: strategy,
      generatedAt: new Date().toISOString(),
      version: '1.0'
    }
  };

  script.fullScript = this.formatFullScript(script);
  await this.db.saveScript(script);
  
  return script;
}
```

### generateHook()

Creates attention-grabbing opening hooks using proven patterns.

```javascript script-writer-agent.js theme={null}
async generateHook(strategy) {
  const hooks = [
    {
      type: 'question',
      text: `Have you ever wondered ${this.generateQuestionAbout(strategy.topic)}?`
    },
    {
      type: 'statistic',
      text: `Did you know that ${this.generateStatistic(strategy.topic)}?`
    },
    {
      type: 'statement',
      text: `${strategy.topic} is about to change everything, and here's why...`
    },
    {
      type: 'challenge',
      text: `Most people think they understand ${strategy.topic}, but they're completely wrong.`
    },
    {
      type: 'promise',
      text: `In the next few minutes, you'll learn exactly how to master ${strategy.topic}.`
    }
  ];

  const selected = hooks[Math.floor(Math.random() * hooks.length)];
  
  return {
    type: selected.type,
    text: selected.text,
    duration: '0:00-0:05'
  };
}
```

<Note>
  The first 5 seconds are critical for retention. The agent uses proven hook patterns that have been shown to maximize viewer engagement.
</Note>

### generateSolutionSteps()

Creates detailed step-by-step content for tutorial videos.

```javascript script-writer-agent.js theme={null}
async generateSolutionSteps(strategy) {
  const steps = [];
  const numSteps = 3 + Math.floor(Math.random() * 3); // 3-5 steps
  
  for (let i = 1; i <= numSteps; i++) {
    steps.push({
      number: i,
      title: `Step ${i}: ${this.generateStepTitle(strategy.topic, i)}`,
      description: this.generateStepDescription(strategy.topic, i),
      tip: this.generateProTip(strategy.topic)
    });
  }
  
  return {
    type: 'solution_steps',
    title: 'The Solution',
    steps,
    duration: steps.length * 45 // 45 seconds per step
  };
}
```

### generateListItems()

Creates countdown-style list content optimized for engagement.

```javascript script-writer-agent.js theme={null}
async generateListItems(strategy) {
  const items = [];
  const numItems = 5 + Math.floor(Math.random() * 6); // 5-10 items
  
  for (let i = 1; i <= numItems; i++) {
    items.push({
      number: numItems - i + 1, // Countdown for engagement
      title: this.generateListItemTitle(strategy.topic, i),
      description: this.generateListItemDescription(strategy.topic),
      impact: this.generateImpactStatement()
    });
  }
  
  return {
    type: 'list_items',
    title: `Top ${numItems} Things About ${strategy.topic}`,
    items,
    duration: items.length * 30 // 30 seconds per item
  };
}
```

## Script Structure

Every generated script follows this structure:

<Steps>
  <Step title="Hook (5 seconds)">
    Attention-grabbing opening using one of 5 proven hook patterns
  </Step>

  <Step title="Introduction (15 seconds)">
    Greeting, topic introduction, value proposition, and credibility statement
  </Step>

  <Step title="Main Content (5-15 minutes)">
    Template-specific content structured for maximum engagement
  </Step>

  <Step title="Conclusion (30 seconds)">
    Recap of key points and final thought
  </Step>

  <Step title="Call-to-Action (15 seconds)">
    Subscribe, like, comment prompts and next video suggestion
  </Step>
</Steps>

## Duration Estimation

The agent calculates precise video duration:

```javascript script-writer-agent.js theme={null}
estimateDuration(mainContent) {
  const totalSeconds = mainContent.sections.reduce((total, section) => {
    return total + (section.duration || 60);
  }, 0);
  
  // Add hook, intro, conclusion, CTA
  const fullDuration = totalSeconds + 5 + 15 + 30 + 15;
  
  return this.formatDuration(fullDuration); // Returns "8:45" format
}
```

<CardGroup cols={4}>
  <Card title="Hook" icon="hook">
    5 seconds
  </Card>

  <Card title="Intro" icon="play">
    15 seconds
  </Card>

  <Card title="Content" icon="file-lines">
    Variable
  </Card>

  <Card title="CTA" icon="bullhorn">
    45 seconds
  </Card>
</CardGroup>

## Script Formatting

Scripts are formatted for easy reading and production:

```javascript script-writer-agent.js theme={null}
formatFullScript(script) {
  let fullScript = '';
  
  // Title
  fullScript += `TITLE: ${script.title}\n\n`;
  fullScript += '═'.repeat(50) + '\n\n';
  
  // Hook
  fullScript += `[${script.hook.duration}] HOOK\n`;
  fullScript += `${script.hook.text}\n\n`;
  
  // Introduction
  fullScript += `[${script.introduction.duration}] INTRODUCTION\n`;
  fullScript += `${script.introduction.greeting}\n`;
  fullScript += `${script.introduction.topicIntro}\n`;
  fullScript += `${script.introduction.valueProposition}\n\n`;
  
  // Main Content with timing markers...
  
  return fullScript;
}
```

### Example Output

```text theme={null}
TITLE: Ultimate Guide to AI Technology Trends (2026)

══════════════════════════════════════════════════

[0:00-0:05] HOOK
Have you ever wondered why AI technology is becoming so important?

[0:05-0:20] INTRODUCTION
Hey everyone, welcome back to the channel!
Today, we're diving deep into AI Technology Trends.
By the end of this video, you'll understand exactly what AI technology is and why it matters.
I've spent months researching this topic

[0:20-5:00] MAIN CONTENT
──────────────────────────────

[0:45] THE CHALLENGE
Many people struggle with AI Technology Trends.
The main issues are:
1. Lack of clear information
2. Complexity and confusion
3. Not knowing where to start

...
```

## Engagement Techniques

<AccordionGroup>
  <Accordion title="Pattern Interrupts">
    Strategic placement of questions, statistics, and surprises every 60-90 seconds to maintain attention
  </Accordion>

  <Accordion title="Value Stacking">
    Each section provides new value, keeping viewers engaged to learn more
  </Accordion>

  <Accordion title="Social Proof">
    Includes credibility statements and references to research/data
  </Accordion>

  <Accordion title="Storytelling Elements">
    Uses narrative techniques even in educational content
  </Accordion>
</AccordionGroup>

## Configuration Options

Customize script generation through environment variables:

```bash .env theme={null}
# Default video duration target (minutes)
DEFAULT_DURATION=10

# Script tone (educational|casual|professional)
DEFAULT_TONE=educational

# Include pro tips in tutorial steps
INCLUDE_PRO_TIPS=true

# Content density (low|medium|high)
CONTENT_DENSITY=medium
```

## Script Output Example

```json theme={null}
{
  "title": "Ultimate Guide to AI Technology Trends (2026)",
  "hook": {
    "type": "question",
    "text": "Have you ever wondered why AI technology is becoming so important?",
    "duration": "0:00-0:05"
  },
  "introduction": {
    "greeting": "Hey everyone, welcome back to the channel!",
    "topicIntro": "Today, we're diving deep into AI Technology Trends.",
    "valueProposition": "By the end of this video, you'll understand exactly what AI technology is and why it matters.",
    "credibility": "I've spent months researching this topic",
    "duration": "0:05-0:20"
  },
  "mainContent": {
    "sections": [
      {
        "type": "explanation",
        "title": "Deep Dive",
        "content": [...],
        "duration": 90
      }
    ],
    "totalDuration": 540
  },
  "duration": "8:45",
  "tone": "educational",
  "pacing": "steady"
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Match Template to Content">
    Let the agent select the template automatically based on content type for optimal results
  </Accordion>

  <Accordion title="Review Generated Scripts">
    While scripts are production-ready, reviewing them allows you to add personal touches and brand voice
  </Accordion>

  <Accordion title="Monitor Retention Metrics">
    Use analytics data to identify which script patterns work best for your audience
  </Accordion>

  <Accordion title="Adjust Duration Targets">
    Different niches have different optimal durations. Experiment to find what works for your channel
  </Accordion>
</AccordionGroup>

## Performance Metrics

<CardGroup cols={3}>
  <Card title="Generation Time" icon="clock">
    2-5 seconds
  </Card>

  <Card title="Average Duration" icon="stopwatch">
    8-12 minutes
  </Card>

  <Card title="Templates" icon="layer-group">
    5 specialized
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Thumbnail Designer" icon="image" href="/features/thumbnail-designer">
    See how thumbnails complement your scripts
  </Card>

  <Card title="SEO Optimizer" icon="chart-line" href="/features/seo-optimizer">
    Learn how scripts are optimized for search
  </Card>

  <Card title="Production Agent" icon="film">
    Discover how scripts become videos
  </Card>

  <Card title="API Reference" icon="code" href="/api/agents/script-writer">
    View complete API documentation
  </Card>
</CardGroup>