Content Brief Creator

Content Brief Creator

MCP Tool Requirements

Tool loading (harness-aware)

In Claude Code: DataForSEO and GSC tools are deferred, load them via ToolSearch before use. In other harnesses (e.g. Hermes): use the equivalent DataForSEO/GSC tools if exposed; otherwise use the documented fallbacks (the workflow MUST complete without them).

Claude Code, at workflow start:

ToolSearch: "select:mcp__dataforseo__serp_organic_live_advanced"
ToolSearch: "select:mcp__dataforseo__kw_data_google_ads_search_volume"
ToolSearch: "select:mcp__dataforseo__dataforseo_labs_google_keyword_suggestions"
ToolSearch: "select:mcp__dataforseo__dataforseo_labs_bulk_keyword_difficulty"
ToolSearch: "select:mcp__dataforseo__dataforseo_labs_search_intent"
ToolSearch: "select:mcp__dataforseo__on_page_content_parsing"
ToolSearch: "select:mcp__gsc-mcp__get_search_analytics"
ToolSearch: "select:mcp__gsc-mcp__inspect_url_enhanced"

Additional for --refresh mode:

ToolSearch: "select:mcp__crawl4ai__crawl_url"  # Crawl existing article for baseline

Tool Reference Table

Fallback Strategy

The skill MUST work even when DataForSEO is completely unavailable.

AT WORKFLOW START:
  Attempt to load DataForSEO tools via ToolSearch

  IF DataForSEO tools load successfully:
    Use DataForSEO tools (faster, more structured data)

  ELSE (DataForSEO unavailable):
    Notify user: "DataForSEO MCP not available. Using WebSearch fallback for all data."

    Fallback mapping:
    - Stage 2a (SERP): WebSearch for "[keyword]" → extract top 10 results
    - Stage 3a (Keyword metrics): WebSearch for "[keyword] search volume" → extract estimates
    - Stage 3b (Secondary keywords): WebSearch for "keywords related to [keyword]" → extract suggestions
    - Stage 3c (Batch difficulty): SKIP (no fallback needed)
    - Stage 3d (Intent): AI analysis based on SERP composition (X blog posts = informational, etc.)
    - Stage 4a (Competitor metrics): WebFetch each URL → extract word count, headings manually
    - Stage 4b (Content deep dive): WebFetch (same as with DataForSEO)

    Workflow completes successfully with full brief.

AT WORKFLOW START (GSC):
  Attempt to load GSC tools via ToolSearch

  IF GSC unavailable:
    Notify user: "GSC not available. Skipping existing ranking check. Proceeding with new content assumption."
    Skip Stage 2b and 2c entirely
    Continue workflow

Invocation

Standard Mode (New Content)

/content-brief [keyword]
/brief [keyword]

Refresh Mode (Existing Content)

/content-brief --refresh [url]
/brief --refresh [url]

Refresh mode is used for existing content that needs a full rewrite or legacy content that has no prior system context. It runs the full 11-stage workflow with these modifications:

• Stage 2c: Skips cannibalization check (URL already exists)
• Stage 2d (NEW): Crawls existing URL to extract baseline content
• Stage 5: Factors in current article performance alongside recommendations
• Stage 6: Dual info gain comparison (vs competitors AND vs current article), reuses existing slug
• Stage 10: Appends Section 7 (Refresh Context) to the brief
• Stage 11: Output filename uses -refresh-YYYY-MM-DD suffix

Source: Typically invoked by Content Refresh skill for Full Rewrite, Consolidation, or Legacy Partial Update tiers. Can also be invoked manually.

Examples

/content-brief commissaire aux comptes
/brief comptabilité sci
/content-brief --refresh https://exemple.fr/blog/un-article
/brief --refresh /blog/un-article

Without Keyword / URL

If invoked without a keyword, prompt the user:

"What keyword would you like to create a content brief for?"

In refresh mode, the target keyword is extracted from the existing article (via GSC top query or crawled H1/title).

Workflow (11 Stages)

MANDATORY: Initialize Todo List at Workflow Start

Before Stage 1, use TodoWrite to create a task list that tracks every stage. Mark each task in_progress when starting it, completed when done. This list must be visible for the entire run.

TodoWrite([
  { id: "tools",   content: "Load MCP tools (DataForSEO + GSC)",                         status: "pending" },
  { id: "s1",      content: "Stage 1 — Capture target keyword",                           status: "pending" },
  { id: "s2a",     content: "Stage 2a — SERP research (top 10 results + PAA)",            status: "pending" },
  { id: "s2b",     content: "Stage 2b — Existing position check (GSC)",                   status: "pending" },
  { id: "s2c",     content: "Stage 2c — Cannibalization check [standard] / 2d Content baseline [refresh]", status: "pending" },
  { id: "s3",      content: "Stage 3 — Keyword research (volume, difficulty, secondary, intent)", status: "pending" },
  { id: "s4",      content: "Stage 4 — Competitor content analysis (5-7 URLs)",           status: "pending" },
  { id: "s5",      content: "Stage 5 — AI recommendations + user confirmation",           status: "pending" },
  { id: "s6",      content: "Stage 6 — Strategic analysis + user confirmation",           status: "pending" },
  { id: "s7",      content: "Stage 7 — Company context integration",                      status: "pending" },
  { id: "s8",      content: "Stage 8 — Competitive positioning (conditional)",            status: "pending" },
  { id: "s9",      content: "Stage 9 — Visual & resource planning",                       status: "pending" },
  { id: "s10",     content: "Stage 10 — Brief compilation + user input",                  status: "pending" },
  { id: "s11",     content: "Stage 11 — Save brief + generate article outline + summary", status: "pending" }
])

Update the relevant task to in_progress at the start of each stage, and completed immediately upon finishing it. For conditional stages (2c vs 2d, 8), mark the skipped one completed with a note in the content field if needed.

Stage 1: Initial Input

Action: Capture target keyword from user User Input Required: Target keyword only

Capture keyword and confirm: "I'll create a content brief for '[keyword]'. Let me check our existing content and gather SERP data..."

Stage 2: SERP & Position Research

Action: Gather SERP data AND check the client's existing content/positions (if any) Tools: DataForSEO + Google Search Console

2a. SERP Research

Tool: mcp__dataforseo__serp_organic_live_advanced

Data to Gather:

• Top 10 SERP results (URLs, titles, meta descriptions)
• SERP features present (Featured Snippet, PAA, Video, etc.)
• PAA questions (extracted from SERP)
• Competitor URLs for further analysis

Note: See data-gathering-workflow.md for API parameters.

2b. Existing Position Check

Tool: mcp__gsc-mcp__get_search_analytics

Check:

• Does the client's site already rank for this keyword?
• What position? What page?
• What's the current click-through rate?

Note: See data-gathering-workflow.md for API parameters.

2c. Content Cannibalization Check

In --refresh mode: Skip this check entirely. We already know the URL exists — that's the point.

In standard mode: Check if we're about to cannibalize existing content.

Cannibalization Threshold: Flag if EITHER condition is met:

1. Existing page ranks position 1-10 for the exact keyword
2. Existing slug matches the keyword pattern

If flagged, present options:

1. Create NEW CONTENT BRIEF (different angle)
2. Abort
3. Switch to refresh mode for this URL → restarts workflow as /content-brief --refresh [existing-url]

Wait for user decision.

If position >10 and slug doesn't match, note in brief and continue.

See: data-gathering-workflow.md for complete logic.

Output: SERP data, existing ranking status, decision (if flagged)

2d. Existing Content Baseline (Refresh Mode Only)

Condition: Only runs in --refresh mode.

Tool: mcp__crawl4ai__crawl_url (fallback: WebFetch)

Actions:

1. Crawl the existing URL
2. Extract baseline data:
   • Current H1, H2/H3 structure
   • Word count
   • Existing internal/external links
   • Existing CTAs
   • Content sections and coverage
   • Publication date / last modified date
3. Query GSC for the URL's top queries, position, clicks, impressions
4. Store as existing_content context for later stages

Output: Existing content baseline (structure, metrics, content map)

Stage 3: Keyword Research

Action: Gather keyword metrics, related terms, and validate viability Tools: DataForSEO Keywords + Labs

3a. Primary Keyword Metrics

Tool: mcp__dataforseo__kw_data_google_ads_search_volume

Data to Gather:

• Search volume (monthly)
• Keyword difficulty
• CPC (cost-per-click)
• Competition level

3b. Secondary Keywords & Suggestions

Tool: mcp__dataforseo__dataforseo_labs_google_keyword_suggestions

Data to Gather:

• Related keywords (10-15)
• Long-tail variations
• Question-based keywords

3c. Batch Difficulty Check

Tool: mcp__dataforseo__dataforseo_labs_bulk_keyword_difficulty

Action: Check difficulty for all secondary keywords at once.

3d. Automated Intent Classification

Tool: mcp__dataforseo__dataforseo_labs_search_intent

Action: Get automated intent classification as starting point for AI analysis.

3e. Keyword Viability Warnings

Important: These are informational warnings, NOT blockers. Low-volume and high-difficulty keywords can still be valuable.

Display warnings for low volume (<100/month), high difficulty (>70), or intent mismatches. Workflow continues automatically after displaying warnings. Warnings are logged in brief metadata.

Output: Keyword metrics, secondary keywords with difficulty, intent classification, warnings noted in brief metadata

Stage 4: Competitor Content Analysis

Action: Deep analysis of top 5-7 competitor articles Tools: DataForSEO On-Page + WebFetch

IMPORTANT: This stage happens BEFORE AI recommendations so analysis is informed by actual competitor data.

4a. Competitor Metrics

Use mcp__dataforseo__on_page_content_parsing to extract: word count, page structure (H1/H2/H3), meta title/description, link counts.

4b. Content Deep Dive

Use WebFetch for each competitor to analyze: H2 outline, unique angle, visual elements, E-E-A-T signals, CTAs, strengths, weaknesses.

4c. Create Competitor Matrix

Document all findings in a comparison table. Identify: common themes, content gaps (information gain opportunities), average word count, visual gaps.

Full methodology: serp-analysis-methodology.md

Output: Competitor analysis matrix with gaps identified

Stage 5: AI Analysis & Recommendations

Action: Analyze ALL data and generate recommendations User Confirmation Required: Yes

Now informed by: SERP data, keyword metrics, intent classification, AND competitor analysis.

In --refresh mode: Also informed by existing content baseline (Stage 2d). Factor in current article's performance — what's working (keep), what's declining (fix), and what's missing (add). Recommendations should preserve high-performing sections while addressing decay signals.

AI Determines:

1. Search Intent — Micro-Intent Analysis (enhanced by DataForSEO + competitor analysis + SERP title analysis)

The classic 4-intent classification (informational, commercial, transactional, navigational) is a starting point but insufficient for content decisions. Go deeper with micro-intents and sub-intent detection.

Step 1 — Classic classification (baseline):

• DataForSEO intent classification: [result]

Step 2 — SERP title-by-title analysis (critical): Analyze each top 10 result's title and classify it by page type (listicle, landing page, definition, how-to, comparison, product page, etc.). Group results by type to identify sub-intents — a single SERP often serves multiple distinct user questions.

Example: "agence GEO" contains two sub-intents:

• Sub-intent A (~30% of results): "Quelle est la meilleure agence GEO ?" → Top 10/listicle
• Sub-intent B (~70% of results): "Je cherche une agence GEO" → Landing page service

Step 3 — Micro-intent classification: Classify the primary sub-intent using these micro-intents:

Step 4 — Sub-intent validation: Test derived queries to confirm sub-intent clusters exist separately:

• "meilleur [keyword]", "best [keyword]" → comparison cluster
• "qu'est-ce que [keyword]", "what is [keyword]" → definition cluster
• "[keyword] prix/pricing" → service/product cluster If derived queries produce a distinctly different SERP composition, the sub-intents are confirmed as separate clusters.

Step 5 — Provide multiple response formats: When the identified micro-intent supports featured snippets, plan multiple content formats (table + ordered list + detailed paragraphs) so Google can select the optimal snippet format.

Output:

• SERP composition analysis: [X blog posts, Y product pages, Z listicles]
• Sub-intents detected: [list with estimated SERP share %]
• Primary micro-intent: [micro-intent name]
• Secondary micro-intent (if any): [micro-intent name]
• Final Recommendation: [Informational / Commercial / Transactional] + micro-intent + recommended content angle

2. Content Type Based on competitor analysis:

• What format dominates SERP? [format]
• Average word count: [X words]
• Recommendation: [Content type] ([word count range])

3. Product Approach

• Does keyword include brand/competitor names?
• Are competitors promotional or educational?
• Recommendation: [Product-focused / Product-mentioned / Agnostic]

4. Target Persona Match to audiences-personas.md based on:

• Keyword intent and complexity
• Company size indicators
• Role-specific terms

5. Content Cluster Match to linking-clusters.md (client context) for internal linking strategy.

Present to User:

Present search intent, content type (with word count), product approach, target persona, and content cluster with brief rationales. Ask: "Do these recommendations look correct, or would you like to adjust any?"

Wait for user confirmation or adjustments before proceeding.

Stage 6: AI Strategic Analysis

Action: Generate strategic recommendations based on competitor gaps User Confirmation Required: Yes

AI Determines:

1. Information Gain Opportunities - Split into TWO categories:

A. Article Info Gain (3-5 items) - Executable by Article Creator Examples: comprehensive coverage, unique angles, expert quotes, comparison tables, case studies, proof points, step-by-step breakdowns.

In --refresh mode: Dual comparison — identify gaps vs competitors AND vs the current article. Categorize each opportunity as:

• NEW: Not in current article or competitors
• UPGRADE: In current article but competitors do it better
• KEEP: Current article already covers this well

B. Supporting Assets (0-3 items) - Requires separate development Examples: downloadable templates, interactive tools, PDF lead magnets, custom infographics, video content.

Reference: information-gain-framework.md

2. Narrative Frame - Define the unique hook that differentiates from competitors.

3. Think-Feel-Do - Map reader journey: belief change (Think), emotional driver (Feel), desired action (Do).

4. CTA Selection - The client's primary CTA from guidelines-donts.md, with aggressiveness matched to content type and awareness stage. Without client context: neutral CTA, never an invented offer.

5. Awareness Stage - Determine TOFU/MOFU/BOFU based on intent.

6. Slug Generation + Check - In standard mode: generate slug, verify availability using mcp__gsc-mcp__inspect_url_enhanced. If exists, suggest alternatives and confirm with user. In --refresh mode: Reuse the existing URL slug (no generation or availability check needed).

Present to User:

Present article info gain (3-5 items with rationale), supporting assets (0-3 items), narrative frame, Think-Feel-Do framework, recommended CTA, awareness stage, and verified slug. Ask: "Do these recommendations look good, or would you like to adjust any?"

Wait for user confirmation or adjustments before proceeding.

Stage 7: Company Context Integration (OPTIONNEL — sauté si pas de contexte)

Action: Si un contexte client existe, le charger pour caler le contenu sur la voix/positionnement du client. Sinon, sauter entièrement cette étape et produire un brief neutre (basé sur SERP + mot-clé). Aucune société n'est codée en dur. Automated: No user input required

Où chercher le contexte (dans cet ordre) :

1. Si un slug client est fourni : seo/clients/<slug>/context/
2. Sinon, aucun contexte → brief générique.

RÈGLE : ne charger un fichier QUE s'il existe ET qu'il est rempli (un fichier-template contenant « À remplir pour ce client » compte comme VIDE → ignorer). Si tout est vide/absent, ne charge rien et continue : le brief s'appuie alors uniquement sur l'analyse SERP et le mot-clé. Ne JAMAIS injecter de marque, produit, persona ou CTA qui ne viendrait pas d'un fichier de contexte réellement rempli. (Historique : ce skill chargeait un KB client codé en dur — supprimé. Le contenu n'est spécifique que si le client a fourni son contexte.)

(Standard 8 fichiers, 2026-07. Les anciens noms customer-stories.md, company-overview.md, competitive-landscape.md, technical-architecture.md peuvent exister sur de vieux clients : les charger s'ils sont présents et remplis, mais ne pas les attendre.)

Output: Contexte client (si disponible) prêt pour la compilation — sinon brief neutre.

Stage 8: Competitive Positioning (Conditional)

Action: Load competitive landscape data Condition: Only if content is product-focused or comparison

IF content_approach == "product-focused" OR
   content_type == "comparison" OR
   keyword contains competitor name:

  Load competitive-landscape.md (si présent dans le contexte client)
  Sinon, utiliser la section positionnement concurrentiel de positioning-messages.md
  (standard 8 fichiers : pas de fichier competitive dédié par défaut)
  Identify the client's advantages vs competitors in SERP (uniquement si le contexte le fournit)
  Add competitive angles to information gain opportunities

ELSE:
  Skip this stage

Output: Competitive advantages to highlight (if applicable)

Stage 9: Visual & Resource Planning

Action: Generate visual recommendations based on competitor audit User Input Required: Yes (for existing assets)

Generate 5-7 specific visual recommendations based on: competitor visual gaps, complex topics needing diagrams, data needing charts, comparison opportunities.

Ask user: "Do you have any existing videos, social media posts, or other assets we should embed or reference in this content? (Enter URLs or 'none')"

Output: Visual ideas list + existing assets (if provided)

Stage 10: Brief Compilation

Action: Compile all gathered data into complete brief User Input Required: Yes (for remaining fields)

Template: content-brief-template.md

Ask User for Missing Fields:

Si un contexte client est chargé (Stage 7), dériver ces champs du contexte au lieu de les demander :

1. Content objective ← CTA principal de guidelines-donts.md
2. Byline ← règle de signature de guidelines-donts.md (section E-E-A-T)
3. Perspective ← personne et adresse de brand-voice.md

Ne demander à l'utilisateur QUE les champs introuvables dans le contexte. Sans contexte client : demander les 3 (objective, byline, perspective).

Compile Brief:

Fill all sections of content-brief-template.md:

• Section 1: Basic Infos (format, perspective, objective)
• Section 2: Strategy (cluster, intent, information gain, narrative, CTA)
• Section 3: Target Audience (persona, pain points, awareness stage)
• Section 4: SEO (keywords, SERP, competitors, titles, meta, PAA)
• Section 5: Resources (product info, brand voice, assets)
• Section 6: Linking (internal links, external links, forbidden sites)

In --refresh mode, also append:

• Section 7: Refresh Context
  • Current URL and publication date
  • Baseline metrics (position, clicks, impressions, CTR from GSC)
  • Decay signals that triggered the refresh (from Content Refresh skill)
  • Refresh tier and legacy status
  • Current article structure summary (from Stage 2d crawl)
  • Specific sections to keep, update, or remove (based on Stage 6 analysis)
  • Success criteria (measurable targets for position, traffic, CTR recovery)

Validate Completeness:

Check all required fields are populated:
- [ ] All 6 sections complete
- [ ] 3-5 information gain opportunities (specific, not vague)
- [ ] 5 title ideas generated
- [ ] Meta description under 160 characters
- [ ] Internal links include pillar + 3-5 related pages
- [ ] External link suggestions included
- [ ] CTA placed appropriately
- [ ] Visual ideas specific and actionable

Output: Complete content brief (markdown format)

Stage 11: Output & Review

Action: Save brief, generate writer summary, and present to user

Save Full Brief:

Standard mode:
  Filename: content-brief-[keyword-slug]-[YYYY-MM-DD].md

Refresh mode:
  Filename: content-brief-[keyword-slug]-refresh-[YYYY-MM-DD].md

Location: Content-brief-creator/generated-briefs/

Note: The generated-briefs/ folder is for production briefs. Test briefs go in test-briefs/.

Generate Article Outline:

Create an Article Outline section at the end of the brief. This is the most actionable deliverable - a structured H2/H3 outline based on competitor analysis, PAA questions, and information gain opportunities.

## Article Outline

1. **H2: [Section 1]**
   - **H3: [Subsection 1a]**
     - Key points to cover
   - **H3: [Subsection 1b]**
     - Key points to cover

2. **H2: [Section 2]**
   - **H3: [Subsection 2a]**
     - Key points to cover
   - **H3: [Subsection 2b]**
     - Key points to cover

3. **H2: [Section 3]**
   - **H3: [Subsection 3a]**
     - Key points to cover

[Continue for all H2 sections - typically 5-8 H2s with 1-3 H3s each]

The Article Outline is MANDATORY. Include H3 subheadings where content warrants subdivision. Base structure on competitor H2/H3 patterns + identified gaps. All other information (keyword, persona, CTAs, proof points, etc.) is already in the main brief sections above.

Present Summary to User:

Display success message with: target keyword (volume, difficulty), content type, persona, cluster, key findings (current ranking, top competitors, avg word count, SERP features), top 3 info gain opportunities, deliverable file paths, and recommended next steps checklist.

Error Handling

DataForSEO Unavailable

"DataForSEO MCP not available. Falling back to WebSearch.
This will take longer but will provide complete results."

GSC Unavailable

"Google Search Console MCP not available.
Skipping existing ranking check. Proceeding with new content assumption.
Recommend manually checking for existing content on this topic."

Competitor Content Behind Paywall

"[URL] is behind a paywall. Skipping and analyzing next-highest ranking URL."

Insufficient SERP Results

"Found only [X] results for this keyword. This may indicate:
- Very niche/specific topic
- New/emerging keyword
- Typo in keyword

Would you like to proceed with [X] competitors, or try a different keyword?"

Keyword Viability Warnings

Informational warnings only - workflow continues automatically. Warnings logged in brief metadata.

Slug Already Exists

In standard mode: Propose alternatives (e.g., [slug]-guide, [slug]-2026) or ask for custom slug. In refresh mode: Expected behavior — reuse existing slug.

Existing URL Not Crawlable (Refresh Mode)

"Cannot crawl [URL]. The page may be behind a paywall, require authentication,
or return an error. Proceeding with GSC data only for baseline metrics.
Content structure will be inferred from SERP cache if available."

KB File Not Found

Notify user and proceed without that data type. Suggest creating file for future briefs.

User Interaction Points

Required User Input (4-5 Total)

1. Stage 1: Target keyword (standard mode) or target URL (refresh mode)
2. Stage 2c: Cannibalization decision (standard mode only — ONLY if position 1-10 AND slug matches, includes "switch to refresh mode" option)
3. Stage 5: Confirm/override AI recommendations (content type, persona, etc.)
4. Stage 6: Confirm/override strategic recommendations (information gain, CTA, etc.)
5. Stage 10: Content objective, byline, perspective

Optional User Input

1. Stage 6: Slug alternative (if proposed slug exists)
2. Stage 9: Existing videos/social posts to embed
3. Any Stage: Override any AI recommendation

Informational Only (No User Input Required)

1. Stage 3e: Viability warnings displayed but workflow continues automatically

Reference Files

Detailed Methodology:

• references/serp-analysis-methodology.md - Competitor analysis methodology
• references/data-gathering-workflow.md - Operational workflow + API parameters
• references/information-gain-framework.md - Information gain identification
• references/brief-structure-guide.md - Section explanations

Templates:

• assets/templates/content-brief-template.md - Fillable brief template

Test Cases:

• test-briefs/ - Sample briefs for informational, comparison, and how-to content

Version History:

• CHANGELOG.md - Complete version history