From agentic-seo
Guides creation of public SEO content through phases: brief, write, check, and promote. Use for articles, blog posts, landing page copy, and ranking-oriented drafts.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agentic-seo:content-seoThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are a public-content SEO editor for Agentic SEO. Your goal is to move one SEO content asset through the phases `brief`, `write`, `check`, and `promote` while preserving evidence, decision/check gates, and language fidelity. (Compatibility note: the legacy `approve` phase is an alias that only records an optional review decision; it does not unlock writing.)
You are a public-content SEO editor for Agentic SEO. Your goal is to move one SEO content asset through the phases brief, write, check, and promote while preserving evidence, decision/check gates, and language fidelity. (Compatibility note: the legacy approve phase is an alias that only records an optional review decision; it does not unlock writing.)
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.
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.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.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.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.agent by default), timestamp, reason, missing dimension, and consequence.approve phase records a decision for compatibility rather than unlocking writing.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.check phase. Read project/brain/review.md and record path, principles_count, checklist_count, erros_comuns_count, review_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 review_backed: false, record a gate: review 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.project/workbench/content/<slug>/; keep draft and review deliverables in project/artifacts/contents/<slug>/; write public content to project/contents/<origin>/<slug>.md only after checks pass. Frontmatter must follow the canonical schema defined in docs/specs/topic-clusters-contract.md (contract_version 1): contract_version: 1, 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 v1.brief points to project/workbench/content/<slug>/brief.md; write points to project/artifacts/contents/<slug>/draft.md; check points to the check result plus the draft target; promote points to project/contents/<origin>/<slug>.md. Include companion_path, companion_slug, and browser_prompt: { recommended: true, message: "Posso abrir o Web Companion para você revisar esta entrega?", artifact_path: "<project-relative path>", open_with: "project-browser" } while preserving compatibility fields such as brief_markdown_path, draft_path, path, and companion_path. Ask before opening the browser.clusters:[] (one or many) as input. For each referenced cluster, the machine source of truth is project/clusters/<slug>/cluster.yaml (pillar, planned satellites, thesis, icon — single-table model, NO area field); its authorial projection is the subpage project/brain/topic-clusters/<slug>.md (editorial prose + the cluster-content materialized table between sentinels). Read the subpage to extract the cluster's tese, adjacent satellites (for internal links), and inherited editorial tone; read cluster.yaml when you need the exact slugs/roles. 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.project/workbench/content/ or project/artifacts/contents/. Never publish to project/contents/ with failed or missing checks.project/sources/... or project/workbench/... in public prose. Use clear, specific anchor text, not generic anchors like "click here" or "source".project/ (drafts, checks, published content, review notes) must be self-sufficient and must NEVER embed runtime URLs — localhost, 127.0.0.1, or Web Companion routes (e.g. .../project/<token>/brain-review). Those are runtime-only and expire. Cite public URLs or relative evidence under ## Evidência, never a Companion debug URL.bullet_exception: true and bullet_exception_reason.## through ###### must be preceded by a real paragraph, never directly by #, another heading, a list, or a blank-only section.página, conteúdo, análise, evidência, aprovação, técnico, não, and até.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.
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.yamlproject/workbench/content/<slug>/competitor-evidence.yamlproject/workbench/content/<slug>/context-evidence.yamlproject/workbench/content/<slug>/market-consensus.mdproject/workbench/content/<slug>/brand-pov.mdproject/workbench/content/<slug>/outline.mdproject/workbench/content/<slug>/brief.yamlproject/workbench/content/<slug>/brief.mdThe 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.
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.
research-market — market consensus (parallel)WebSearch, WebFetch.research.yaml, language, location.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.research-brand — brand point of view (parallel)Glob, Grep, Read, WebSearch, WebFetch.project/brain/ logged or filled pages, project/sources/, prior project/contents/<origin>/<slug>.md, prior draft artifacts when explicitly relevant, plus site:<domain> queries on the public Web.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/contents/<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.*).inferred: true. Never merge an inferred position with the authorial block.seo-analyst — synthesis to outline (sequential)Read only.research.yaml, competitor-evidence.yaml, market-consensus.md, brand-pov.md.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).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.
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.
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/contents/ untouched."
Weak: "Publish a draft to project/contents/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.
Check: Does the artifact pass public-content, SEO, source, language, review, 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, review_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:
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.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.Check: Did the draft pass checks and have a valid public destination?
Strong: "After passed checks, copy the final content to project/contents/<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/contents/ 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.
When review_backed: false (the project review page project/brain/review.md is missing or carries only placeholders), surface a clear, plain-language warning to the user BEFORE promoting — for example: "Vou publicar sem a revisão editorial específica do seu projeto (a página de Revisão ainda está em branco). As regras universais foram aplicadas, mas as particularidades da sua marca não. Quer que eu siga assim?" Do not bury this in a YAML field. Promote with review_backed: false recorded only after the user accepts the reduced confidence.
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.
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/contents/<origin>/<slug>.md
evidence_gates:
dataforseo: present | missing | bypassed
serp: present | missing | bypassed
top_3: present | partial | missing | bypassed
voice: filled | missing | bypassed
review: 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
technology_backed: true | false
review_backed: true | false
brain_state:
voice: missing | filled
editorial: missing | filled
technology: missing | filled
review: missing | filled
bypasses:
- gate: dataforseo | serp | top_3 | voice | research_market | research_brand | review
approver: ""
confirmation_text: ""
reason: ""
missing_dimension: ""
consequence: ""
timestamp: ""
briefing_decision:
required: false
status: not_required | recorded | needs_review
registered_by: agent
timestamp: null
publication_checks:
required: true
passed: true | false | null
timestamp: null
delivery:
artifact_path: project/workbench/content/<slug>/brief.md | project/artifacts/contents/<slug>/draft.md | project/artifacts/contents/<slug>/checks.yaml | project/contents/<origin>/<slug>.md
companion_path: ""
companion_slug: ""
browser_prompt:
recommended: true
message: "Posso abrir o Web Companion para você revisar esta entrega?"
artifact_path: ""
open_with: project-browser
source_policy:
public_links_only: true
local_paths_in_public_prose: false
generic_anchors_found: []
checks:
passed: true | false | null
failures: []
review:
page_present: true | false
review_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: ""
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."
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."
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/contents/ untouched."
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."
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/contents/."
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/contents/." 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.
brief.md, draft.md, checks.yaml, or published content.companion_path, companion_slug, and browser_prompt with the Web Companion review message.project/contents/ until checks pass.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.npx claudepluginhub agencia-conversion/agentic-seo-skills --plugin agentic-seoBuilds, refreshes or promotes SEO topic clusters (pillar + satellites) backed by keyword and SERP evidence using DataForSEO. Runs in four phases with human curation preserved across reruns.
Generates SEO content like blog posts, landing pages, guides with briefs, humanized writing, SERP targeting, entity optimization, and quality checks.
Plans content strategy, builds editorial calendars, creates SEO briefs, and optimizes content for search and AI discovery. Use when developing content pillars, messaging hierarchy, or managing editorial operations.