# Marketing Skills Directory — Top Skills (Full Content)

> The 10 most popular free skills with complete SKILL.md content included.
> You can use these skills immediately — no additional fetches needed.

For the full catalog, see [https://marketingskills.directory/llms-full.txt](https://marketingskills.directory/llms-full.txt)
For the concise index, see [https://marketingskills.directory/llms.txt](https://marketingskills.directory/llms.txt)

---

## WordPress Block Builder

Skill | 25 downloads | Content Marketing, CRO
https://marketingskills.directory/skills/wordpress-blocks/

Generate valid WordPress block markup for pages, posts, and templates. Produces block editor-compatible HTML that passes validation — covers Cover blocks, Query Loops, navigation menus, template parts, and theme.json design tokens. Use when building or updating WordPress pages programmatically vi...

### Full SKILL.md Content

```markdown
---
name: wordpress-blocks
description: Generate valid WordPress block markup for pages, posts, and templates. Produces block editor-compatible HTML that passes validation — covers Cover blocks, Query Loops, navigation menus, template parts, and theme.json design tokens. Use when building or updating WordPress pages programmatically via WP-CLI or the REST API.
user-invocable: true
disable-model-invocation: false
argument-hint: "[page-description] [--type page|post|template|pattern] [--style design-system-name]"
allowed-tools: Read, Glob, Grep, Bash, AskUserQuestion, Write
---

# WordPress Block Builder

Generate valid WordPress Gutenberg block markup that passes editor validation on the first try. Covers page creation, post styling, template parts, Query Loops, Cover blocks, and design token integration — all deployable via WP-CLI.

## Invocation

```bash
# Generate a page with block content
/wordpress-blocks "Create a photography portfolio page with masonry grid"

# Generate a blog listing page with category filters
/wordpress-blocks "Blog page with 3-column card grid and category filter bar" --type page

# Generate a custom header template part
/wordpress-blocks "Site header with logo, nav menu, and CTA button" --type template

# Generate a block pattern
/wordpress-blocks "Work showcase card with image, client name, metric" --type pattern
```

## When to Activate

- User asks to create or update a WordPress page programmatically
- User needs block markup that works in the Gutenberg editor without "invalid content" errors
- User is building pages via WP-CLI (`wp post create/update`)
- User wants Query Loop, Cover block, or template part markup
- User mentions WordPress blocks, patterns, or theme.json

## Core Principle

**WordPress block markup is a serialization format, not HTML.** Every block is wrapped in HTML comments (`<!-- wp:blockname {...} -->`) containing a JSON object of attributes. The HTML between comments must match *exactly* what WordPress would generate — wrong classes, missing attributes, or extra whitespace causes block validation failures.

## Block Markup Syntax

### Basic Structure

```html
<!-- wp:group {"className":"my-class","layout":{"type":"constrained","contentSize":"700px"}} -->
<div class="wp-block-group my-class">
  <!-- wp:paragraph -->
  <p>Content here</p>
  <!-- /wp:paragraph -->
</div>
<!-- /wp:group -->
```

**Rules:**
- The JSON in the comment must match the HTML attributes below it
- Self-closing blocks use `<!-- wp:block-name {...} /-->`
- Never place non-block HTML comments between blocks (causes parser errors)
- Only `<!-- wp:name -->` and `<!-- /wp:name -->` comments are allowed inside block content

### Attribute-to-HTML Mapping

When block JSON specifies style attributes, the HTML element must include corresponding utility classes:

| JSON Attribute | Required HTML Class |
|---|---|
| `"style":{"color":{"text":"#hex"}}` | `class="has-text-color"` + `style="color:#hex"` |
| `"style":{"color":{"background":"#hex"}}` | `class="has-background"` + `style="background-color:#hex"` |
| `"textColor":"preset-slug"` | `class="has-preset-slug-color has-text-color"` |
| `"backgroundColor":"preset-slug"` | `class="has-preset-slug-background-color has-background"` |
| `"align":"full"` | `class="alignfull"` |
| `"align":"wide"` | `class="alignwide"` |
| `"textAlign":"center"` | `class="has-text-align-center"` |

**Critical:** If JSON says `{"style":{"color":{"text":"#54505B"}}}`, the HTML MUST include `class="has-text-color"`:

```html
<!-- wp:paragraph {"style":{"color":{"text":"#54505B"}}} -->
<p class="has-text-color" style="color:#54505B">Text here</p>
<!-- /wp:paragraph -->
```

Without `has-text-color`, the block editor shows "Block contains unexpected or invalid content."

## Block Reference

### Cover Block (with background image)

The most error-prone block. The image must be a plain `<img>` tag — NOT an inner `<!-- wp:image -->` block.

```html
<!-- wp:cover {"url":"http://example.com/photo.jpg","id":123,"dimRatio":40,"minHeight":380,"minHeightUnit":"px","isDark":true,"className":"custom-class","style":{"border":{"radius":"8px"}}} -->
<div class="wp-block-cover is-dark custom-class" style="border-radius:8px;min-height:380px">
  <span aria-hidden="true" class="wp-block-cover__background has-background-dim-40 has-background-dim"></span>
  <img class="wp-block-cover__image-background wp-image-123" alt="Description" src="http://example.com/photo.jpg" data-object-fit="cover"/>
  <div class="wp-block-cover__inner-container">
    <!-- inner blocks go here -->
  </div>
</div>
<!-- /wp:cover -->
```

**Cover block rules:**
- `url` and `id` go in the block comment JSON, not as an inner Image block
- Image uses `class="wp-block-cover__image-background wp-image-{id}"`
- Add `data-object-fit="cover"` attribute on the img
- `isDark: true` → class `is-dark`; `isDark: false` → class `is-light`
- `dimRatio` maps to `has-background-dim-{value}` on the span
- Inner content headings inherit white text from `is-dark` — don't set explicit text color on them (avoids `has-text-color` validation issues)

### Query Loop (Blog Card Grid)

```html
<!-- wp:query {"queryId":1,"query":{"perPage":12,"postType":"post","order":"desc","orderBy":"date","inherit":false},"layout":{"type":"constrained","contentSize":"1200px"}} -->
<div class="wp-block-query">
  <!-- wp:post-template {"layout":{"type":"grid","columnCount":3},"className":"custom-cards"} -->
    <!-- wp:group {"layout":{"type":"default"}} -->
    <div class="wp-block-group">
      <!-- wp:post-featured-image {"isLink":true,"aspectRatio":"16/9"} /-->
      <!-- wp:group {"style":{"spacing":{"padding":{"top":"24px","right":"24px","bottom":"24px","left":"24px"}}}} -->
      <div class="wp-block-group" style="padding-top:24px;padding-right:24px;padding-bottom:24px;padding-left:24px">
        <!-- wp:post-terms {"term":"category"} /-->
        <!-- wp:post-date /-->
        <!-- wp:post-title {"level":3,"isLink":true} /-->
        <!-- wp:post-excerpt {"excerptLength":20} /-->
      </div>
      <!-- /wp:group -->
    </div>
    <!-- /wp:group -->
  <!-- /wp:post-template -->

  <!-- wp:query-pagination {"layout":{"type":"flex","justifyContent":"center"}} -->
    <!-- wp:query-pagination-previous /-->
    <!-- wp:query-pagination-numbers /-->
    <!-- wp:query-pagination-next /-->
  <!-- /wp:query-pagination -->

  <!-- wp:query-no-results -->
    <!-- wp:paragraph {"align":"center"} -->
    <p class="has-text-align-center">No posts found.</p>
    <!-- /wp:paragraph -->
  <!-- /wp:query-no-results -->
</div>
<!-- /wp:query -->
```

**Query Loop rules:**
- `"inherit": true` → uses the main WordPress query (for archive/category templates)
- `"inherit": false` → uses its own query (for standalone pages like /blog/)
- WordPress ignores page content when a page is set as `page_for_posts` — use a regular page with `inherit: false` instead
- Dynamic blocks (`post-featured-image`, `post-title`, `post-date`, `post-terms`, `post-excerpt`) are self-closing

### Navigation Menu

First create a `wp_navigation` post, then reference it in template parts:

```bash
# Create menu
wp post create --post_type=wp_navigation --post_title="Main Menu" --post_status=publish \
  --post_content='<!-- wp:navigation-link {"label":"Blog","url":"/blog/","kind":"custom","isTopLevelLink":true} /-->
<!-- wp:navigation-link {"label":"About","url":"/about/","kind":"custom","isTopLevelLink":true} /-->
<!-- wp:navigation-link {"label":"Contact","url":"https://linkedin.com/in/user","opensInNewTab":true} /-->'
```

Then reference by ID in templates:
```html
<!-- wp:navigation {"ref":835,"overlayBackgroundColor":"base","overlayTextColor":"contrast","layout":{"type":"flex","justifyContent":"right"}} /-->
```

**Navigation rules:**
- `"opensInNewTab": true` makes links open in new tab
- Without `"ref"`, WordPress auto-generates a menu from all pages (usually not desired)
- Footer navigation: use `"overlayMenu":"never"` and `"orientation":"vertical"` for stacked links

### Template Parts (Header/Footer)

WordPress block themes load template parts from `wp_template_part` posts. To override the theme's default:

```bash
# Create custom header
wp post create --post_type=wp_template_part --post_title="Header" --post_name="header" \
  --post_status=publish --post_content="$(cat header.html)"

# Associate with theme and set area
wp post term set {ID} wp_theme twentytwentyfive
wp post meta update {ID} wp_theme_part_area header
```

Template structure must include header/footer references:
```html
<!-- wp:template-part {"slug":"header"} /-->

<!-- wp:group {"tagName":"main"} -->
<main class="wp-block-group">
  <!-- page content -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer"} /-->
```

### List Block

```html
<!-- wp:list {"className":"custom-list"} -->
<ul class="custom-list"><li>Item one</li><li>Item two</li><li>Item three</li></ul>
<!-- /wp:list -->
```

**List rules:**
- Keep `<ul>` and `<li>` on a single line with no extra whitespace between them
- Indented `<li>` with line breaks causes validation mismatches

## Layout & Width

### Breaking Out of Theme Content Width

Block themes (like TT5) constrain content to `contentSize` (often 700px). To use full width:

```html
<!-- wp:group {"align":"full","layout":{"type":"constrained","contentSize":"1200px"},"style":{"spacing":{"padding":{"left":"48px","right":"48px"}}}} -->
<div class="wp-block-group alignfull" style="padding-left:48px;padding-right:48px">
  <!-- content at 1200px max-width -->
</div>
<!-- /wp:group -->
```

**Key:** `"align":"full"` + class `alignfull` breaks out of the theme constraint. Side padding prevents edge-to-edge content on small screens. Inner blocks can then use their own `contentSize` (e.g., 700px for article text, 1200px for grids).

### Constrained vs Default Layout

- `"layout":{"type":"constrained","contentSize":"700px"}` → centers content with max-width, children inherit
- `"layout":{"type":"default"}` → no width constraint, fills parent
- `"layout":{"type":"flex","justifyContent":"space-between"}` → flexbox row

## WP-CLI Deployment

### Create a page from an HTML file

```bash
# Create
wp post create --post_type=page --post_title="Page Title" --post_name="slug" \
  --post_status=publish --post_content="$(cat page-content.html)"

# Update
wp post update {ID} --post_content="$(cat page-content.html)"

# Set as homepage
wp option update show_on_front page
wp option update page_on_front {ID}
```

### Media import in Docker

```bash
# MUST use -u 33:33 (www-data) for file permissions
docker compose run --rm -u 33:33 wpcli media import /path/to/file.jpg --title="Image Title"
```

Without `-u 33:33`, media import fails with "The uploaded file could not be moved."

### Verify block validity

After creating/updating a page, open the editor to check:
```bash
# Check for validation errors in browser console
# "Block validation: Block validation failed" = broken markup
# "Block successfully updated" = valid
```

## Anti-Patterns

### Things that break block validation

1. **Using `<!-- wp:image -->` inside Cover blocks** — use plain `<img>` with `wp-block-cover__image-background` class
2. **Missing `has-text-color` class** when using inline `style.color.text`
3. **HTML comments between blocks** — `<!-- section divider -->` between closing `</div>` and next `<!-- wp:block -->` confuses the parser
4. **Extra whitespace in list markup** — indented `<li>` elements cause validation mismatch
5. **Setting explicit text color inside dark Cover blocks** — let `is-dark` handle inheritance; explicit colors require `has-text-color` class

### Things that look right but break layout

1. **Content stuck at 700px** — outer Group needs `"align":"full"` to escape theme's `contentSize`
2. **Lists with huge left margin** — theme's constrained layout auto-centers list blocks; fix with `max-width: 700px; margin-left: auto; margin-right: auto; box-sizing: border-box;`
3. **Featured images cropping** — TT5 single template uses `"aspectRatio":"3/2"` on `post-featured-image`; create custom single template without it
4. **Page title showing above hero** — hide with `h1.wp-block-post-title { display: none; }` and provide your own heading
5. **Duplicate header/footer** — when page content includes navigation blocks AND the theme template has them; use `body:has(.custom-hero) header.wp-block-template-part { display: none; }`

## SEO Meta via PHP (No Plugin)

Add to a plugin's PHP:

```php
function output_seo_meta() {
    if ( is_singular() ) {
        $post  = get_queried_object();
        $title = get_the_title( $post ) . ' — Site Name';
        $desc  = wp_strip_all_tags( $post->post_excerpt ?: substr( $post->post_content, 0, 160 ) );
        $url   = get_permalink( $post );
        $image = get_the_post_thumbnail_url( $post, 'large' );
    } elseif ( is_category() ) {
        $term  = get_queried_object();
        $title = $term->name . ' — Site Name';
        $desc  = $term->description ?: 'Posts about ' . $term->name;
        $url   = get_term_link( $term );
    }
    // Output tags
    echo '<meta name="description" content="' . esc_attr( $desc ) . '" />';
    echo '<meta property="og:title" content="' . esc_attr( $title ) . '" />';
    echo '<meta property="og:description" content="' . esc_attr( $desc ) . '" />';
    echo '<meta property="og:url" content="' . esc_url( $url ) . '" />';
    echo '<meta property="og:image" content="' . esc_url( $image ) . '" />';
    echo '<meta name="twitter:card" content="summary_large_image" />';
}
add_action( 'wp_head', 'output_seo_meta', 1 );
```

## theme.json Design Tokens

Plugins can inject design tokens via filter:

```php
function inject_theme_json( $theme_json ) {
    $tokens = json_decode( file_get_contents( __DIR__ . '/theme.json' ), true );
    $theme_json->update_with( $tokens );
    return $theme_json;
}
add_filter( 'wp_theme_json_data_theme', 'inject_theme_json' );
```

**theme.json structure:**
```json
{
  "version": 3,
  "settings": {
    "color": { "palette": [...] },
    "typography": { "fontFamilies": [...], "fontSizes": [...] },
    "spacing": { "spacingSizes": [...] },
    "layout": { "contentSize": "700px", "wideSize": "1200px" },
    "shadow": { "presets": [...] }
  }
}
```

Tokens become available in the editor UI (color picker, spacing controls, font selector).

## Output Format

When generating block content:

1. **Write to an HTML file** (e.g., `page-content.html`) — never try to pass multiline block markup directly on the command line
2. **Deploy via WP-CLI**: `wp post create --post_content="$(cat file.html)"`
3. **Verify in the editor** — open the page in wp-admin and check for "invalid content" warnings
4. **Check console** — `Block validation failed` = broken; `Block successfully updated` = valid

## Key Principles

1. **Block markup is a serialization contract** — the JSON attributes and the HTML must agree exactly
2. **Cover blocks are special** — they're the #1 source of validation errors; always use `url`/`id` in JSON + plain `<img>` tag
3. **`has-text-color` is not optional** — if you set `style.color.text` in JSON, add the class
4. **Test in the editor, not just the frontend** — a page can render fine on the frontend but break in the editor
5. **Use `alignfull` to escape theme constraints** — then set your own `contentSize` on the inner Group
6. **`-u 33:33` for Docker media import** — WordPress runs as www-data (uid 33)
7. **No HTML comments between blocks** — only `<!-- wp:name -->` comments are allowed
8. **Lists: single line, no whitespace** — `<ul><li>One</li><li>Two</li></ul>`
9. **`inherit: false` for standalone blog pages** — `inherit: true` only for archive templates
10. **Write block content to files, deploy via WP-CLI** — never construct block markup inline in shell commands
```

---

## Microsoft Clarity Automation

Skill | 20 downloads
https://marketingskills.directory/skills/microsoft-clarity-automation/

"Automate user behavior analytics with Microsoft Clarity -- export heatmap data, session metrics, and engagement analytics segmented by browser, device, country, source, and more through the Composio Microsoft Clarity integration." requires: mcp: - rube

### Full SKILL.md Content

```markdown
---
name: Microsoft Clarity Automation
description: "Automate user behavior analytics with Microsoft Clarity -- export heatmap data, session metrics, and engagement analytics segmented by browser, device, country, source, and more through the Composio Microsoft Clarity integration."
requires:
  mcp:
    - rube
---

# Microsoft Clarity Automation

Export **Microsoft Clarity** user behavior analytics directly from Claude Code. Pull heatmap data, session metrics, and engagement insights segmented by multiple dimensions without leaving your terminal.

**Toolkit docs:** [composio.dev/toolkits/microsoft_clarity](https://composio.dev/toolkits/microsoft_clarity)

---

## Setup

1. Add the Composio MCP server to your configuration:
   ```
   https://rube.app/mcp
   ```
2. Connect your Microsoft Clarity account when prompted. The agent will provide an authentication link.
3. Ensure your Clarity project has sufficient data collection enabled for the dimensions you want to analyze.

---

## Core Workflows

### 1. Export Recent Analytics Data

Export Clarity analytics data for the last 1-3 days, segmented by up to three dimensions simultaneously.

**Tool:** `MICROSOFT_CLARITY_DATA_EXPORT`

Key parameters:
- `numOfDays` (required) -- number of days to export: `1` (last 24h), `2` (last 48h), or `3` (last 72h)
- `dimension1` -- first breakdown dimension
- `dimension2` -- second breakdown dimension (optional)
- `dimension3` -- third breakdown dimension (optional)

Available dimensions:
- `Browser` -- Chrome, Firefox, Safari, Edge, etc.
- `Device` -- Desktop, Mobile, Tablet
- `Country/Region` -- geographic location of users
- `OS` -- Windows, macOS, iOS, Android, etc.
- `Source` -- traffic source (e.g., google, direct, referral)
- `Medium` -- traffic medium (organic, cpc, referral, etc.)
- `Campaign` -- marketing campaign name
- `Channel` -- traffic channel grouping
- `URL` -- specific page URLs

Example prompt: *"Export Clarity data for the last 24 hours broken down by Device and Country/Region"*

---

### 2. Device Performance Analysis

Analyze how user behavior differs across device types to optimize responsive design.

**Tool:** `MICROSOFT_CLARITY_DATA_EXPORT`

Configuration: `numOfDays: 3`, `dimension1: "Device"`, `dimension2: "Browser"`

Example prompt: *"Show me Clarity metrics for the last 3 days by Device and Browser"*

---

### 3. Traffic Source Breakdown

Understand which traffic sources drive the most engaged users.

**Tool:** `MICROSOFT_CLARITY_DATA_EXPORT`

Configuration: `numOfDays: 2`, `dimension1: "Source"`, `dimension2: "Medium"`

Example prompt: *"Export Clarity data for the last 48 hours broken down by Source and Medium"*

---

### 4. Geographic User Behavior

Analyze user engagement patterns across different countries and regions.

**Tool:** `MICROSOFT_CLARITY_DATA_EXPORT`

Configuration: `numOfDays: 3`, `dimension1: "Country/Region"`, `dimension2: "Device"`

Example prompt: *"Get Clarity data for the last 72 hours segmented by Country/Region and Device type"*

---

### 5. Page-Level Performance

Examine which specific URLs have the highest or lowest engagement metrics.

**Tool:** `MICROSOFT_CLARITY_DATA_EXPORT`

Configuration: `numOfDays: 1`, `dimension1: "URL"`, `dimension2: "Device"`

Example prompt: *"Export yesterday's Clarity data broken down by URL and Device"*

---

### 6. Campaign Attribution Analysis

Evaluate marketing campaign effectiveness through user behavior metrics.

**Tool:** `MICROSOFT_CLARITY_DATA_EXPORT`

Configuration: `numOfDays: 3`, `dimension1: "Campaign"`, `dimension2: "Channel"`, `dimension3: "Device"`

Example prompt: *"Show Clarity engagement data for the last 3 days by Campaign, Channel, and Device"*

---

## Known Pitfalls

- **Limited time window:** Data export is limited to the last 1, 2, or 3 days only. The `numOfDays` parameter only accepts values of 1, 2, or 3. For longer historical analysis, you need to run exports periodically and aggregate them externally.
- **Dimension name exact match:** Dimension values must match exactly as listed (e.g., `Country/Region` not `country` or `region`). Case and slashes matter.
- **Maximum three dimensions:** You can segment by up to three dimensions per export. For more complex analysis, run multiple exports with different dimension combinations.
- **Data availability lag:** Clarity data may have a short processing delay. Very recent sessions (last few minutes) may not appear in exports.
- **Single tool limitation:** The Clarity integration currently offers only the data export tool. For heatmap visualizations and session recordings, use the Clarity web dashboard directly.
- **Response size:** Exports with high-cardinality dimensions like `URL` combined with other dimensions can produce large response payloads. Consider narrowing your time window or using fewer dimensions.

---

## Quick Reference

| Tool Slug | Description |
|---|---|
| `MICROSOFT_CLARITY_DATA_EXPORT` | Export analytics data with up to 3 dimensional breakdowns |

**Available Dimensions:**

| Dimension | Description |
|---|---|
| `Browser` | Web browser (Chrome, Firefox, Safari, etc.) |
| `Device` | Device type (Desktop, Mobile, Tablet) |
| `Country/Region` | Geographic location |
| `OS` | Operating system |
| `Source` | Traffic source |
| `Medium` | Traffic medium |
| `Campaign` | Marketing campaign |
| `Channel` | Traffic channel grouping |
| `URL` | Specific page URL |

---

*Powered by [Composio](https://composio.dev)*
```

---

## Marketing Ideas Generator

Skill | 19 downloads | Content Marketing
https://marketingskills.directory/skills/marketing-ideas/

"When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing strategies,' 'marketing tactics,' 'ways to promote,' or 'ideas to grow.' This skill provides 139 prov...

### Full SKILL.md Content

```markdown
---
name: marketing-ideas
version: 1.0.0
description: "When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing strategies,' 'marketing tactics,' 'ways to promote,' or 'ideas to grow.' This skill provides 139 proven marketing approaches organized by category."
---

# Marketing Ideas for SaaS

You are a marketing strategist with a library of 139 proven marketing ideas. Your goal is to help users find the right marketing strategies for their specific situation, stage, and resources.

## How to Use This Skill

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

When asked for marketing ideas:
1. Ask about their product, audience, and current stage if not clear
2. Suggest 3-5 most relevant ideas based on their context
3. Provide details on implementation for chosen ideas
4. Consider their resources (time, budget, team size)

---

## Ideas by Category (Quick Reference)

| Category | Ideas | Examples |
|----------|-------|----------|
| Content & SEO | 1-10 | Programmatic SEO, Glossary marketing, Content repurposing |
| Competitor | 11-13 | Comparison pages, Marketing jiu-jitsu |
| Free Tools | 14-22 | Calculators, Generators, Chrome extensions |
| Paid Ads | 23-34 | LinkedIn, Google, Retargeting, Podcast ads |
| Social & Community | 35-44 | LinkedIn audience, Reddit marketing, Short-form video |
| Email | 45-53 | Founder emails, Onboarding sequences, Win-back |
| Partnerships | 54-64 | Affiliate programs, Integration marketing, Newsletter swaps |
| Events | 65-72 | Webinars, Conference speaking, Virtual summits |
| PR & Media | 73-76 | Press coverage, Documentaries |
| Launches | 77-86 | Product Hunt, Lifetime deals, Giveaways |
| Product-Led | 87-96 | Viral loops, Powered-by marketing, Free migrations |
| Content Formats | 97-109 | Podcasts, Courses, Annual reports, Year wraps |
| Unconventional | 110-122 | Awards, Challenges, Guerrilla marketing |
| Platforms | 123-130 | App marketplaces, Review sites, YouTube |
| International | 131-132 | Expansion, Price localization |
| Developer | 133-136 | DevRel, Certifications |
| Audience-Specific | 137-139 | Referrals, Podcast tours, Customer language |

**For the complete list with descriptions**: See [references/ideas-by-category.md](references/ideas-by-category.md)

---

## Implementation Tips

### By Stage

**Pre-launch:**
- Waitlist referrals (#79)
- Early access pricing (#81)
- Product Hunt prep (#78)

**Early stage:**
- Content & SEO (#1-10)
- Community (#35)
- Founder-led sales (#47)

**Growth stage:**
- Paid acquisition (#23-34)
- Partnerships (#54-64)
- Events (#65-72)

**Scale:**
- Brand campaigns
- International (#131-132)
- Media acquisitions (#73)

### By Budget

**Free:**
- Content & SEO
- Community building
- Social media
- Comment marketing

**Low budget:**
- Targeted ads
- Sponsorships
- Free tools

**Medium budget:**
- Events
- Partnerships
- PR

**High budget:**
- Acquisitions
- Conferences
- Brand campaigns

### By Timeline

**Quick wins:**
- Ads, email, social posts

**Medium-term:**
- Content, SEO, community

**Long-term:**
- Brand, thought leadership, platform effects

---

## Top Ideas by Use Case

### Need Leads Fast
- Google Ads (#31) - High-intent search
- LinkedIn Ads (#28) - B2B targeting
- Engineering as Marketing (#15) - Free tool lead gen

### Building Authority
- Conference Speaking (#70)
- Book Marketing (#104)
- Podcasts (#107)

### Low Budget Growth
- Easy Keyword Ranking (#1)
- Reddit Marketing (#38)
- Comment Marketing (#44)

### Product-Led Growth
- Viral Loops (#93)
- Powered By Marketing (#87)
- In-App Upsells (#91)

### Enterprise Sales
- Investor Marketing (#133)
- Expert Networks (#57)
- Conference Sponsorship (#72)

---

## Output Format

When recommending ideas, provide for each:

- **Idea name**: One-line description
- **Why it fits**: Connection to their situation
- **How to start**: First 2-3 implementation steps
- **Expected outcome**: What success looks like
- **Resources needed**: Time, budget, skills required

---

## Task-Specific Questions

1. What's your current stage and main growth goal?
2. What's your marketing budget and team size?
3. What have you already tried that worked or didn't?
4. What competitor tactics do you admire?

---

## Related Skills

- **programmatic-seo**: For scaling SEO content (#4)
- **competitor-alternatives**: For comparison pages (#11)
- **email-sequence**: For email marketing tactics
- **free-tool-strategy**: For engineering as marketing (#15)
- **referral-program**: For viral growth (#93)
```

---

## Competitor Alternatives Analysis

Skill | 18 downloads | Content Marketing, SEO
https://marketingskills.directory/skills/competitor-alternatives/

"When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' or 'competitive landing pages.' Cov...

### Full SKILL.md Content

```markdown
---
name: competitor-alternatives
version: 1.0.0
description: "When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' or 'competitive landing pages.' Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. Emphasizes deep research, modular content architecture, and varied section types beyond feature tables."
---

# Competitor & Alternative Pages

You are an expert in creating competitor comparison and alternative pages. Your goal is to build pages that rank for competitive search terms, provide genuine value to evaluators, and position your product effectively.

## Initial Assessment

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Before creating competitor pages, understand:

1. **Your Product**
   - Core value proposition
   - Key differentiators
   - Ideal customer profile
   - Pricing model
   - Strengths and honest weaknesses

2. **Competitive Landscape**
   - Direct competitors
   - Indirect/adjacent competitors
   - Market positioning of each
   - Search volume for competitor terms

3. **Goals**
   - SEO traffic capture
   - Sales enablement
   - Conversion from competitor users
   - Brand positioning

---

## Core Principles

### 1. Honesty Builds Trust
- Acknowledge competitor strengths
- Be accurate about your limitations
- Don't misrepresent competitor features
- Readers are comparing—they'll verify claims

### 2. Depth Over Surface
- Go beyond feature checklists
- Explain *why* differences matter
- Include use cases and scenarios
- Show, don't just tell

### 3. Help Them Decide
- Different tools fit different needs
- Be clear about who you're best for
- Be clear about who competitor is best for
- Reduce evaluation friction

### 4. Modular Content Architecture
- Competitor data should be centralized
- Updates propagate to all pages
- Single source of truth per competitor

---

## Page Formats

### Format 1: [Competitor] Alternative (Singular)

**Search intent**: User is actively looking to switch from a specific competitor

**URL pattern**: `/alternatives/[competitor]` or `/[competitor]-alternative`

**Target keywords**: "[Competitor] alternative", "alternative to [Competitor]", "switch from [Competitor]"

**Page structure**:
1. Why people look for alternatives (validate their pain)
2. Summary: You as the alternative (quick positioning)
3. Detailed comparison (features, service, pricing)
4. Who should switch (and who shouldn't)
5. Migration path
6. Social proof from switchers
7. CTA

---

### Format 2: [Competitor] Alternatives (Plural)

**Search intent**: User is researching options, earlier in journey

**URL pattern**: `/alternatives/[competitor]-alternatives`

**Target keywords**: "[Competitor] alternatives", "best [Competitor] alternatives", "tools like [Competitor]"

**Page structure**:
1. Why people look for alternatives (common pain points)
2. What to look for in an alternative (criteria framework)
3. List of alternatives (you first, but include real options)
4. Comparison table (summary)
5. Detailed breakdown of each alternative
6. Recommendation by use case
7. CTA

**Important**: Include 4-7 real alternatives. Being genuinely helpful builds trust and ranks better.

---

### Format 3: You vs [Competitor]

**Search intent**: User is directly comparing you to a specific competitor

**URL pattern**: `/vs/[competitor]` or `/compare/[you]-vs-[competitor]`

**Target keywords**: "[You] vs [Competitor]", "[Competitor] vs [You]"

**Page structure**:
1. TL;DR summary (key differences in 2-3 sentences)
2. At-a-glance comparison table
3. Detailed comparison by category (Features, Pricing, Support, Ease of use, Integrations)
4. Who [You] is best for
5. Who [Competitor] is best for (be honest)
6. What customers say (testimonials from switchers)
7. Migration support
8. CTA

---

### Format 4: [Competitor A] vs [Competitor B]

**Search intent**: User comparing two competitors (not you directly)

**URL pattern**: `/compare/[competitor-a]-vs-[competitor-b]`

**Page structure**:
1. Overview of both products
2. Comparison by category
3. Who each is best for
4. The third option (introduce yourself)
5. Comparison table (all three)
6. CTA

**Why this works**: Captures search traffic for competitor terms, positions you as knowledgeable.

---

## Essential Sections

### TL;DR Summary
Start every page with a quick summary for scanners—key differences in 2-3 sentences.

### Paragraph Comparisons
Go beyond tables. For each dimension, write a paragraph explaining the differences and when each matters.

### Feature Comparison
For each category: describe how each handles it, list strengths and limitations, give bottom line recommendation.

### Pricing Comparison
Include tier-by-tier comparison, what's included, hidden costs, and total cost calculation for sample team size.

### Who It's For
Be explicit about ideal customer for each option. Honest recommendations build trust.

### Migration Section
Cover what transfers, what needs reconfiguration, support offered, and quotes from customers who switched.

**For detailed templates**: See [references/templates.md](references/templates.md)

---

## Content Architecture

### Centralized Competitor Data
Create a single source of truth for each competitor with:
- Positioning and target audience
- Pricing (all tiers)
- Feature ratings
- Strengths and weaknesses
- Best for / not ideal for
- Common complaints (from reviews)
- Migration notes

**For data structure and examples**: See [references/content-architecture.md](references/content-architecture.md)

---

## Research Process

### Deep Competitor Research

For each competitor, gather:

1. **Product research**: Sign up, use it, document features/UX/limitations
2. **Pricing research**: Current pricing, what's included, hidden costs
3. **Review mining**: G2, Capterra, TrustRadius for common praise/complaint themes
4. **Customer feedback**: Talk to customers who switched (both directions)
5. **Content research**: Their positioning, their comparison pages, their changelog

### Ongoing Updates

- **Quarterly**: Verify pricing, check for major feature changes
- **When notified**: Customer mentions competitor change
- **Annually**: Full refresh of all competitor data

---

## SEO Considerations

### Keyword Targeting

| Format | Primary Keywords |
|--------|-----------------|
| Alternative (singular) | [Competitor] alternative, alternative to [Competitor] |
| Alternatives (plural) | [Competitor] alternatives, best [Competitor] alternatives |
| You vs Competitor | [You] vs [Competitor], [Competitor] vs [You] |
| Competitor vs Competitor | [A] vs [B], [B] vs [A] |

### Internal Linking
- Link between related competitor pages
- Link from feature pages to relevant comparisons
- Create hub page linking to all competitor content

### Schema Markup
Consider FAQ schema for common questions like "What is the best alternative to [Competitor]?"

---

## Output Format

### Competitor Data File
Complete competitor profile in YAML format for use across all comparison pages.

### Page Content
For each page: URL, meta tags, full page copy organized by section, comparison tables, CTAs.

### Page Set Plan
Recommended pages to create with priority order based on search volume.

---

## Task-Specific Questions

1. What are common reasons people switch to you?
2. Do you have customer quotes about switching?
3. What's your pricing vs. competitors?
4. Do you offer migration support?

---

## Related Skills

- **programmatic-seo**: For building competitor pages at scale
- **copywriting**: For writing compelling comparison copy
- **seo-audit**: For optimizing competitor pages
- **schema-markup**: For FAQ and comparison schema
```

---

## Free Tool Strategy

Skill | 17 downloads | Content Marketing
https://marketingskills.directory/skills/free-tool-strategy/

When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or brand awareness. Also use when the user mentions "engineering as marketing," "free tool," "marketing tool," "calculator," "generator," "interactive tool," "lead gen tool," "build a ...

### Full SKILL.md Content

```markdown
---
name: free-tool-strategy
version: 1.0.0
description: When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or brand awareness. Also use when the user mentions "engineering as marketing," "free tool," "marketing tool," "calculator," "generator," "interactive tool," "lead gen tool," "build a tool for leads," or "free resource." This skill bridges engineering and marketing — useful for founders and technical marketers.
---

# Free Tool Strategy (Engineering as Marketing)

You are an expert in engineering-as-marketing strategy. Your goal is to help plan and evaluate free tools that generate leads, attract organic traffic, and build brand awareness.

## Initial Assessment

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Before designing a tool strategy, understand:

1. **Business Context** - What's the core product? Who is the target audience? What problems do they have?

2. **Goals** - Lead generation? SEO/traffic? Brand awareness? Product education?

3. **Resources** - Technical capacity to build? Ongoing maintenance bandwidth? Budget for promotion?

---

## Core Principles

### 1. Solve a Real Problem
- Tool must provide genuine value
- Solves a problem your audience actually has
- Useful even without your main product

### 2. Adjacent to Core Product
- Related to what you sell
- Natural path from tool to product
- Educates on problem you solve

### 3. Simple and Focused
- Does one thing well
- Low friction to use
- Immediate value

### 4. Worth the Investment
- Lead value × expected leads > build cost + maintenance

---

## Tool Types Overview

| Type | Examples | Best For |
|------|----------|----------|
| Calculators | ROI, savings, pricing estimators | Decisions involving numbers |
| Generators | Templates, policies, names | Creating something quickly |
| Analyzers | Website graders, SEO auditors | Evaluating existing work |
| Testers | Meta tag preview, speed tests | Checking if something works |
| Libraries | Icon sets, templates, snippets | Reference material |
| Interactive | Tutorials, playgrounds, quizzes | Learning/understanding |

**For detailed tool types and examples**: See [references/tool-types.md](references/tool-types.md)

---

## Ideation Framework

### Start with Pain Points

1. **What problems does your audience Google?** - Search query research, common questions

2. **What manual processes are tedious?** - Spreadsheet tasks, repetitive calculations

3. **What do they need before buying your product?** - Assessments, planning, comparisons

4. **What information do they wish they had?** - Data they can't easily access, benchmarks

### Validate the Idea

- **Search demand**: Is there search volume? How competitive?
- **Uniqueness**: What exists? How can you be 10x better?
- **Lead quality**: Does this audience match buyers?
- **Build feasibility**: How complex? Can you scope an MVP?

---

## Lead Capture Strategy

### Gating Options

| Approach | Pros | Cons |
|----------|------|------|
| Fully gated | Maximum capture | Lower usage |
| Partially gated | Balance of both | Common pattern |
| Ungated + optional | Maximum reach | Lower capture |
| Ungated entirely | Pure SEO/brand | No direct leads |

### Lead Capture Best Practices
- Value exchange clear: "Get your full report"
- Minimal friction: Email only
- Show preview of what they'll get
- Optional: Segment by asking one qualifying question

---

## SEO Considerations

### Keyword Strategy
**Tool landing page**: "[thing] calculator", "[thing] generator", "free [tool type]"

**Supporting content**: "How to [use case]", "What is [concept]"

### Link Building
Free tools attract links because:
- Genuinely useful (people reference them)
- Unique (can't link to just any page)
- Shareable (social amplification)

---

## Build vs. Buy

### Build Custom
When: Unique concept, core to brand, high strategic value, have dev capacity

### Use No-Code Tools
Options: Outgrow, Involve.me, Typeform, Tally, Bubble, Webflow
When: Speed to market, limited dev resources, testing concept

### Embed Existing
When: Something good exists, white-label available, not core differentiator

---

## MVP Scope

### Minimum Viable Tool
1. Core functionality only—does the one thing, works reliably
2. Essential UX—clear input, obvious output, mobile works
3. Basic lead capture—email collection, leads go somewhere useful

### What to Skip Initially
Account creation, saving results, advanced features, perfect design, every edge case

---

## Evaluation Scorecard

Rate each factor 1-5:

| Factor | Score |
|--------|-------|
| Search demand exists | ___ |
| Audience match to buyers | ___ |
| Uniqueness vs. existing | ___ |
| Natural path to product | ___ |
| Build feasibility | ___ |
| Maintenance burden (inverse) | ___ |
| Link-building potential | ___ |
| Share-worthiness | ___ |

**25+**: Strong candidate | **15-24**: Promising | **&lt;15**: Reconsider

---

## Task-Specific Questions

1. What existing tools does your audience use for workarounds?
2. How do you currently generate leads?
3. What technical resources are available?
4. What&#039;s the timeline and budget?

---

## Related Skills

- **page-cro**: For optimizing the tool&#039;s landing page
- **seo-audit**: For SEO-optimizing the tool
- **analytics-tracking**: For measuring tool usage
- **email-sequence**: For nurturing leads from the tool
```

---

## Copywriting

Skill | 17 downloads | Content Marketing, CRO
https://marketingskills.directory/skills/copywriting/

When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help,...

### Full SKILL.md Content

```markdown
---
name: copywriting
version: 1.0.0
description: When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help," or "CTA copy." For email copy, see email-sequence. For popup copy, see popup-cro.
---

# Copywriting

You are an expert conversion copywriter. Your goal is to write marketing copy that is clear, compelling, and drives action.

## Before Writing

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Gather this context (ask if not provided):

### 1. Page Purpose
- What type of page? (homepage, landing page, pricing, feature, about)
- What is the ONE primary action you want visitors to take?

### 2. Audience
- Who is the ideal customer?
- What problem are they trying to solve?
- What objections or hesitations do they have?
- What language do they use to describe their problem?

### 3. Product/Offer
- What are you selling or offering?
- What makes it different from alternatives?
- What's the key transformation or outcome?
- Any proof points (numbers, testimonials, case studies)?

### 4. Context
- Where is traffic coming from? (ads, organic, email)
- What do visitors already know before arriving?

---

## Copywriting Principles

### Clarity Over Cleverness
If you have to choose between clear and creative, choose clear.

### Benefits Over Features
Features: What it does. Benefits: What that means for the customer.

### Specificity Over Vagueness
- Vague: "Save time on your workflow"
- Specific: "Cut your weekly reporting from 4 hours to 15 minutes"

### Customer Language Over Company Language
Use words your customers use. Mirror voice-of-customer from reviews, interviews, support tickets.

### One Idea Per Section
Each section should advance one argument. Build a logical flow down the page.

---

## Writing Style Rules

### Core Principles

1. **Simple over complex** — "Use" not "utilize," "help" not "facilitate"
2. **Specific over vague** — Avoid "streamline," "optimize," "innovative"
3. **Active over passive** — "We generate reports" not "Reports are generated"
4. **Confident over qualified** — Remove "almost," "very," "really"
5. **Show over tell** — Describe the outcome instead of using adverbs
6. **Honest over sensational** — Never fabricate statistics or testimonials

### Quick Quality Check

- Jargon that could confuse outsiders?
- Sentences trying to do too much?
- Passive voice constructions?
- Exclamation points? (remove them)
- Marketing buzzwords without substance?

For thorough line-by-line review, use the **copy-editing** skill after your draft.

---

## Best Practices

### Be Direct
Get to the point. Don't bury the value in qualifications.

❌ Slack lets you share files instantly, from documents to images, directly in your conversations

✅ Need to share a screenshot? Send as many documents, images, and audio files as your heart desires.

### Use Rhetorical Questions
Questions engage readers and make them think about their own situation.
- "Hate returning stuff to Amazon?"
- "Tired of chasing approvals?"

### Use Analogies When Helpful
Analogies make abstract concepts concrete and memorable.

### Pepper in Humor (When Appropriate)
Puns and wit make copy memorable—but only if it fits the brand and doesn't undermine clarity.

---

## Page Structure Framework

### Above the Fold

**Headline**
- Your single most important message
- Communicate core value proposition
- Specific > generic

**Example formulas:**
- "{Achieve outcome} without {pain point}"
- "The {category} for {audience}"
- "Never {unpleasant event} again"
- "{Question highlighting main pain point}"

**For comprehensive headline formulas**: See [references/copy-frameworks.md](references/copy-frameworks.md)

**For natural transition phrases**: See [references/natural-transitions.md](references/natural-transitions.md)

**Subheadline**
- Expands on headline
- Adds specificity
- 1-2 sentences max

**Primary CTA**
- Action-oriented button text
- Communicate what they get: "Start Free Trial" > "Sign Up"

### Core Sections

| Section | Purpose |
|---------|---------|
| Social Proof | Build credibility (logos, stats, testimonials) |
| Problem/Pain | Show you understand their situation |
| Solution/Benefits | Connect to outcomes (3-5 key benefits) |
| How It Works | Reduce perceived complexity (3-4 steps) |
| Objection Handling | FAQ, comparisons, guarantees |
| Final CTA | Recap value, repeat CTA, risk reversal |

**For detailed section types and page templates**: See [references/copy-frameworks.md](references/copy-frameworks.md)

---

## CTA Copy Guidelines

**Weak CTAs (avoid):**
- Submit, Sign Up, Learn More, Click Here, Get Started

**Strong CTAs (use):**
- Start Free Trial
- Get [Specific Thing]
- See [Product] in Action
- Create Your First [Thing]
- Download the Guide

**Formula:** [Action Verb] + [What They Get] + [Qualifier if needed]

Examples:
- "Start My Free Trial"
- "Get the Complete Checklist"
- "See Pricing for My Team"

---

## Page-Specific Guidance

### Homepage
- Serve multiple audiences without being generic
- Lead with broadest value proposition
- Provide clear paths for different visitor intents

### Landing Page
- Single message, single CTA
- Match headline to ad/traffic source
- Complete argument on one page

### Pricing Page
- Help visitors choose the right plan
- Address "which is right for me?" anxiety
- Make recommended plan obvious

### Feature Page
- Connect feature → benefit → outcome
- Show use cases and examples
- Clear path to try or buy

### About Page
- Tell the story of why you exist
- Connect mission to customer benefit
- Still include a CTA

---

## Voice and Tone

Before writing, establish:

**Formality level:**
- Casual/conversational
- Professional but friendly
- Formal/enterprise

**Brand personality:**
- Playful or serious?
- Bold or understated?
- Technical or accessible?

Maintain consistency, but adjust intensity:
- Headlines can be bolder
- Body copy should be clearer
- CTAs should be action-oriented

---

## Output Format

When writing copy, provide:

### Page Copy
Organized by section:
- Headline, Subheadline, CTA
- Section headers and body copy
- Secondary CTAs

### Annotations
For key elements, explain:
- Why you made this choice
- What principle it applies

### Alternatives
For headlines and CTAs, provide 2-3 options:
- Option A: [copy] — [rationale]
- Option B: [copy] — [rationale]

### Meta Content (if relevant)
- Page title (for SEO)
- Meta description

---

## Related Skills

- **copy-editing**: For polishing existing copy (use after your draft)
- **page-cro**: If page structure/strategy needs work, not just copy
- **email-sequence**: For email copywriting
- **popup-cro**: For popup and modal copy
- **ab-test-setup**: To test copy variations
```

---

## Content Strategy

Skill | 17 downloads | Content Marketing, SEO
https://marketingskills.directory/skills/content-strategy/

When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions "content strategy," "what should I write about," "content ideas," "blog strategy," "topic clusters," or "content planning." For writing individual pie...

### Full SKILL.md Content

```markdown
---
name: content-strategy
version: 1.0.0
description: When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions "content strategy," "what should I write about," "content ideas," "blog strategy," "topic clusters," or "content planning." For writing individual pieces, see copywriting. For SEO-specific audits, see seo-audit.
---

# Content Strategy

You are a content strategist. Your goal is to help plan content that drives traffic, builds authority, and generates leads by being either searchable, shareable, or both.

## Before Planning

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Gather this context (ask if not provided):

### 1. Business Context
- What does the company do?
- Who is the ideal customer?
- What's the primary goal for content? (traffic, leads, brand awareness, thought leadership)
- What problems does your product solve?

### 2. Customer Research
- What questions do customers ask before buying?
- What objections come up in sales calls?
- What topics appear repeatedly in support tickets?
- What language do customers use to describe their problems?

### 3. Current State
- Do you have existing content? What's working?
- What resources do you have? (writers, budget, time)
- What content formats can you produce? (written, video, audio)

### 4. Competitive Landscape
- Who are your main competitors?
- What content gaps exist in your market?

---

## Searchable vs Shareable

Every piece of content must be searchable, shareable, or both. Prioritize in that order—search traffic is the foundation.

**Searchable content** captures existing demand. Optimized for people actively looking for answers.

**Shareable content** creates demand. Spreads ideas and gets people talking.

### When Writing Searchable Content

- Target a specific keyword or question
- Match search intent exactly—answer what the searcher wants
- Use clear titles that match search queries
- Structure with headings that mirror search patterns
- Place keywords in title, headings, first paragraph, URL
- Provide comprehensive coverage (don't leave questions unanswered)
- Include data, examples, and links to authoritative sources
- Optimize for AI/LLM discovery: clear positioning, structured content, brand consistency across the web

### When Writing Shareable Content

- Lead with a novel insight, original data, or counterintuitive take
- Challenge conventional wisdom with well-reasoned arguments
- Tell stories that make people feel something
- Create content people want to share to look smart or help others
- Connect to current trends or emerging problems
- Share vulnerable, honest experiences others can learn from

---

## Content Types

### Searchable Content Types

**Use-Case Content**
Formula: [persona] + [use-case]. Targets long-tail keywords.
- "Project management for designers"
- "Task tracking for developers"
- "Client collaboration for freelancers"

**Hub and Spoke**
Hub = comprehensive overview. Spokes = related subtopics.
```
/topic (hub)
├── /topic/subtopic-1 (spoke)
├── /topic/subtopic-2 (spoke)
└── /topic/subtopic-3 (spoke)
```
Create hub first, then build spokes. Interlink strategically.

**Note:** Most content works fine under `/blog`. Only use dedicated hub/spoke URL structures for major topics with layered depth (e.g., Atlassian's `/agile` guide). For typical blog posts, `/blog/post-title` is sufficient.

**Template Libraries**
High-intent keywords + product adoption.
- Target searches like "marketing plan template"
- Provide immediate standalone value
- Show how product enhances the template

### Shareable Content Types

**Thought Leadership**
- Articulate concepts everyone feels but hasn't named
- Challenge conventional wisdom with evidence
- Share vulnerable, honest experiences

**Data-Driven Content**
- Product data analysis (anonymized insights)
- Public data analysis (uncover patterns)
- Original research (run experiments, share results)

**Expert Roundups**
15-30 experts answering one specific question. Built-in distribution.

**Case Studies**
Structure: Challenge → Solution → Results → Key learnings

**Meta Content**
Behind-the-scenes transparency. "How We Got Our First $5k MRR," "Why We Chose Debt Over VC."

For programmatic content at scale, see **programmatic-seo** skill.

---

## Content Pillars and Topic Clusters

Content pillars are the 3-5 core topics your brand will own. Each pillar spawns a cluster of related content.

Most of the time, all content can live under `/blog` with good internal linking between related posts. Dedicated pillar pages with custom URL structures (like `/guides/topic`) are only needed when you're building comprehensive resources with multiple layers of depth.

### How to Identify Pillars

1. **Product-led**: What problems does your product solve?
2. **Audience-led**: What does your ICP need to learn?
3. **Search-led**: What topics have volume in your space?
4. **Competitor-led**: What are competitors ranking for?

### Pillar Structure

```
Pillar Topic (Hub)
├── Subtopic Cluster 1
│   ├── Article A
│   ├── Article B
│   └── Article C
├── Subtopic Cluster 2
│   ├── Article D
│   ├── Article E
│   └── Article F
└── Subtopic Cluster 3
    ├── Article G
    ├── Article H
    └── Article I
```

### Pillar Criteria

Good pillars should:
- Align with your product/service
- Match what your audience cares about
- Have search volume and/or social interest
- Be broad enough for many subtopics

---

## Keyword Research by Buyer Stage

Map topics to the buyer's journey using proven keyword modifiers:

### Awareness Stage
Modifiers: "what is," "how to," "guide to," "introduction to"

Example: If customers ask about project management basics:
- "What is Agile Project Management"
- "Guide to Sprint Planning"
- "How to Run a Standup Meeting"

### Consideration Stage
Modifiers: "best," "top," "vs," "alternatives," "comparison"

Example: If customers evaluate multiple tools:
- "Best Project Management Tools for Remote Teams"
- "Asana vs Trello vs Monday"
- "Basecamp Alternatives"

### Decision Stage
Modifiers: "pricing," "reviews," "demo," "trial," "buy"

Example: If pricing comes up in sales calls:
- "Project Management Tool Pricing Comparison"
- "How to Choose the Right Plan"
- "[Product] Reviews"

### Implementation Stage
Modifiers: "templates," "examples," "tutorial," "how to use," "setup"

Example: If support tickets show implementation struggles:
- "Project Template Library"
- "Step-by-Step Setup Tutorial"
- "How to Use [Feature]"

---

## Content Ideation Sources

### 1. Keyword Data

If user provides keyword exports (Ahrefs, SEMrush, GSC), analyze for:
- Topic clusters (group related keywords)
- Buyer stage (awareness/consideration/decision/implementation)
- Search intent (informational, commercial, transactional)
- Quick wins (low competition + decent volume + high relevance)
- Content gaps (keywords competitors rank for that you don't)

Output as prioritized table:
| Keyword | Volume | Difficulty | Buyer Stage | Content Type | Priority |

### 2. Call Transcripts

If user provides sales or customer call transcripts, extract:
- Questions asked → FAQ content or blog posts
- Pain points → problems in their own words
- Objections → content to address proactively
- Language patterns → exact phrases to use (voice of customer)
- Competitor mentions → what they compared you to

Output content ideas with supporting quotes.

### 3. Survey Responses

If user provides survey data, mine for:
- Open-ended responses (topics and language)
- Common themes (30%+ mention = high priority)
- Resource requests (what they wish existed)
- Content preferences (formats they want)

### 4. Forum Research

Use web search to find content ideas:

**Reddit:** `site:reddit.com [topic]`
- Top posts in relevant subreddits
- Questions and frustrations in comments
- Upvoted answers (validates what resonates)

**Quora:** `site:quora.com [topic]`
- Most-followed questions
- Highly upvoted answers

**Other:** Indie Hackers, Hacker News, Product Hunt, industry Slack/Discord

Extract: FAQs, misconceptions, debates, problems being solved, terminology used.

### 5. Competitor Analysis

Use web search to analyze competitor content:

**Find their content:** `site:competitor.com/blog`

**Analyze:**
- Top-performing posts (comments, shares)
- Topics covered repeatedly
- Gaps they haven't covered
- Case studies (customer problems, use cases, results)
- Content structure (pillars, categories, formats)

**Identify opportunities:**
- Topics you can cover better
- Angles they're missing
- Outdated content to improve on

### 6. Sales and Support Input

Extract from customer-facing teams:
- Common objections
- Repeated questions
- Support ticket patterns
- Success stories
- Feature requests and underlying problems

---

## Prioritizing Content Ideas

Score each idea on four factors:

### 1. Customer Impact (40%)
- How frequently did this topic come up in research?
- What percentage of customers face this challenge?
- How emotionally charged was this pain point?
- What's the potential LTV of customers with this need?

### 2. Content-Market Fit (30%)
- Does this align with problems your product solves?
- Can you offer unique insights from customer research?
- Do you have customer stories to support this?
- Will this naturally lead to product interest?

### 3. Search Potential (20%)
- What's the monthly search volume?
- How competitive is this topic?
- Are there related long-tail opportunities?
- Is search interest growing or declining?

### 4. Resource Requirements (10%)
- Do you have expertise to create authoritative content?
- What additional research is needed?
- What assets (graphics, data, examples) will you need?

### Scoring Template

| Idea | Customer Impact (40%) | Content-Market Fit (30%) | Search Potential (20%) | Resources (10%) | Total |
|------|----------------------|-------------------------|----------------------|-----------------|-------|
| Topic A | 8 | 9 | 7 | 6 | 8.0 |
| Topic B | 6 | 7 | 9 | 8 | 7.1 |

---

## Output Format

When creating a content strategy, provide:

### 1. Content Pillars
- 3-5 pillars with rationale
- Subtopic clusters for each pillar
- How pillars connect to product

### 2. Priority Topics
For each recommended piece:
- Topic/title
- Searchable, shareable, or both
- Content type (use-case, hub/spoke, thought leadership, etc.)
- Target keyword and buyer stage
- Why this topic (customer research backing)

### 3. Topic Cluster Map
Visual or structured representation of how content interconnects.

---

## Task-Specific Questions

1. What patterns emerge from your last 10 customer conversations?
2. What questions keep coming up in sales calls?
3. Where are competitors' content efforts falling short?
4. What unique insights from customer research aren't being shared elsewhere?
5. Which existing content drives the most conversions, and why?

---

## Related Skills

- **copywriting**: For writing individual content pieces
- **seo-audit**: For technical SEO and on-page optimization
- **programmatic-seo**: For scaled content generation
- **email-sequence**: For email-based content
- **social-content**: For social media content
```

---

## Brevo Email Automation

Skill | 17 downloads | Email, Marketing Automation
https://marketingskills.directory/skills/brevo-automation/

"Automate Brevo (Sendinblue) tasks via Rube MCP (Composio): manage email campaigns, create/edit templates, track senders, and monitor campaign performance. Always search tools first for current schemas." requires: mcp: [rube]

### Full SKILL.md Content

```markdown
---
name: brevo-automation
description: "Automate Brevo (Sendinblue) tasks via Rube MCP (Composio): manage email campaigns, create/edit templates, track senders, and monitor campaign performance. Always search tools first for current schemas."
requires:
  mcp: [rube]
---

# Brevo Automation via Rube MCP

Automate Brevo (formerly Sendinblue) email marketing operations through Composio's Brevo toolkit via Rube MCP.

## Prerequisites

- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active Brevo connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `brevo`
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas

## Setup

**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.


1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `brevo`
3. If connection is not ACTIVE, follow the returned auth link to complete Brevo authentication
4. Confirm connection status shows ACTIVE before running any workflows

## Core Workflows

### 1. Manage Email Campaigns

**When to use**: User wants to list, review, or update email campaigns

**Tool sequence**:
1. `BREVO_LIST_EMAIL_CAMPAIGNS` - List all campaigns with filters [Required]
2. `BREVO_UPDATE_EMAIL_CAMPAIGN` - Update campaign content or settings [Optional]

**Key parameters for listing**:
- `type`: Campaign type ('classic' or 'trigger')
- `status`: Campaign status ('suspended', 'archive', 'sent', 'queued', 'draft', 'inProcess', 'inReview')
- `startDate`/`endDate`: Date range filter (YYYY-MM-DDTHH:mm:ss.SSSZ format)
- `statistics`: Stats type to include ('globalStats', 'linksStats', 'statsByDomain')
- `limit`: Results per page (max 100, default 50)
- `offset`: Pagination offset
- `sort`: Sort order ('asc' or 'desc')
- `excludeHtmlContent`: Set `true` to reduce response size

**Key parameters for update**:
- `campaign_id`: Numeric campaign ID (required)
- `name`: Campaign name
- `subject`: Email subject line
- `htmlContent`: HTML email body (mutually exclusive with `htmlUrl`)
- `htmlUrl`: URL to HTML content
- `sender`: Sender object with `name`, `email`, or `id`
- `recipients`: Object with `listIds` and `exclusionListIds`
- `scheduledAt`: Scheduled send time (YYYY-MM-DDTHH:mm:ss.SSSZ)

**Pitfalls**:
- `startDate` and `endDate` are mutually required; provide both or neither
- Date filters only work when `status` is not passed or set to 'sent'
- `htmlContent` and `htmlUrl` are mutually exclusive
- Campaign `sender` email must be a verified sender in Brevo
- A/B testing fields (`subjectA`, `subjectB`, `splitRule`, `winnerCriteria`) require `abTesting: true`
- `scheduledAt` uses full ISO 8601 format with timezone

### 2. Create and Manage Email Templates

**When to use**: User wants to create, edit, list, or delete email templates

**Tool sequence**:
1. `BREVO_GET_ALL_EMAIL_TEMPLATES` - List all templates [Required]
2. `BREVO_CREATE_OR_UPDATE_EMAIL_TEMPLATE` - Create a new template or update existing [Required]
3. `BREVO_DELETE_EMAIL_TEMPLATE` - Delete an inactive template [Optional]

**Key parameters for listing**:
- `templateStatus`: Filter active (`true`) or inactive (`false`) templates
- `limit`: Results per page (max 1000, default 50)
- `offset`: Pagination offset
- `sort`: Sort order ('asc' or 'desc')

**Key parameters for create/update**:
- `templateId`: Include to update; omit to create new
- `templateName`: Template display name (required for creation)
- `subject`: Email subject line (required for creation)
- `htmlContent`: HTML template body (min 10 characters; use this or `htmlUrl`)
- `sender`: Sender object with `name` and `email`, or `id` (required for creation)
- `replyTo`: Reply-to email address
- `isActive`: Activate or deactivate the template
- `tag`: Category tag for the template

**Pitfalls**:
- When `templateId` is provided, the tool updates; when omitted, it creates
- For creation, `templateName`, `subject`, and `sender` are required
- `htmlContent` must be at least 10 characters
- Template personalization uses `{{contact.ATTRIBUTE}}` syntax
- Only inactive templates can be deleted
- `htmlContent` and `htmlUrl` are mutually exclusive

### 3. Manage Senders

**When to use**: User wants to view authorized sender identities

**Tool sequence**:
1. `BREVO_GET_ALL_SENDERS` - List all verified senders [Required]

**Key parameters**: (none required)

**Pitfalls**:
- Senders must be verified before they can be used in campaigns or templates
- Sender verification is done through the Brevo web interface, not via API
- Sender IDs can be used in `sender.id` fields for campaigns and templates

### 4. Configure A/B Testing Campaigns

**When to use**: User wants to set up or modify A/B test settings on a campaign

**Tool sequence**:
1. `BREVO_LIST_EMAIL_CAMPAIGNS` - Find the target campaign [Prerequisite]
2. `BREVO_UPDATE_EMAIL_CAMPAIGN` - Configure A/B test settings [Required]

**Key parameters**:
- `campaign_id`: Campaign to configure
- `abTesting`: Set to `true` to enable A/B testing
- `subjectA`: Subject line for variant A
- `subjectB`: Subject line for variant B
- `splitRule`: Percentage split for the test (1-99)
- `winnerCriteria`: 'open' or 'click' for determining the winner
- `winnerDelay`: Hours to wait before selecting winner (1-168)

**Pitfalls**:
- A/B testing must be enabled (`abTesting: true`) before setting variant fields
- `splitRule` is the percentage of contacts that receive variant A
- `winnerDelay` defines how long to test before sending the winner to remaining contacts
- Only works with 'classic' campaign type

## Common Patterns

### Campaign Lifecycle

```
1. Create campaign (status: draft)
2. Set recipients (listIds)
3. Configure content (htmlContent or htmlUrl)
4. Optionally schedule (scheduledAt)
5. Send or schedule via Brevo UI (API update can set scheduledAt)
```

### Pagination

- Use `limit` (page size) and `offset` (starting index)
- Default limit is 50; max varies by endpoint (100 for campaigns, 1000 for templates)
- Increment `offset` by `limit` each page
- Check `count` in response to determine total available

### Template Personalization

```
- First name: {{contact.FIRSTNAME}}
- Last name: {{contact.LASTNAME}}
- Custom attribute: {{contact.CUSTOM_ATTRIBUTE}}
- Mirror link: {{mirror}}
- Unsubscribe link: {{unsubscribe}}
```

## Known Pitfalls

**Date Formats**:
- All dates use ISO 8601 with milliseconds: YYYY-MM-DDTHH:mm:ss.SSSZ
- Pass timezone in the date-time format for accurate results
- `startDate` and `endDate` must be used together

**Sender Verification**:
- All sender emails must be verified in Brevo before use
- Unverified senders cause campaign creation/update failures
- Use GET_ALL_SENDERS to check available verified senders

**Rate Limits**:
- Brevo API has rate limits per account plan
- Implement backoff on 429 responses
- Template operations have lower limits than read operations

**Response Parsing**:
- Response data may be nested under `data` or `data.data`
- Parse defensively with fallback patterns
- Campaign and template IDs are numeric integers

## Quick Reference

| Task | Tool Slug | Key Params |
|------|-----------|------------|
| List campaigns | BREVO_LIST_EMAIL_CAMPAIGNS | type, status, limit, offset |
| Update campaign | BREVO_UPDATE_EMAIL_CAMPAIGN | campaign_id, subject, htmlContent |
| List templates | BREVO_GET_ALL_EMAIL_TEMPLATES | templateStatus, limit, offset |
| Create template | BREVO_CREATE_OR_UPDATE_EMAIL_TEMPLATE | templateName, subject, htmlContent, sender |
| Update template | BREVO_CREATE_OR_UPDATE_EMAIL_TEMPLATE | templateId, htmlContent |
| Delete template | BREVO_DELETE_EMAIL_TEMPLATE | templateId |
| List senders | BREVO_GET_ALL_SENDERS | (none) |
```

---

## Landing Page CRO

Skill | 16 downloads | CRO
https://marketingskills.directory/skills/page-cro/

When the user wants to optimize, improve, or increase conversions on any marketing page — including homepage, landing pages, pricing pages, feature pages, or blog posts. Also use when the user says "CRO," "conversion rate optimization," "this page isn't converting," "improve conversions," or "why...

### Full SKILL.md Content

```markdown
---
name: page-cro
version: 1.0.0
description: When the user wants to optimize, improve, or increase conversions on any marketing page — including homepage, landing pages, pricing pages, feature pages, or blog posts. Also use when the user says "CRO," "conversion rate optimization," "this page isn't converting," "improve conversions," or "why isn't this page working." For signup/registration flows, see signup-flow-cro. For post-signup activation, see onboarding-cro. For forms outside of signup, see form-cro. For popups/modals, see popup-cro.
---

# Page Conversion Rate Optimization (CRO)

You are a conversion rate optimization expert. Your goal is to analyze marketing pages and provide actionable recommendations to improve conversion rates.

## Initial Assessment

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Before providing recommendations, identify:

1. **Page Type**: Homepage, landing page, pricing, feature, blog, about, other
2. **Primary Conversion Goal**: Sign up, request demo, purchase, subscribe, download, contact sales
3. **Traffic Context**: Where are visitors coming from? (organic, paid, email, social)

---

## CRO Analysis Framework

Analyze the page across these dimensions, in order of impact:

### 1. Value Proposition Clarity (Highest Impact)

**Check for:**
- Can a visitor understand what this is and why they should care within 5 seconds?
- Is the primary benefit clear, specific, and differentiated?
- Is it written in the customer's language (not company jargon)?

**Common issues:**
- Feature-focused instead of benefit-focused
- Too vague or too clever (sacrificing clarity)
- Trying to say everything instead of the most important thing

### 2. Headline Effectiveness

**Evaluate:**
- Does it communicate the core value proposition?
- Is it specific enough to be meaningful?
- Does it match the traffic source's messaging?

**Strong headline patterns:**
- Outcome-focused: "Get [desired outcome] without [pain point]"
- Specificity: Include numbers, timeframes, or concrete details
- Social proof: "Join 10,000+ teams who..."

### 3. CTA Placement, Copy, and Hierarchy

**Primary CTA assessment:**
- Is there one clear primary action?
- Is it visible without scrolling?
- Does the button copy communicate value, not just action?
  - Weak: "Submit," "Sign Up," "Learn More"
  - Strong: "Start Free Trial," "Get My Report," "See Pricing"

**CTA hierarchy:**
- Is there a logical primary vs. secondary CTA structure?
- Are CTAs repeated at key decision points?

### 4. Visual Hierarchy and Scannability

**Check:**
- Can someone scanning get the main message?
- Are the most important elements visually prominent?
- Is there enough white space?
- Do images support or distract from the message?

### 5. Trust Signals and Social Proof

**Types to look for:**
- Customer logos (especially recognizable ones)
- Testimonials (specific, attributed, with photos)
- Case study snippets with real numbers
- Review scores and counts
- Security badges (where relevant)

**Placement:** Near CTAs and after benefit claims

### 6. Objection Handling

**Common objections to address:**
- Price/value concerns
- "Will this work for my situation?"
- Implementation difficulty
- "What if it doesn't work?"

**Address through:** FAQ sections, guarantees, comparison content, process transparency

### 7. Friction Points

**Look for:**
- Too many form fields
- Unclear next steps
- Confusing navigation
- Required information that shouldn't be required
- Mobile experience issues
- Long load times

---

## Output Format

Structure your recommendations as:

### Quick Wins (Implement Now)
Easy changes with likely immediate impact.

### High-Impact Changes (Prioritize)
Bigger changes that require more effort but will significantly improve conversions.

### Test Ideas
Hypotheses worth A/B testing rather than assuming.

### Copy Alternatives
For key elements (headlines, CTAs), provide 2-3 alternatives with rationale.

---

## Page-Specific Frameworks

### Homepage CRO
- Clear positioning for cold visitors
- Quick path to most common conversion
- Handle both "ready to buy" and "still researching"

### Landing Page CRO
- Message match with traffic source
- Single CTA (remove navigation if possible)
- Complete argument on one page

### Pricing Page CRO
- Clear plan comparison
- Recommended plan indication
- Address "which plan is right for me?" anxiety

### Feature Page CRO
- Connect feature to benefit
- Use cases and examples
- Clear path to try/buy

### Blog Post CRO
- Contextual CTAs matching content topic
- Inline CTAs at natural stopping points

---

## Experiment Ideas

When recommending experiments, consider tests for:
- Hero section (headline, visual, CTA)
- Trust signals and social proof placement
- Pricing presentation
- Form optimization
- Navigation and UX

**For comprehensive experiment ideas by page type**: See [references/experiments.md](references/experiments.md)

---

## Task-Specific Questions

1. What's your current conversion rate and goal?
2. Where is traffic coming from?
3. What does your signup/purchase flow look like after this page?
4. Do you have user research, heatmaps, or session recordings?
5. What have you already tried?

---

## Related Skills

- **signup-flow-cro**: If the issue is in the signup process itself
- **form-cro**: If forms on the page need optimization
- **popup-cro**: If considering popups as part of the strategy
- **copywriting**: If the page needs a complete copy rewrite
- **ab-test-setup**: To properly test recommended changes
```

---

## Duration Governance

Skill | 16 downloads
https://marketingskills.directory/skills/duration-governance/

Monitor and govern automated AI tasks for time spent, API costs, and error rates. Detect compounding errors, recommend kill switches, and generate monitoring code. Use when analyzing multi-step AI workflows, debugging expensive automations, or implementing cost controls.

### Full SKILL.md Content

```markdown
---
name: duration-governance
description: Monitor and govern automated AI tasks for time spent, API costs, and error rates. Detect compounding errors, recommend kill switches, and generate monitoring code. Use when analyzing multi-step AI workflows, debugging expensive automations, or implementing cost controls.
---

# Duration Governance

Monitor, analyze, and control the **time and cost** of multi-step AI automation workflows.

## The Problem

Multi-step AI workflows suffer from **compounding error rates**:
- A workflow with 95% accuracy per step over 20 steps = **36% success rate**
- Small errors at Step 3 compound into expensive failures at Step 18
- By the time humans notice, agents have burned significant compute creating liabilities

**Example math:**
- Single agent with retry loops: $2,500/month
- 500 agents × $50/day errors = **$750k/month waste**

## What This Skill Teaches

How to implement **Duration Governance**: tracking time, cost, and errors across automated tasks to prevent invisible budget leaks.

### Core Metrics to Track

1. **Time Spent** — wall-clock duration per task
2. **API Costs** — cumulative $ spent (LLM calls, external APIs)
3. **Error Rate** — failures, retries, drift events

### When to Use This Skill

Trigger this skill when:
- Building multi-step AI automation
- Debugging expensive workflows
- Setting up cost monitoring
- Analyzing task performance
- Implementing kill switches
- User asks about "duration governance", "task budgets", "automation costs"

---

## 1. Instrumentation Patterns

### Basic Task Logging Schema

Every automated task should log:

```python
{
  "task_id": "uuid",
  "task_type": "content_pipeline | rank_check | audit | email_response",
  "started_at": "2026-02-10T14:30:00Z",
  "ended_at": "2026-02-10T14:35:23Z",
  "duration_seconds": 323,
  "status": "success | failed | killed",
  "cost_usd": 0.45,
  "steps_completed": 12,
  "steps_total": 12,
  "errors": [
    {
      "step": 4,
      "type": "api_error | hallucination | timeout",
      "message": "Vendor name drift detected",
      "cost_impact_usd": 0.12
    }
  ],
  "kill_reason": null  # or "budget_exceeded | timeout | error_threshold"
}
```

### Database Table (Recommended)

```sql
CREATE TABLE task_runs (
  id UUID PRIMARY KEY,
  task_type VARCHAR(100) NOT NULL,
  started_at TIMESTAMP NOT NULL,
  ended_at TIMESTAMP,
  duration_seconds INTEGER,
  status VARCHAR(20),
  cost_usd DECIMAL(10,4),
  steps_completed INTEGER,
  steps_total INTEGER,
  error_count INTEGER DEFAULT 0,
  kill_reason VARCHAR(100),
  metadata JSONB,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_task_runs_type_status ON task_runs(task_type, status);
CREATE INDEX idx_task_runs_started ON task_runs(started_at DESC);
CREATE INDEX idx_task_runs_cost ON task_runs(cost_usd DESC);
```

---

## 2. Instrumentation Code Examples

### Python Decorator Pattern

```python
import time
from functools import wraps
from decimal import Decimal
import logging

logger = logging.getLogger(__name__)

class TaskMonitor:
    def __init__(self, db_session):
        self.db = db_session
        
    def track_task(self, task_type: str, cost_limit_usd: float = None, 
                   time_limit_seconds: int = None):
        """
        Decorator to track task duration, cost, and errors.
        
        Usage:
            @task_monitor.track_task("content_pipeline", cost_limit_usd=5.0)
            async def generate_content(topic: str):
                ...
        """
        def decorator(func):
            @wraps(func)
            async def wrapper(*args, **kwargs):
                task_id = uuid.uuid4()
                started_at = datetime.utcnow()
                cost_tracker = CostTracker()
                error_log = []
                
                try:
                    # Inject cost tracker into function context
                    kwargs['_cost_tracker'] = cost_tracker
                    kwargs['_error_log'] = error_log
                    
                    result = await func(*args, **kwargs)
                    
                    # Check cost limit
                    if cost_limit_usd and cost_tracker.total > cost_limit_usd:
                        raise BudgetExceededError(
                            f"Task exceeded ${cost_limit_usd} limit (spent ${cost_tracker.total})"
                        )
                    
                    # Log success
                    self._log_task(
                        task_id=task_id,
                        task_type=task_type,
                        started_at=started_at,
                        ended_at=datetime.utcnow(),
                        status="success",
                        cost_usd=cost_tracker.total,
                        errors=error_log
                    )
                    
                    return result
                    
                except Exception as e:
                    # Log failure
                    self._log_task(
                        task_id=task_id,
                        task_type=task_type,
                        started_at=started_at,
                        ended_at=datetime.utcnow(),
                        status="failed",
                        cost_usd=cost_tracker.total,
                        errors=error_log + [{"type": "exception", "message": str(e)}],
                        kill_reason=type(e).__name__
                    )
                    raise
                    
            return wrapper
        return decorator
    
    def _log_task(self, task_id, task_type, started_at, ended_at, 
                  status, cost_usd, errors, kill_reason=None):
        duration = (ended_at - started_at).total_seconds()
        
        self.db.execute(
            """
            INSERT INTO task_runs 
            (id, task_type, started_at, ended_at, duration_seconds, 
             status, cost_usd, error_count, kill_reason, metadata)
            VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
            """,
            (task_id, task_type, started_at, ended_at, int(duration),
             status, cost_usd, len(errors), kill_reason, json.dumps({"errors": errors}))
        )
        self.db.commit()
        
        logger.info(
            f"Task {task_type} [{task_id}]: {status} in {duration:.1f}s, "
            f"cost ${cost_usd:.4f}, {len(errors)} errors"
        )

class CostTracker:
    def __init__(self):
        self.total = Decimal('0.00')
        self.breakdown = []
    
    def add(self, cost: float, label: str):
        self.total += Decimal(str(cost))
        self.breakdown.append({"label": label, "cost": cost})
        
    def add_llm_call(self, model: str, input_tokens: int, output_tokens: int):
        cost = calculate_llm_cost(model, input_tokens, output_tokens)
        self.add(cost, f"LLM: {model}")
```

### Usage in Task Function

```python
@task_monitor.track_task("seo_content_pipeline", cost_limit_usd=5.0, time_limit_seconds=600)
async def generate_seo_article(topic: str, _cost_tracker=None, _error_log=None):
    # Step 1: Generate outline
    outline_response = await llm.complete("gpt-4", f"Create outline for {topic}")
    _cost_tracker.add_llm_call("gpt-4", outline_response.input_tokens, outline_response.output_tokens)
    
    # Step 2: Validate outline
    if not validate_outline(outline_response.text):
        _error_log.append({
            "step": 2,
            "type": "validation_failed",
            "message": "Outline missing key sections"
        })
        raise ValidationError("Invalid outline structure")
    
    # Step 3-12: Continue pipeline...
    # Each step logs cost and errors
    
    return final_article
```

---

## 3. Analysis Queries

### Daily Cost Summary

```sql
SELECT 
  task_type,
  DATE(started_at) as date,
  COUNT(*) as runs,
  SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) as successes,
  SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) as failures,
  ROUND(AVG(duration_seconds), 1) as avg_duration_sec,
  ROUND(SUM(cost_usd), 2) as total_cost_usd,
  ROUND(AVG(cost_usd), 4) as avg_cost_usd
FROM task_runs
WHERE started_at >= NOW() - INTERVAL '7 days'
GROUP BY task_type, DATE(started_at)
ORDER BY date DESC, total_cost_usd DESC;
```

### Find Expensive Failures

```sql
SELECT 
  id,
  task_type,
  started_at,
  duration_seconds,
  cost_usd,
  error_count,
  kill_reason,
  metadata->>'errors' as error_details
FROM task_runs
WHERE status = 'failed' 
  AND cost_usd > 1.0
ORDER BY cost_usd DESC
LIMIT 20;
```

### Calculate Compounding Error Rate

```python
def calculate_workflow_success_rate(per_step_accuracy: float, num_steps: int) -> float:
    """
    Calculate actual success rate for multi-step workflow.
    
    Example:
        95% per-step accuracy over 20 steps = 35.8% overall success
    """
    return per_step_accuracy ** num_steps

def analyze_pipeline_drift(task_type: str, days: int = 7):
    """
    Detect if error rates are increasing over time.
    """
    query = """
    SELECT 
      DATE(started_at) as date,
      COUNT(*) as total_runs,
      AVG(error_count) as avg_errors_per_run,
      SUM(cost_usd) as daily_cost
    FROM task_runs
    WHERE task_type = %s 
      AND started_at >= NOW() - INTERVAL '%s days'
    GROUP BY DATE(started_at)
    ORDER BY date;
    """
    
    results = db.execute(query, (task_type, days))
    
    # Detect if avg errors trending up
    error_trend = [r['avg_errors_per_run'] for r in results]
    if len(error_trend) >= 3:
        recent_avg = sum(error_trend[-3:]) / 3
        older_avg = sum(error_trend[:3]) / 3
        if recent_avg > older_avg * 1.5:
            return {
                "status": "WARNING",
                "message": f"Error rate increased 50%+ in last 3 days",
                "older_avg": older_avg,
                "recent_avg": recent_avg
            }
    
    return {"status": "OK"}
```

---

## 4. Kill Switch Patterns

### Budget Kill Switch

```python
class BudgetKillSwitch:
    def __init__(self, limit_usd: float):
        self.limit = limit_usd
        self.spent = Decimal('0.00')
    
    def check(self, new_cost: float):
        self.spent += Decimal(str(new_cost))
        if self.spent > self.limit:
            raise BudgetExceededError(
                f"Task budget ${self.limit} exceeded (spent ${self.spent})"
            )

# Usage in workflow
kill_switch = BudgetKillSwitch(limit_usd=5.0)

for step in pipeline_steps:
    result, cost = await step.execute()
    kill_switch.check(cost)
```

### Time Kill Switch

```python
from contextlib import asynccontextmanager
import asyncio

@asynccontextmanager
async def time_limit(seconds: int):
    """
    Context manager to enforce time limits on tasks.
    
    Usage:
        async with time_limit(300):  # 5 minutes
            await long_running_task()
    """
    async def timeout():
        await asyncio.sleep(seconds)
        raise TimeoutError(f"Task exceeded {seconds}s limit")
    
    timeout_task = asyncio.create_task(timeout())
    
    try:
        yield
        timeout_task.cancel()
    except Exception:
        timeout_task.cancel()
        raise
```

### Drift Gate Pattern

```python
class DriftGate:
    """
    Detect when task behavior changes unexpectedly.
    """
    def __init__(self, task_type: str, window_size: int = 100):
        self.task_type = task_type
        self.window_size = window_size
        self.baseline = self._get_baseline()
    
    def _get_baseline(self):
        """Get average duration + cost for recent successful runs."""
        query = """
        SELECT 
          AVG(duration_seconds) as avg_duration,
          AVG(cost_usd) as avg_cost
        FROM task_runs
        WHERE task_type = %s 
          AND status = 'success'
          AND started_at >= NOW() - INTERVAL '7 days'
        """
        result = db.execute(query, (self.task_type,)).fetchone()
        return {
            "avg_duration": result['avg_duration'] or 60,
            "avg_cost": result['avg_cost'] or 0.50
        }
    
    def check(self, duration: float, cost: float):
        """Flag if current run deviates >2x from baseline."""
        if duration > self.baseline['avg_duration'] * 2:
            logger.warning(
                f"Drift detected: duration {duration}s vs baseline {self.baseline['avg_duration']}s"
            )
        
        if cost > self.baseline['avg_cost'] * 2:
            logger.warning(
                f"Drift detected: cost ${cost} vs baseline ${self.baseline['avg_cost']}"
            )
```

---

## 5. Monitoring Dashboard Queries

### Real-Time Task Health

```sql
-- Last 100 task runs with health indicators
SELECT 
  task_type,
  started_at,
  duration_seconds,
  cost_usd,
  status,
  error_count,
  CASE 
    WHEN cost_usd > (
      SELECT AVG(cost_usd) * 2 
      FROM task_runs t2 
      WHERE t2.task_type = t1.task_type 
        AND t2.status = 'success'
    ) THEN 'COST_ANOMALY'
    WHEN duration_seconds > (
      SELECT AVG(duration_seconds) * 2 
      FROM task_runs t2 
      WHERE t2.task_type = t1.task_type 
        AND t2.status = 'success'
    ) THEN 'DURATION_ANOMALY'
    WHEN error_count > 3 THEN 'HIGH_ERRORS'
    ELSE 'OK'
  END as health_flag
FROM task_runs t1
ORDER BY started_at DESC
LIMIT 100;
```

### Cost Leaderboard (Top Spenders)

```sql
SELECT 
  task_type,
  SUM(cost_usd) as total_cost_7d,
  COUNT(*) as runs,
  ROUND(AVG(cost_usd), 4) as avg_cost_per_run,
  SUM(CASE WHEN status = 'failed' THEN cost_usd ELSE 0 END) as wasted_on_failures
FROM task_runs
WHERE started_at >= NOW() - INTERVAL '7 days'
GROUP BY task_type
ORDER BY total_cost_7d DESC;
```

---

## 6. Alert Rules (When to Notify)

Trigger alerts when:

1. **Single task cost > $10** (possible runaway)
2. **Daily cost for task type > 2x weekly average**
3. **Error rate > 30% for task type** (over last hour)
4. **Any task duration > 30 minutes** (stuck?)
5. **Drift detected:** duration or cost > 2x baseline

Example alert function:

```python
def check_alerts():
    alerts = []
    
    # Check for expensive single tasks
    expensive = db.execute("""
        SELECT id, task_type, cost_usd 
        FROM task_runs 
        WHERE cost_usd > 10 
          AND started_at >= NOW() - INTERVAL '1 hour'
    """).fetchall()
    
    for task in expensive:
        alerts.append({
            "severity": "HIGH",
            "message": f"Task {task['id']} cost ${task['cost_usd']:.2f}",
            "type": "expensive_task"
        })
    
    # Check error rate spike
    error_rate = db.execute("""
        SELECT 
          task_type,
          COUNT(*) as total,
          SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) as failures
        FROM task_runs
        WHERE started_at >= NOW() - INTERVAL '1 hour'
        GROUP BY task_type
        HAVING SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END)::float / COUNT(*) > 0.3
    """).fetchall()
    
    for task in error_rate:
        alerts.append({
            "severity": "MEDIUM",
            "message": f"{task['task_type']} error rate: {task['failures']}/{task['total']}",
            "type": "high_error_rate"
        })
    
    return alerts
```

---

## 7. Cost Calculation Helpers

### LLM Pricing Table (2026)

```python
LLM_PRICING = {
    # Model: (input_cost_per_1M_tokens, output_cost_per_1M_tokens)
    "gpt-4": (30.00, 60.00),
    "gpt-4-turbo": (10.00, 30.00),
    "gpt-3.5-turbo": (0.50, 1.50),
    "claude-opus-4": (15.00, 75.00),
    "claude-sonnet-4": (3.00, 15.00),
    "gemini-pro": (0.50, 1.50),
}

def calculate_llm_cost(model: str, input_tokens: int, output_tokens: int) -> float:
    """Calculate cost for LLM API call."""
    if model not in LLM_PRICING:
        logger.warning(f"Unknown model {model}, using default pricing")
        input_cost, output_cost = 5.00, 15.00
    else:
        input_cost, output_cost = LLM_PRICING[model]
    
    total_cost = (
        (input_tokens / 1_000_000) * input_cost +
        (output_tokens / 1_000_000) * output_cost
    )
    
    return round(total_cost, 6)
```

---

## Quick Start Checklist

To add Duration Governance to a project:

1. **Create task_runs table** (see schema above)
2. **Add TaskMonitor class** to your project
3. **Wrap automated functions** with `@track_task` decorator
4. **Set cost/time limits** based on expected task value
5. **Add kill switches** for budget and time
6. **Create alerts** for expensive failures
7. **Dashboard** → query task_runs for daily summaries

---

## Key Gotchas

1. **Don't log synchronously** — use async inserts or queue to avoid blocking tasks
2. **Timestamp precision** — use UTC always, store with timezone
3. **Cost attribution** — track which step/API caused each cost, not just totals
4. **Baseline drift** — recalculate baselines weekly as workflows improve
5. **Alert fatigue** — start with high thresholds, tune down based on real failures

---

## Example Output (When Analyzing a Workflow)

```
📊 Duration Governance Report: seo_content_pipeline

Time Range: Last 7 days
Total Runs: 247
Success Rate: 78% (193 success, 54 failed)

💰 Cost Analysis:
  Total Spent: $1,247.80
  Avg per Run: $5.05
  Wasted (failures): $312.40 (25%)

⏱️ Duration Analysis:
  Avg Duration: 4m 23s
  Longest: 18m 12s (killed: timeout)
  Shortest: 1m 45s

⚠️ Compounding Error Analysis:
  Steps per Run: 12
  Per-Step Accuracy: 92%
  Predicted Success Rate: 36.9%
  Actual Success Rate: 78%
  ✅ Better than predicted (good breakpoint validation)

🚨 Issues Detected:
  - 14 tasks exceeded $10 budget (avg: $12.40)
  - 3 tasks exceeded 15min timeout
  - Error rate spiked 40% on Feb 8 (vendor API change)

💡 Recommendations:
  1. Add budget kill switch at $8 (before $10 failures)
  2. Add breakpoint validation at Step 6 (highest error step)
  3. Reduce timeout to 10min (18min outliers are failures anyway)
  4. Monitor vendor API response times (new drift pattern)

Estimated Monthly Savings: $468/month
```

---

## When NOT to Use This

- Single-step, one-off tasks (overhead not worth it)
- Tasks that cost <$0.01 (logging costs more than insights)
- Purely deterministic workflows with no API calls

---

## Further Reading

- Original concept: Srini Annamaraju (LinkedIn, Feb 2026)
- Compounding probability: https://en.wikipedia.org/wiki/Compound_probability
- OpenTelemetry for distributed tracing: https://opentelemetry.io/

---

**Status:** Production-ready  
**Last Updated:** 2026-02-10  
**Maintained by:** Sandeep Kelvadi / Thrivemattic
```

---