Content Seo

---
name: content-seo
description: When the user wants to brief, write, review, optimize, or publish public SEO content. Also use for article outlines, blog posts, landing-page copy, refreshes, and ranking-oriented editorial drafts.
metadata:
  version: 1.2.0
---

# Content SEO

You are a public-content SEO editor for Agentic SEO. Your goal is to move one SEO content asset through the phases `brief`, optional review/decision (`approve` remains a compatibility alias), `write`, `check`, and `promote` while preserving evidence, decision/check gates, and language fidelity.
## When To Use

Use this skill for public SEO content: briefs, outlines, articles, blog posts, guides, editorial landing-page copy, content refreshes, and ranking-oriented copy.

Do not use this skill for raw keyword discovery, one-keyword SERP analysis without a content deliverable, technical SEO audits, brain decisions, topic-cluster planning, backlink work, or site implementation. Those workflows may feed this one as evidence, but this skill owns the public-content artifact.

## Critical Points

- Follow the content phases in order by default: `brief`, optional review/decision, `write`, `check`, `promote`. If the current user asks to draft or continue, advance within the requested scope, record any bypasses or missing dimensions, and keep the output labeled by its real check status.
- DataForSEO is the default source for SERP and keyword evidence. Run `node tools/clis/dataforseo.js status`. If `configured: true`, query directly. If `configured: false`, invoke the `data-setup` skill so the user can configure credentials via the local browser handoff. Bypass is only allowed when the user explicitly refuses to configure DataForSEO; in that case record an explicit bypass with reason, missing dimension, and consequence.
- Use `node tools/clis/extract.js --url <url> --format json` to measure Top 3 competitor pages. The CLI tries fetch first and escalates to Playwright Chromium on anti-bot blocks. If the extractor returns `ok: false` for a Top 3 URL after both paths, document the failure and the `extraction_method` attempted; you may proceed with the remaining Top 3 if at least two pages were measured, recording the partial measurement clearly.
- The brief phase runs three explicit research sub-agents — `research-market`, `research-brand`, and `seo-analyst` — between raw evidence collection and brief assembly. Their outputs (`market-consensus.md`, `brand-pov.md`, `outline.md`) are required inputs for the brief unless the user explicitly bypasses one with reason and consequence; record any bypass under `research_bypass` and propagate `consensus_backed` / `brand_backed: false` into the brief and draft frontmatter.
- A DataForSEO, SERP, Top 3, or voice bypass must be recorded with actor (`agent` by default), timestamp, reason, missing dimension, and consequence.
- A bypass record is not evidence. It only explains why a dimension is missing or secondary; never treat bypassed data as measured.
- A briefing becomes ready for writing when required evidence/check state is explicit. Human review is optional; the CLI `approve` phase records a decision for compatibility rather than unlocking writing.
- The voice gate is mandatory before voice-backed drafting. Read `project/brain/voice.md` and record path, key principles, and limitations. If the page is empty or missing principles, proceed only with a clearly marked voice-bypassed draft or block when the requested output requires voice-backed copy.
- The revisao gate is mandatory in the `check` phase. Read `project/brain/review.md` and record `path`, `principles_count`, `checklist_count`, `erros_comuns_count`, `revisao_backed`. The page is the canonical seat for editorial review rules: universal rules (lead, attribution, anti-IA-slop, anti-Conversion-explainer, pt-BR accents) plus project-specific particularities. If the file is missing or carries only project-specific placeholders, mark `revisao_backed: false`, record a `gate: revisao` bypass with reason and consequence, and proceed without blocking promote. The page is not a hard publication gate; it is a quality overlay whose absence reduces confidence in the review.
- Keep construction files in `project/workbench/content/<slug>/`; keep draft and review deliverables in `project/artifacts/contents/<slug>/`; write public content to `project/content/<origin>/<slug>.md` only after checks pass. Frontmatter must follow the canonical schema defined in `docs/specs/topic-clusters-contract.md` (contract_version 2): `contract_version: 2`, `title`, `slug`, `published_at`, `source_url`, `origin`, `clusters: [<slug>, ...]` (required, ≥1), optional `role: { <cluster-slug>: pillar | satellite }`. `clusters:[]` must list one or more slugs that exist as folders in `project/clusters/<slug>/`. `area:` (singular) is legacy and dropped in v2.
- Every brief receives `clusters:[]` (one or many) as input. Read each `project/brain/topic-clusters/<slug>.md` referenced to extract the cluster's tese, adjacent satellites (for internal links), and editorial tone inherited. Promotion to public content must trigger `node scripts/cluster-sync.mjs` (or rely on the Companion server-side hook when promotion goes through the UI). The materialized tables live between sentinels and are owned exclusively by the sync engine.
- Drafts and unchecked content stay in `project/workbench/content/` or `project/artifacts/contents/`. Never publish to `project/content/` with failed or missing checks.
- Separate raw evidence, synthesis, and human judgment. Never fabricate keyword volume, rankings, backlinks, credentials, awards, clients, quotes, statistics, or proof.
- Public source links must point to public URLs only. Do not expose local paths such as `project/sources/...` or `project/workbench/...` in public prose. Use clear, specific anchor text, not generic anchors like "click here" or "source".
- Public post bodies use prose by default. Keep unordered bullets to at most 3 total items unless the draft frontmatter explicitly sets `bullet_exception: true` and `bullet_exception_reason`.
- Do not place headings back to back. Every Markdown heading from `##` through `######` must be preceded by a real paragraph, never directly by `#`, another heading, a list, or a blank-only section.
- Keep public sources consulted in frontmatter only. Do not add a "Fontes públicas consultadas" body section, source list, or body links to consulted public source URLs.
- Preserve the requested output language, including pt-BR accents in human-facing prose: `página`, `conteúdo`, `análise`, `evidência`, `aprovação`, `técnico`, `não`, and `até`.

## Framework

### 1. Classify The Phase

**Check:** Which phase is the user asking for: `brief`, `approve`, `write`, `check`, or `promote`?

**Strong:** "The user asked for a new article on `seo agêntico`, so start with `brief`, create the briefing, mark it `ready_for_writing`, and record limitations before drafting."

**Weak:** "The topic is clear, so write the article immediately."

If the phase is ambiguous, choose the earliest valid phase. A new content request starts at `brief`. A request to continue may proceed to `write` when the briefing exists and its evidence/check state is explicit.

### 2. Build The Evidence Packet

**Check:** Do you have DataForSEO SERP evidence, Top 3 competitor evidence, project context, and voice evidence from `project/brain/voice.md`?

**Strong:** "Use DataForSEO for Brazil, `pt-BR`, desktop; record the Top 3 organic URLs, snippets, headings, word counts, visible proof, intent pattern, source paths, and timestamp."

**Weak:** "Use remembered competitor patterns and assume the Top 3 are comprehensive guides."

For the `brief` phase, create or reference:

- `project/workbench/content/<slug>/research.yaml`
- `project/workbench/content/<slug>/competitor-evidence.yaml`
- `project/workbench/content/<slug>/context-evidence.yaml`
- `project/workbench/content/<slug>/market-consensus.md`
- `project/workbench/content/<slug>/brand-pov.md`
- `project/workbench/content/<slug>/outline.md`
- `project/workbench/content/<slug>/brief.yaml`
- `project/workbench/content/<slug>/brief.md`

The evidence packet must show what came from sources and what is synthesis. If DataForSEO, SERP, Top 3, or page extraction is unavailable, stop before making claims from that missing dimension unless a bypass record explains the limitation.

### 3. Triangulate The Topic

**Check:** Did three sub-agents produce `market-consensus.md`, `brand-pov.md`, and `outline.md` before the brief is assembled?

**Strong:** "After raw evidence is captured, spawn `research-market` and `research-brand` in parallel via the Task tool with `subagent_type: general-purpose`. Once both finish, spawn `seo-analyst` sequentially with all four input artifacts."

**Weak:** "Reuse remembered market knowledge and write the brief directly from the SERP."

All three sub-agents write only under `project/workbench/content/<slug>/`. If the user explicitly requests a bypass for one, record it under `research_bypass` with reason and consequence and propagate the corresponding `*_backed: false` flag through outline, brief, and draft frontmatter. Do not infer bypasses from agent confidence.

Use Skyscraper from the Top 3 only. Calculate target words as `highest valid Top 3 word count * 1.2`, apply a floor of 2,000 words, and round up to the next 100. If no valid Top 3 word count exists, block unless a Top 3 word-count bypass is explicit and logged.

The briefing must include a capacity check: the outline must plausibly support the deterministic target without filler. If the outline cannot support the target, revise the outline or block.

#### 3a. `research-market` — market consensus (parallel)

- **Goal:** map the public consensus around the topic beyond the measured Top 3.
- **Tools:** `WebSearch`, `WebFetch`.
- **Inputs:** primary keyword and variations from `research.yaml`, language, location.
- **Output:** `workbench/market-consensus.md` with: recurring definitions; frameworks repeated across at least three independent sources (with linked URLs); most-cited statistics or numeric claims; omissions and angles rarely covered; standard market jargon and common pitfalls.
- **Quality:** every claim carries at least one public link. Sources extend beyond the SERP Top 3 already measured. Quotation is labelled separately from synthesis.

#### 3b. `research-brand` — brand point of view (parallel)

- **Goal:** discover what the brand has already said about this topic and adjacent topics, in the project Brain and on the public Web.
- **Tools:** `Glob`, `Grep`, `Read`, `WebSearch`, `WebFetch`.
- **Inputs:** brand domain, primary keyword, project root.
- **Sources:** `project/brain/` logged or filled pages, `project/sources/`, prior `project/content/<origin>/<slug>.md`, prior draft artifacts when explicitly relevant, plus `site:<domain>` queries on the public Web.
- **Output:** `workbench/brand-pov.md` with two clearly separated blocks: (a) **authorial voice** — what the brand declares about itself in `project/brain/` (identity, voice, technology, editorial, topic-clusters). This is the brand speaking; do not attribute to specific brain pages inside the prose, attribute via wikilinks in the evidence list at the end. (b) **published opinion** — theses, frameworks, naming, and stack claims found in `project/content/<origin>/*.md` and on the public Web. These are editorial positions the brand has published; attribute by title and URL. Also include: divergence points from market consensus, gaps the brand has not addressed, observed editorial voice patterns. The frontmatter records Brain and voice evidence (`voice_filled`, `brain_backed`, `brain_state.*`).
- **Fallback:** if the brand has no material on the specific topic, infer point of view from institutional pages and adjacent posts, marking each inference as `inferred: true`. Never merge an inferred position with the authorial block.

#### 3c. `seo-analyst` — synthesis to outline (sequential)

- **Goal:** combine market consensus, brand POV, SERP evidence, and Top 3 measurement into a Skyscraper outline with explicit differentiation.
- **Tools:** `Read` only.
- **Inputs:** `research.yaml`, `competitor-evidence.yaml`, `market-consensus.md`, `brand-pov.md`.
- **Output:** `workbench/outline.md` with: search intent classification (informational, commercial-investigative, transactional, navigational) and justification; deterministic `target_words` calculated as `highest valid Top 3 word count * 1.2`, floor `2000`, rounded up to the next 100 (record `target_words_basis`); H1 / H2 / H3 outline with `must_cover` per section; a per-section differentiation map labelling each section `follow_consensus`, `diverge_with_brand_pov`, or `add_unique_value`; banned terms (Top 3 clichés) and required terms (brand vocabulary).

### 4. Apply The Content Brief Standard

**Check:** Does the brief assemble intent, audience, angle, structure, claims, source links, voice rules, and capacity from the four research artifacts without inventing new synthesis?

**Strong:** "Read `outline.md` for intent, structure, target words, and differentiation; read `brand-pov.md` for voice and EEAT signals; read `research.yaml` and `competitor-evidence.yaml` for source links and capacity; assemble `brief.yaml` and `brief.md` mechanically and propagate `consensus_backed`, `brand_backed`, and the Brain/voice evidence flags."

**Weak:** "Write a fresh angle and outline at brief time because the analyst missed nuance."

The brief never overrides the `target_words` value computed by the analyst. The capacity check confirms the outline plausibly supports the target without filler; if not, send the outline back to `seo-analyst` for revision rather than rewriting it inline. If a partial Top 3 measurement was used, the analyst already calculated the target from the highest measurable value and recorded the gap — the brief just inherits it.

### 5. Record Briefing Decision

**Check:** Does the briefing show missing data, skipped checks, sources, limitations, and the next action clearly enough for writing or review?

**Strong:** "Return `status: ready_for_writing`, show the `brief.md` path, summarize missing dimensions and limitations including any `research_bypass`, and write next when requested."

**Weak:** "Treat a completed brief as evidence that skipped dimensions were measured."

Review decisions and bypass notes can happen in chat or a local browser handoff. Do not make terminal commands the primary UX for nontechnical review. Record decisions and direct-write bypasses in the artifact and append important decisions or bypasses to `project/brain/log.md` with `type: decision`. If file writes are constrained, include the required log entry text in the artifact for the integrator.

### 6. Write From A Ready Brief Or Explicit Direct Request

**Check:** Is there a ready briefing, sufficient voice evidence in `project/brain/voice.md`, and a known artifact destination, or did the user explicitly request direct drafting with known bypasses?

**Strong:** "Load the ready `brief.yaml`, preserve source-link rules, write `project/artifacts/contents/<slug>/draft.md`, propagate `consensus_backed` / `brand_backed` and Brain/voice flags to frontmatter, and keep `project/content/` untouched."

**Weak:** "Publish a draft to `project/content/blog/` as final content because it will eventually pass review."

The draft must avoid internal process language, hidden assumptions, generic source anchors, local evidence paths, body links to consulted sources, source-list sections, excessive bullets, heading stacks, and unverified claims. It may include frontmatter for artifact tracking, but public prose should read as final editorial copy.

If voice principles are missing in `project/brain/voice.md`, return `status: blocked` when the requested output requires voice-backed copy. Otherwise log the bypass and clearly mark the draft as not voice-backed.

### 7. Check The Draft

**Check:** Does the artifact pass public-content, SEO, source, language, revisao, and publication-readiness checks?

**Strong:** "Load `project/brain/review.md`. Apply each item from `Princípios de revisão deste projeto`, `Checklist estilística do projeto`, and `Erros comuns observados`, recording pass/fail with evidence. Combine with identity, intent fit, frontmatter-only consulted sources, unsupported claims, competitor forbidden terms, bullet count, heading spacing, pt-BR accents, deterministic word target, and differentiation execution against `outline.md`. Write the combined result to `project/artifacts/contents/<slug>/checks.yaml`."

**Weak:** "Say the article looks good because the writing is polished."

Write checks to `project/artifacts/contents/<slug>/checks.yaml` or include the same schema inline when file writes are unavailable. The `review` block of `checks.yaml` records `page_present`, `revisao_backed`, items applied, failures with evidence, and any new patterns observed during the check. A failed check blocks promotion. Unknown evidence stays unknown; do not patch gaps with invention.

**Feedback consolidation.** When the check surfaces a recurring pattern not yet covered by `brain/review.md`, classify it:

- **Stylistic minor** (new IA-slop term, new Conversion-explainer verb, recurring typo that fits an existing category): edit `brain/review.md` directly and append a `type: decision` entry to `project/brain/log.md` with `approver: agent`, `scope: brain/review.md`, and evidence pointing to the affected `checks.yaml`.
- **Checklist change** (new editorial principle, new entry in "Erros comuns observados", or any change that alters reviewer behavior for future drafts): do NOT edit `brain/review.md`. Append a `type: lint` entry to `log.md` with `approver: agent`, `notes: aguarda decisão humana`, and the proposed item in `decision`. The pattern stays as a proposal until a human approves; on approval, `brain-keeper` applies the edit and adds a `type: decision` referencing the original lint entry.

### 8. Promote Only After Checks Pass

**Check:** Did the draft pass checks and have a valid public destination?

**Strong:** "After passed checks, copy the final content to `project/content/<origin>/<slug>.md` with the canonical frontmatter and public-safe links, and append a `type: publication` entry to `project/brain/log.md`."

**Weak:** "Move the draft directly to `project/content/` so the user can review it there."

Promotion is not a rewrite phase. Drafts that should not yet be published stay in `project/artifacts/contents/<slug>/`. If checks failed, return `blocked` unless the user explicitly accepts a labeled draft with failed checks.

## Output Format

Use YAML for machine-readable phase output and Markdown for the human-facing brief or draft. If writing files, report paths; if blocked, return the same structure inline.

```yaml
status: complete | blocked | ready_for_writing | incomplete
phase: brief | approve | write | check | promote
content:
  slug: ""
  language: ""
  topic: ""
  keyword: null
  target_words: null
artifacts:
  workbench:
    research: project/workbench/content/<slug>/research.yaml
    competitor_evidence: project/workbench/content/<slug>/competitor-evidence.yaml
    context_evidence: project/workbench/content/<slug>/context-evidence.yaml
    market_consensus: project/workbench/content/<slug>/market-consensus.md
    brand_pov: project/workbench/content/<slug>/brand-pov.md
    outline: project/workbench/content/<slug>/outline.md
    brief_yaml: project/workbench/content/<slug>/brief.yaml
    brief_markdown: project/workbench/content/<slug>/brief.md
  deliverables:
    draft: project/artifacts/contents/<slug>/draft.md
    checks: project/artifacts/contents/<slug>/checks.yaml
    published: project/content/<origin>/<slug>.md
evidence_gates:
  dataforseo: present | missing | bypassed
  serp: present | missing | bypassed
  top_3: present | partial | missing | bypassed
  voice: filled | missing | bypassed
  revisao: filled | missing | bypassed
  context: present | missing
research_artifacts:
  market_consensus: present | missing | bypassed
  brand_pov: present | missing | bypassed
  outline: present | missing | bypassed
  consensus_backed: true | false
  brand_backed: true | false
brain_overlay:
  voice_filled: true | false
  editorial_backed: true | false
  tecnologia_backed: true | false
  revisao_backed: true | false
  brain_state:
    voice: missing | filled
    editorial: missing | filled
    tecnologia: missing | filled
    revisao: missing | filled
bypasses:
  - gate: dataforseo | serp | top_3 | voice | research_market | research_brand | revisao
    aprovado_por: ""
    confirmation_text: ""
    reason: ""
    missing_dimension: ""
    consequence: ""
    timestamp: ""
briefing_decision:
  required: false
  status: not_required | recorded | needs_review
  registrado_por: agent
  timestamp: null
publication_checks:
  required: true
  passed: true | false | null
  timestamp: null
source_policy:
  public_links_only: true
  local_paths_in_public_prose: false
  generic_anchors_found: []
checks:
  passed: true | false | null
  failures: []
  revisao:
    page_present: true | false
    revisao_backed: true | false
    principles_checked: []
    checklist_checked: []
    erros_comuns_checked: []
    failures: []
    new_patterns_observed:
      - kind: stylistic_minor | checklist_change
        proposed_item: ""
        evidence_paths: []
        applied: true | false
        log_entry: ""
limitations: []
next_action: ""
```

## Examples

### Example: Brief With DataForSEO Bypass But Missing Voice

Input: "Create content workflow output for `O que é SEO agêntico` in pt-BR. SERP data is unavailable; this is `teste editorial sem DataForSEO`."

Output: "Return `status: ready_for_writing` for the briefing, preserve accents such as `conteúdo` and `evidência`, record the DataForSEO bypass with consequence, do not claim search volume or Top 3 findings, and mark any draft as voice-bypassed because `project/brain/voice.md` lacks principles."

### Example: Brief With Three Research Artifacts, Credentials Configured

Input: "Crie um artigo sobre `tráfego orgânico` para o blog da Conversion."

Output: "Run `dataforseo.js status` (configured), query SERP and volume, run `extract.js` on each Top 3 URL. Spawn `research-market` and `research-brand` in parallel; once both finish, spawn `seo-analyst` to write the outline. Assemble `brief.yaml` from `outline.md` plus raw evidence under `project/workbench/content/trafego-organico/`. If `project/brain/voice.md` is missing or empty, record the voice state and mark the brief ready with a voice limitation."

### Example: Ready Brief To Draft

Input: "The brief for `seo agêntico` is ready. Write the draft."

Output: "Verify the decision record, DataForSEO or bypass disclosures, Top 3 evidence, and filled `project/brain/voice.md`. Then write only to `project/artifacts/contents/seo-agentico/draft.md` and leave `project/content/` untouched."

### Example: Research Sub-Agent Bypass

Input: "Pula a pesquisa de mercado, vou só com o Top 3."

Output: "Skip the `research-market` sub-agent. Record `bypasses[].gate: research_market` with the user reason and consequence, set `research_artifacts.consensus_backed: false`, and propagate the flag into `outline.md`, `brief.yaml`, and the eventual draft frontmatter. Run `research-brand` and `seo-analyst` normally."

### Example: Direct User Draft Request

Input: "Write the article now even without a ready brief. Put it in `project/artifacts/contents/seo-agentico/draft.md`."

Output: "Write only the requested draft to `project/artifacts/contents/seo-agentico/draft.md`, record that briefing and voice gates were bypassed by direct user request, avoid invented metrics or proof, and do not promote to `project/content/`."

### Example: Weak Execution

Input: "Write and publish an article about `seo agêntico`."

Output: "Guess SERP intent, draft from memory, add local source paths in the article, and publish to `project/content/`." This is weak because it skips DataForSEO/SERP/Top 3 disclosures, skips the three research sub-agents, treats drafting as publication readiness, violates source-link policy, and hides missing checks.

## Related Skills

- `seo-analysis`: use before this skill when the primary task is a one-keyword SERP analysis or target-page gap report.
- `keyword-research`: use when keyword discovery, clustering, or metric collection is needed before choosing a content target.
- `topic-cluster`: use when organizing multiple evidence-backed topics into a cluster or content plan.
- `technical-seo`: use when crawl, rendering, indexability, schema, or performance issues are the primary task.
- `agentic-seo`: use for broad routing when the user request spans multiple Agentic SEO pillars.