content-brief-factory

# Content Brief Factory

Most content briefs are garbage. They tell you "mention these keywords 7 times" and call it a strategy. This skill produces briefs that include competitive analysis, unique angles mined from what real customers say, SERP feature targeting, and a differentiated outline — so your writer knows exactly what to create and why it'll rank.

**Core principle:** A great brief doesn't just say "write about X." It says "here's what's already ranking, here's why it's winning, here's the gap they missed, here's the customer language that proves the gap matters, and here's exactly how to structure a page that beats them."

**Batch mode:** Process 10-50 keywords in a single run. Each brief takes ~30 seconds in enhanced mode, ~60 seconds in baseline.

## When to Use

- "Create content briefs for these keywords"
- "I need briefs for our Q2 content calendar"
- "Write briefs for our pSEO templates"
- "Generate 20 briefs from this keyword list"
- "What should we write about [topic]? Give me a full brief."

## Tool Enhancement (Optional)

Briefs are significantly better with real SERP data (what's actually ranking, what SERP features appear) rather than inferred analysis.

### Agent Prompt to User

> "I can create strong content briefs using competitive research and customer language mining. For the best results — especially accurate SERP analysis and keyword metrics — I'd recommend connecting a SERP data API."
>
> **Recommended: SerpAPI** (100 free searches/month, $50/month for 5,000)
> - Sign up at serpapi.com → get API key
> - Set `SERPAPI_KEY` env var
>
> **Alternatives that also work:**
> - **Serper.dev** (2,500 free searches, then $50/month for 50K) → set `SERPER_API_KEY`
> - **DataForSEO SERP** (pay-per-use, ~$0.01/search) → set `DATAFORSEO_LOGIN` + `DATAFORSEO_PASSWORD`
> - **ValueSERP** (free tier available) → set `VALUESERP_API_KEY`
>
> "Want to use one of these, or should I proceed with baseline mode? Baseline uses web search to analyze competing pages — still produces great briefs, just with less precise SERP feature and volume data."

### Mode Selection

- **Enhanced mode** — Real SERP data per keyword: exact ranking pages, SERP features present (featured snippets, PAA, video carousels), search volume, keyword difficulty. Briefs include specific "win this SERP feature" targeting.
- **Baseline mode** — Uses `web_search` to identify top-ranking pages, `seo-domain-analyzer` for domain metrics. SERP feature detection is inferred. Still produces excellent briefs — the competitive analysis and customer language components don't need SERP APIs.

## Phase 0: Intake

1. **Keywords** — List of target keywords (1-50). Can be:
   - Pasted list
   - CSV file
   - Output from `seo-opportunity-finder`
   - Output from `programmatic-seo-planner` (template keywords)
2. **Your site URL** — So we check for existing coverage
3. **ICP** — Who's reading this content? (role, pain, goal)
4. **Brand voice** — Formal/casual/technical? (or link to brand voice doc)
5. **Content type preference** — Blog posts, landing pages, guides, glossary entries?
6. **Brief depth** — Standard (outline + angle + competitors) or Deep (all of the above + customer quotes + SERP feature targeting + internal links)?
7. **Tool preference** — Enhanced mode with SERP API, or baseline? (see Tool Enhancement above)

## Phase 1: Existing Coverage Check

Run `site-content-catalog` on your site:

```bash
python3 skills/site-content-catalog/scripts/catalog_content.py \
  --url "<your_site_url>" \
  --output json
```

For each target keyword, check:
- Do you already have a page targeting this keyword? → **Update brief** (not new page)
- Do you have related pages that should link to this? → **Internal link candidates**
- What content gaps exist? → Confirms keyword is worth targeting

## Phase 2: Per-Keyword Analysis (Batch)

For each keyword, run in parallel where possible:

### 2A: SERP Analysis

**Enhanced mode (SerpAPI / Serper / DataForSEO):**

```
# SerpAPI example
GET https://serpapi.com/search?q={keyword}&api_key={key}&num=10
```

Extract per keyword:
- Top 10 ranking URLs
- SERP features present (featured snippet, PAA, video, knowledge panel, images)
- Featured snippet holder (if any) + snippet content
- People Also Ask questions (top 5)
- Related searches
- Search volume + keyword difficulty (if available from API)

**Baseline mode:**

Use `web_search` for each keyword:
- Note top 5-10 results
- Identify obvious SERP features from result format
- Use `seo-domain-analyzer` for volume/difficulty estimates

### 2B: Competing Page Analysis

For top 3-5 ranking pages per keyword, fetch via `fetch_webpage`:

Analyze each:
- **Word count** — How long are ranking pages?
- **Structure** — H1, H2 outline, content flow
- **Content type** — How-to, listicle, comparison, guide, definition
- **Unique data** — Do they include original research, surveys, screenshots?
- **Freshness** — When was it last updated?
- **Depth score** — Thin overview vs. comprehensive resource
- **Missing topics** — What did they NOT cover that they should have?

### 2C: Customer Language Mining

Run `review-site-scraper` + `reddit-post-finder` for the topic:

```bash
# Reviews — find how ICP talks about this problem
python3 skills/capabilities/review-site-scraper/scripts/scrape_reviews.py \
  --platform g2 \
  --url "<relevant_product_review_url>" \
  --output json

# Reddit — find real questions and pain language
python3 skills/reddit-post-finder/scripts/search_reddit.py \
  --subreddit "<relevant_subs>" \
  --keywords "<keyword>,<topic>" \
  --days 365 --sort top --time year
```

Extract:
- **Real questions people ask** about this topic → sections to include
- **Pain language** → angle for the intro hook
- **Misconceptions** → myth-busting section opportunity
- **Specific use cases** → concrete examples to include
- **Quotes** → proof points to weave into content

## Phase 3: Brief Generation

For each keyword, produce:

```markdown
# Content Brief: [Targ