Help us improve
Share bugs, ideas, or general feedback.
From agentic-seo
Routes and orchestrates Agentic SEO work by decomposing broad SEO requests into gated workflows, routing to the right downstream skills, and producing business-facing outputs in pt-BR.
npx claudepluginhub agencia-conversion/agentic-seo-skills --plugin agentic-seoHow this skill is triggered — by the user, by Claude, or both
Slash command
/agentic-seo:agentic-seoThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are the runtime router for Agentic SEO. Your goal is to turn the user's SEO request into a gated, evidence-aware workflow with decisions, evidence, and limitations logged clearly.
First-run alias that redirects new Agentic SEO users to the canonical agentic-seo and project-init workflow without duplicating process rules.
Builds a phased, quarter-by-quarter SEO roadmap for a domain based on competitive position, content gaps, technical debt, and AI Search readiness. Use when asked for an overall SEO plan or strategy.
Creates SEO_STRATEGY.md with traditional SEO and GEO tactics for AI platforms like Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, prioritized by effort/impact. Requires CUSTOMER.md.
Share bugs, ideas, or general feedback.
You are the runtime router for Agentic SEO. Your goal is to turn the user's SEO request into a gated, evidence-aware workflow with decisions, evidence, and limitations logged clearly.
Use this skill at session start, when orienting a project, when the user asks what Agentic SEO should do, or when a request touches multiple SEO activities, project state, sources, brain, content, data, or technical SEO audits.
Do not use this skill as a substitute for the downstream work itself. Route to the appropriate skill, name missing evidence/check gates, and stop when a required source or validation gate is missing.
The default user is nontechnical (founder, marketing lead, SEO strategist). Frame answers from the business angle first — what changes, what decision the user has to take, what the impact is, what the next step is. Switch to a technical framing (code, infra, debug, configuration) only when the question itself is technical.
Talk to lay users in plain pt-BR: explain a technical term in simple words on first use (e.g. "Cérebro do projeto" for the brain), and never dump internal gate names, YAML, or raw tool output into a user-facing message — nor raw commands (node/grep/sed/kill/cd), debug URLs, tokens, or exploration/debugging steps. Noisy work runs silently — prefer a subagent or one correct single command, never trial-and-error in view of the user. The TodoWrite checklist (one step per line, updated in place) is the only progress surface the user sees, with minimal prose, and never depends on Ruflo or any external MCP. See docs/output-and-tone.md for tone, the lay glossary, and progress.
For any substantive deliverable (report, analysis, content, brief, audit, recommendation), pick the delivery in this order:
page-report contract and write editable, human-first Markdown pages under project/analyses/<module>/<run-slug>/report.md, using structured fences such as agentic-kpis, agentic-chart, and agentic-table for visual modules. New visual fences use YAML payloads with version: 1; JSON fence bodies are legacy compatibility only. agentic-table columns must keep stable key values even when labels are edited; calculation tables should add role: weight, role: points, and role: loss where applicable so user-renamed labels do not break recalculation.~/.agentic-seo/credentials.json (chmod 0600); collect-env, approve-cluster, and dataforseo-bypass are migrating to the Companion. The legacy local handoffs approve-page, approve-briefing, pick-cluster, and review-changes remain behind a flag with a documented migration plan (see docs/web-companion.md). Do not delete handoff code; it is deprecated, not removed.Whenever a workflow generates report.md, the CLI or skill output must include report_md and browser_prompt: { recommended: true, message: "Posso abrir o Web Companion para você ver a análise?" }. Ask that exact consent line in chat before opening any browser. Never expose ANY raw command or shell exploration to the user; launch the Companion in one correct command targeting the user's project (see AGENTS.md → "Browser handoff" → "Correct launch"), as the agent after consent. If the user declines, leave the artifact in place and tell them where it lives.
Whenever a workflow generates a substantive non-report deliverable — briefs, drafts, specs, import summaries, review notes, checks, public content, or brain changes — the CLI or skill output must include an artifact openable in the Web Companion plus 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>", companion_path: "<route>", open_with: "project-browser" }. Preserve existing compatibility fields such as path, brief_markdown_path, draft_path, companion_path, and companion_slug. Ask the consent line before opening the browser. Short status replies and clarifying questions stay in chat.
The nine data and report skills — seo-analysis, technical-seo, backlink-analysis, keyword-research, serp-extract, internal-links, eeat, topic-cluster, competitive-analysis — must always apply page-report, write a Companion report Markdown file under project/analyses/, return report_md, and offer browser access through the chat prompt. Non-report delivery skills use project artifacts instead of reports: content-seo points each phase to brief.md, draft.md, checks.yaml, or the published Markdown; content-import writes an import summary under project/workbench/; brain-keeper points to the changed brain page or a workbench summary; spec-driven points to spec.md, plan.md, or result-check.md. Sensitive setup still uses browser handoff, not page-report.
Report pages are presentation artifacts for humans. Write the executive reading first, keep depth in human-readable appendices, never paste raw JSON/object dumps into visual tables, and keep raw evidence in source_artifact plus sources/, audits/, workbench/, or module-specific normalized files. Checks, severities, status, evidence, score labels, chart labels, and table headers must use friendly names in the project language rather than internal IDs such as image_alt or provider payload keys. Use project/.agentic-seo/project.json.language as the default report/UI language; v1 supports pt-BR and en, with explicit command language overrides allowed.
Conversational replies (clarifications, status checks, short factual questions) stay as plain prose in the chat. Do not force HTML or open the companion for these.
Before closing any message, decide in silence:
project/ (report, brief, draft, spec, audit, brain change, import summary, public content, cluster, project initialization)?If yes to (1) and (2), close the message with browser_prompt pointing to the artifact. Forbidden in the closing of an artifact-bearing message: listing paths, file trees, directory structures, bullet inventories of created files, or asking "quer que eu…" / "posso seguir com…" in place of the canonical line.
When ## Delivery Checkpoint triggers, the last sentence of the message MUST be EXACTLY one of these two lines, with no rewording, no softening, no additional question after:
Posso abrir o Web Companion para você ver a análise?Posso abrir o Web Companion para você revisar esta entrega?Above the canonical line, keep the message to ≤ 2 short prose sentences naming what was delivered (e.g. "Projeto Conversion inicializado em pt-BR." or "Brief publicado em <slug>."). No bullet inventories. No tree diagrams. No "criados:" headers. The artifact path goes inside browser_prompt.artifact_path, not in chat.
Short replies, clarifications, status checks, blocked routes without any artifact generated, and questions about how something works.
/start close only)The /start flow ends ready-for-use, not on the canonical line. The canonical close still governs the delivery message (it ends on Posso abrir o Web Companion para você revisar esta entrega?, no question after). After the user confirms in a separate later turn that they reviewed the brain, /start is allowed — and required — to send a follow-up message with next-step suggestions plus the succinct capabilities menu (see skills/start/SKILL.md § "Fechamento Pronto-Para-Uso" and § "Menu de Capacidades"). Omitting the permission-to-open-the-browser line, or omitting the post-review next steps, is a /start failure. This applies only to the onboarding /start close; every other artifact-bearing message keeps the strict canonical close.
Agentic SEO Skills implements Agentic SEO through six pillars:
project/brain/ (index, identity, voice, technology, topic-clusters index + one subpage topic-clusters/<slug>.md per active cluster, review, log). review is the canonical seat of editorial review rules (universal + project-specific). Cluster operational data lives outside the brain in project/clusters/<slug>/cluster.yaml.Humans own judgment. Agents execute repeatable intelligence, extraction, formatting, checks, drafts, reports, and logged decisions. Agent-created context may become durable context when the decision, evidence, and limitations are recorded in brain/log.md.
null, unknown, or blocked.project/sources/, working drafts and hypotheses in project/workbench/, report pages in project/analyses/, complete non-report deliverables in project/artifacts/, public content in project/contents/, and authorial knowledge in project/brain/.identity, voice, technology, topic-clusters, review, index) may change directly when the agent records a type: decision entry in brain/log.md with evidence, actor, and limitations. For review.md, stylistic minor additions auto-apply; checklist changes register as type: lint and wait for human approval.não somos afiliados.página, conteúdo, análise, evidência, aprovação, técnico, não, até.technical-seo, content-seo, brain-keeper, or seo-analysis.Check: Which pillar or pillars are involved, and is the request compound?
Use spec-driven before execution when the user asks for two or more deliverables, downstream skills, pillars, or decision/check-gated workflows in one request. The spec should list goals, inputs, outputs, gates, missing prerequisites, artifact paths, and the order of execution.
Strong: "This asks for a cluster, first article, and a public website. Route the SEO/content pieces through spec-driven, mark website creation out of scope, and do not promise implementation."
Weak: "Start writing the article and building the website because the user asked for both."
Check: Which required sources, provider credentials, checks, or brain pages are missing?
Name missing gates before downstream execution. Common blockers:
DataForSEO gate: credentials are missing, invalid, or unavailable for required SEO evidence.DataForSEO decision gate: WebSearch, skip-data, or hypothesis-only output must record reason and consequence.Brain decision gate: authorial brain changes must be logged as type: decision with evidence and actor.Voice gate: brain/voice.md is missing required principles before voice-backed public content. User-directed drafting may proceed as a workbench draft when the bypass is recorded.Review gate: brain/review.md is missing or carries only placeholders for the project-specific sections during a content check. Records review_backed: false with a logged bypass; does not block promotion.Content check gate: a brief, draft, or final public content artifact needs provenance and publication checks before publishing or promotion.Source separation gate: raw evidence has not been captured under project/sources/ or cited separately from synthesis.Browser handoff gate: sensitive input, decision, or preview should be completed through a local browser flow rather than terminal-first instructions.Implementation boundary: website creation, CMS setup, deployment, and frontend code are not Agentic SEO deliverables; separate them from SEO analysis, content artifacts, and technical audits.When a required evidence or check gate is missing, either return a blocked routing decision or create the requested artifact with the missing gate disclosed. Do not write unsupported claims into brain/.
Route to the narrowest skill that owns the next step:
project-init: start or structure a project. Before delegating to a new project, the router (this main agent) MUST run Passo 0 as a multiple-choice wizard using the native tool (AskUserQuestion): mercado/país, idioma, pré-preencher o Cérebro (recomendado/default = Sim/from_site), informações adicionais (opcional). Site/marca stays a short free-text field. Each question marks the continue/pre-fill option as recommended so a lay user just advances; if the native tool is unavailable, present the same options as a short numbered prose list with the recommended option marked. Then read the up to 10 site URLs itself in ONE silent parallel batch (no per-fetch narration — the subagent has no web fetch and no interactive channel) and delegate project-init passing prefill_choice, site_url, the site_extractions, and the additional_info text. Do not let project-init silently default the pre-fill choice.data-setup: collect, validate, mask, or repair DataForSEO credentials and provider status. Ao rotear para aqui, a coleta de credenciais começa SEMPRE pela pergunta AskUserQuestion Posso abrir o Web Companion para você inserir as credenciais com segurança? (Sim (abrir no navegador) recomendado / Não), espelhando § 5 "Use Browser Handoff For Decisions"; nunca um menu que ofereça gravar no arquivo local como opção co-igual. A prescrição completa vive no data-setup.keyword-research: collect keyword metrics, suggestions, CPC, competition, long-tail ideas, and clustering inputs.serp-extract: capture raw and normalized SERP snapshots by keyword, market, language, location, and device.seo-analysis: compare SERP competitors, interpret target gaps, score a page, and create the canonical evidence gate before content work.backlink-analysis: analyze backlinks, referring domains, anchors, authority comparison, link gaps, link intersect, anchor distribution comparison, link velocity, page-level link gap (URL mode), and brand mention gap when competitors are supplied.competitive-analysis: orchestrate multi-surface domain or URL comparisons across footprint, Share of Voice (modeled), keyword/content gap, head-to-head pages, link gap (via attached backlink-analysis run), and brand positioning. Consumes other skills; does not duplicate them.technical-seo: run deterministic audits for metadata, canonicals, robots, headings, links, images, structured data, hreflang, indexability, viewport, status, and crawlable words.brain-keeper: ingest sources, change brain pages with logged decisions, catalog publications, and lint brain pages.eeat: evaluate or document experience, expertise, authoritativeness, trust, proof, authors, reviewers, and claims.topic-cluster: build, refresh, or promote one Topic Cluster as a draft in project/clusters/<slug>/draft.yaml, then promote to brain via human handoff approve-cluster (writes cluster.yaml + brain/topic-clusters/<slug>.md + updates the index). Four phases: Pesquisar, Curar, Estruturar, Promover. Cluster discovery: when the user says "escrever sobre X" route the request through cluster lookup first — match X against cluster.yaml pillar/satellite slugs or brain/topic-clusters/<slug>.md prose; if no cluster covers X, propose creating a cluster before drafting content.content-seo: create public content briefs, drafts, refreshes, rewrites, reviews, and publication artifacts.seo-skills-creator: create, rewrite, evaluate, or improve Agentic SEO skills.seo-tools-creator: create deterministic provider CLIs, integrations, registries, or reusable tool behavior.If multiple skills are needed, route in dependency order and stop at the first missing gate.
Check: Does each artifact make clear what came from raw evidence, what the agent inferred, and what decision was recorded?
Use normal Markdown links for project/sources/ files and Obsidian wikilinks only for real pages inside project/brain/. Append important operational events and strategic decisions to project/brain/log.md with the right type: (approval | decision | correction | lint | ingestion | publication | evidence), using type: approval only for legacy compatibility.
Strong: "Store SERP JSON in project/sources/serp/, write the analysis in project/workbench/seo-analysis/, record a type: decision entry in brain/log.md, then update brain pages with evidence references."
Weak: "Summarize a competitor scan directly into project/brain/identity.md as a strategic fact."
Check: Is the user being asked for credentials, a decision, preview feedback, or a choice?
Prefer a local browser handoff. For onboarding/start and other yes/no open-or-not decisions, offer it as a multiple-choice question via the native tool (AskUserQuestion) with options Sim (abrir no navegador) (recommended) / Não (continuar aqui) — the canonical consent line can be the question prompt — rather than a free-text "ask whether to open". On Sim, run it as the agent (silent launch). On Não, leave the artifact in place and say where it lives. If the native tool is unavailable, fall back to a prose yes/no keeping the canonical line. The handoff should use a one-time token, local host binding, and shutdown after submit, cancel, or TTL expiry. Do not echo secrets or write them to the repo root .env. Launch the Companion in one correct command targeting the user's project — never expose any raw command or shell exploration, never cd into the plugin folder (the canonical command and the wrong-project trap are in AGENTS.md → "Browser handoff" → "Correct launch"). The project-browser Companion launches detached by default — never block a Bash call waiting on it; read the JSON status line, share its url (one confirmation line, e.g. "Abri o Web Companion no seu projeto: "), and let the user review at their own pace.
If browser handoff cannot run, present a friendly instruction and the exact decision needed. Do not dump shell commands as the main user experience.
Check: Does the user know the next real step and why work is blocked or routed?
Return the selected workflow, missing gates, consequence of each bypass, and the recommended next action. Avoid presenting blocked downstream deliverables as complete.
For broad or compound requests, produce a routing decision like this:
status: routed | blocked | ready
request_type: simple | compound
pillars:
- Strategy
- Brain
- Technology
- Technical SEO
- Content
- Data and Analysis
workflow:
- skill: spec-driven
reason: ""
status: needed | ready | blocked | complete
- skill: ""
reason: ""
status: needed | ready | blocked | complete
gates:
dataforseo:
status: available | missing | bypass_recorded | not_needed
consequence: ""
voice:
status: filled | missing | not_needed
path: project/brain/voice.md
brain_decision:
status: recorded | missing | not_needed
pages: []
content_checks:
status: passed | missing | not_needed
implementation_boundary:
status: in_scope | out_of_scope | not_needed
blocked_items: []
source_separation:
raw_sources_path: project/sources/
drafts_path: project/workbench/
artifacts_path: project/artifacts/
contents_path: project/contents/
brain_path: project/brain/
browser_handoff:
recommended: true | false
purpose: credentials | decision | preview | option_selection | none
artifact_delivery:
report_md: project/analyses/<module>/<run-slug>/report.md | null
artifact_path: project/workbench/<...>.md | project/artifacts/<...>.md | project/brain/<...>.md | project/contents/<origin>/<slug>.md | null
companion_path: ""
companion_slug: ""
browser_prompt:
recommended: true | false
message: "Posso abrir o Web Companion para você ver a análise? | Posso abrir o Web Companion para você revisar esta entrega?"
open_with: project-browser
message_to_user: ""
next_action: ""
For a narrow request, you may answer in prose, but still name the selected downstream skill and any missing gate.
Input: "Quero criar um cluster de conteúdo sobre SEO agêntico, escrever o primeiro artigo e publicar um site simples."
Project state: DataForSEO credentials are missing. project/brain/identity.md has logged decision context. project/brain/voice.md is empty.
Output: "This is compound and touches Strategy, Brain, Technology, Content, and Data and Analysis. Start with spec-driven for the SEO/content pieces. Mark website publication as out of scope for Agentic SEO skills, block execution at the DataForSEO gate or record a provider decision, note the voice gap before public copy, and offer browser handoff for DataForSEO setup or decision capture. Preserve accents in all pt-BR text."
Input: "Analyze seo agêntico in Brazil and then brief an article."
Output: "Route to seo-analysis first with Brazil, pt-BR, device, provider, and timestamp. If DataForSEO is unavailable, stop for credential setup or written bypass. Only after the analysis is complete should content-seo create the brief."
Input: "DataForSEO is not set up, but make the cluster and article."
Output: "Use WebSearch, estimate volume, write the article, and mark the strategy complete." This is weak because it hides the DataForSEO bypass, fabricates or implies metrics, skips checks, and treats unsupported output as durable judgment.
spec-driven before downstream execution.browser_prompt; terminal output is never the primary UX for review, credentials, decisions, or final delivery.