content-brief

Files (6)

• SKILL.md
• error-handling.md · references/
• notion-schema.md · references/
• routing-logic.md · references/
• brief_validator.py · scripts/
• text_parser.py · scripts/

SKILL.md (first lines)

# Content Brief — Keyword-to-Notion Brief Generator

Generates a structured SEO content brief from a target keyword. Output follows the mandatory Direction prompt format so the `text_parser.py` script can extract every field for Notion without manual cleanup.

## Invocation Triggers

**Explicit phrases** (any of):
- "create a content brief for [keyword]"
- "brief this keyword: [keyword]"
- "content brief on [topic]"
- "generate a brief for [keyword]"
- "write a brief for [keyword]"
- "run the content brief skill"

**Implicit signals:**
- User provides a keyword and asks for an SEO spec, editorial spec, or writing assignment
- User pastes a keyword list and asks for briefs

When triggered, run immediately — no upfront intake beyond the keyword itself.

## Grill-Me Intake (One Question, Optional)

Run the brief without questions when the keyword is clear.

Ask **one** clarifying question only when **both** are true:
1. The target audience or client is not inferrable from context
2. Audience changes the content angle meaningfully (e.g., "project management software" could target PMs or developers)

> **Quick clarification — who is the primary audience for "[keyword]"?**
> 1. [Inferred persona A — e.g., HR Director]
> 2. [Inferred persona B — e.g., Operations Manager]
> 3. Tell me
>
> *Why I'm asking: audience shapes the H1, content angle, and writer notes. One question prevents a wrong brief.*

Max one question. If audience is inferable, skip and proceed.

## Data Gathering (Before Writing the Brief)

Run these steps before generating the Direction prompt output:

### Step 1 — Keyword Metrics
**Preferred:** Ahrefs MCP (`keywords_explorer_overview`) → volume, KD, CPC, SERP data.

**Fallback (no Ahrefs MCP):** Use WebSearch to estimate:
- Search `[keyword] search volume KD CPC site:ahrefs.com OR site:semrush.com OR site:moz.com`
- Extract available volume/KD/CPC estimates
- If no data found, set VOLUME/CPC/DIFFICULTY to `[not available — add manually]`

### Step 2 — Competitor H2/H3 Analysis
- WebSearch `[keyword]` → identify top 3 organic results (skip ads, maps, featured snippets)
- WebFetch each URL → extract all H2 and H3 headings
- Note: competitor structure informs the H2_OUTLINE. Do not copy — use as gap analysis.

### Step 3 — Search Intent Classification
Based on keyword + SERP type, classify as one of exactly four options:
- `Informational` — user wants to learn
- `Commercial` — user is comparing options before buying
- `Transactional` — user is ready to act/purchase
- `Navigational` — user seeks a specific brand/site

### Step 4 — Priority Scoring
Apply routing logic from `references/routing-logic.md`:
- HIGH: Volume > 200 AND KD < 40 AND intent is Commercial or Transactional
- MEDIUM: Doesn't meet HIGH criteria but has meaningful volume or strategic importance
- LOW: Low volume, high difficulty, or informational with limited conversion value

## Direction Prompt Output Format (Mandatory)

**This format is non-negotiable.** The `text_parser.py` script performs label-exact extraction. If any label deviates from the format below — wrong case, extra space, missing underscore — the Notion property will arrive empty.

After data gathering, output the brief using EXACTLY this structure:

```
TARGET_KEYWORD: [keyword]
VOLUME: [number or "not available"]
CPC: [decimal or "not available"]
DIFFICULTY: [0-100 integer or "not available"]
SEARCH_INTENT: [Informational | Commercial | Transactional | Navigational]
AUDIENCE: [persona — job title or role]
RECOMMENDED_H1: [final proposed title]
CONTENT_ANGLE: [one paragraph describing the unique angle, why this beats competitors, what the post must do]
WORD_COUNT: [number]
SCHEMA: [schema type — e.g., FAQ, HowTo, Article, FAQ + HowTo]
PRIORITY: [HIGH | MEDIUM | LOW]
H2_OUTLINE:
- H2: [heading]
  - H3: [subheading]
  - H3: [subheading]
- H2: [heading]
  - H3: [subheading]
FAQ:
- Q: [question the audience actually searches]
- Q: [question]
- Q: [question]
INTERNAL_LINKS:
- [anchor text] → [relative URL or page title if URL unknown]
WRITER_NOTES:
[one paragraph of specific guidance: tone, POV, what to avoid, key differentiators to emphasize, CTAs, any client-specific requirements]
```

**Critical rules:**
- Every field label must appear exactly as shown (ALL_CAPS with underscores)
- SEARCH_INTENT value must exactly match one of the four options (capitalized)
- PRIORITY value must be exactly HIGH, MEDIUM, or LOW
- H2_OUTLINE, FAQ, INTERNAL_LINKS, WRITER_NOTES are block fields — content follows on the next line(s)
- No additional text before TARGET_KEYWORD or after WRITER_NOTES block

## Workflow Architecture (9 Nodes)

| Node | Role | Tool |
|---|---|---|
| 1 — Input | Accept keyword + optional client/audience context | User message |
| 2 — Keyword Metrics | Pull volume, KD, CPC, SERP type | Ahrefs MCP OR WebSearch fallback |
| 3 — SERP Scrape | Extract H2/H3 from top 3 organic results | WebFetch |
| 4 — Brief Generation | Process data through Direction prompt → structured output | Claude (this skill) |
| 5 — Text Parser | Extract labeled fields → structured variables | `scripts/text_parser.py` |
| 6 — Conditional Router | Route based on PRIORITY value | Routing logic |
| 7A — Notion Create (HIGH) | Create page, Status = "Briefed: Ready for Assignment" | Notion MCP |

From Infrasity-Labs/dev-gtm-claude-skills, MIT.

More from Infrasity-Labs/dev-gtm-claude-skills