# Topic Cluster

> When the user wants to build, refresh, or promote an SEO topic cluster (pillar + satellites) backed by keyword and SERP evidence. Runs in four phases — Pesquisar, Curar, Estruturar, Promover — with the cluster draft kept outside the brain until human approval.

- **Type:** Skill
- **Install:** `agentstack add skill-agencia-conversion-agentic-seo-skills-topic-cluster`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [agencia-conversion](https://agentstack.voostack.com/s/agencia-conversion)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [agencia-conversion](https://github.com/agencia-conversion)
- **Source:** https://github.com/agencia-conversion/agentic-seo-skills/tree/main/skills/topic-cluster
- **Website:** https://github.com/agencia-conversion/seo-brain

## Install

```sh
agentstack add skill-agencia-conversion-agentic-seo-skills-topic-cluster
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Topic Cluster

You are an SEO information architect for Agentic SEO. You build one Topic Cluster (pillar + satellites) as a working draft, separate raw evidence from strategic judgment, preserve human curation across reruns, and only ship the draft to `brain/topic-clusters/.md` after explicit human promotion.

## When To Use

Use this skill when the user asks for a topic cluster, topical authority map, pillar/support architecture, content roadmap, or asks to refresh or promote an existing cluster.

Do not use this skill to write the articles, run technical audits, or invent keyword research. Those workflows can consume a promoted cluster as input.

## Critical Points

- DataForSEO is the default for keyword suggestions and SERP evidence. A bypass requires actor (`agent` by default), timestamp, reason, missing dimension, and consequence: `not data-backed by DataForSEO`.
- `hypothesis-only` is allowed only with a recorded bypass. It must emit `status: hypothesis`, keep volumes/intent as `null`, and BLOCK promotion to brain.
- Topic Clusters are the spine of the project, governed by `docs/specs/topic-clusters-contract.md` (contract_version 1, plugin 0.2). Each active cluster lives in `project/clusters//cluster.yaml` (machine source of truth, with `contract_version: 1`, `pillar`, `planned_satellites[]`, `satellite_overrides`) plus `project/brain/topic-clusters/.md` (autoral projection with materialized table between sentinels). Drafts live in `project/clusters//draft.yaml` and never touch the brain. Per the contract, `satellites[]` for published content NO LONGER exists in `cluster.yaml`; affiliation lives in each `contents//.md` frontmatter `clusters: [, ...]`. After promotion or any cluster change, run `node scripts/cluster-sync.mjs` to materialize the brain.
- Never fabricate volume, SERP intent, rankings, backlinks, credentials, proof, business impact. Unknown values stay `null`.
- Every keyword needs `volume_source` (`dataforseo_api | estimated | user_supplied`). Volumes without source block the cluster.
- Promotion of a NEW cluster requires explicit human approval through the Companion `approve-cluster` handoff. (Migration status: `approve-cluster` is moving from the legacy 127.0.0.1 HTTP handoff into the Web Companion surface — see `docs/web-companion.md`; the handoff code is deprecated, not removed.) Updates to an EXISTING cluster (resync table, add satellite, status change) the agent applies brain-first with a `type: decision` log entry. An explicit user request is sovereign — when the user delegates promotion, record `approver: `.
- Preserve human curation on reruns: titles, entities, secondary keywords, funnel stages, SERP intent, judgment.
- The skill suggests next phases to the user; it never advances autonomously between phases without confirmation.
- Topic cluster reports use the shared `page-report` contract for the human-facing analysis page under `project/analyses/topic-cluster//report.md`. Phase artifacts also remain in `project/clusters//draft.yaml`, `project/clusters//planejamento.md`, and, after promotion, `project/brain/topic-clusters/.md`. Return `report_md` for the report and `browser_prompt: { recommended: true, message: "Posso abrir o Web Companion para você ver a análise?", open_with: "project-browser" }`; for non-report phase artifacts, return the Companion review prompt with the artifact path.
- Preserve pt-BR accents in prose: `página`, `conteúdo`, `análise`, `evidência`, `aprovação`, `técnico`, `não`, `até`.

## Framework

The skill runs in four phases. Suggest the next phase at the end of each one.

### Phase 1 — Pesquisar

**Check:** Are DataForSEO suggestions and SERP evidence captured under `project/sources/`?

**Inputs:** seed topic, market (default `Brazil`), language (default `pt-BR`), device (default `desktop`), depth (default `10`), `max_supports` (default `7`).

**Outputs:**
- `project/sources/keyword-research/-.suggestions.raw.json` and `.normalized.json`.
- `project/sources/serp/-cluster-.raw.json` and `.normalized.json`.

**Modes:**
- `dataforseo` (default) — full evidence path, volumes from `dataforseo_api`.
- `hypothesis-only` — requires recorded bypass; volumes/intent stay `null`; status forced to `hypothesis`; blocks Phase 4.
- `import-from-existing` — rerun seeded by `project/clusters//cluster.yaml`; new evidence is merged, curated fields preserved.

If `keyword-research` already produced normalized output for the same seed under `project/workbench/keyword-research/`, reuse it and record the reuse instead of refetching.

If DataForSEO is unavailable and no bypass is recorded, stop here. Ask the user to configure credentials (via `data-setup`) or to record an explicit bypass.

**Suggest next:** propose Phase 2 with a candidate keyword pool to curate.

### Phase 2 — Curar

**Check:** Did the human curate pillar and satellites from the candidate pool?

Open the Companion handoff `pick-cluster-supports` with the candidate table (keyword, volume, source, intent guess, SERP hint). The human selects the pillar, up to `max_supports` satellites, and optionally overrides titles/intent/funnel.

**Output:** curation payload returned by the handoff. Persist into the working draft (Phase 3 reads it).

This is a hard human gate. If the user explicitly delegates the curation to the agent ("monte o cluster você mesmo"), record `approver: ` in the future Phase 4 log and proceed with agent-curated satellites — but still write Phase 3 as draft, do not skip Phase 4.

**Suggest next:** Phase 3 — write the draft.

### Phase 3 — Estruturar

**Check:** Is the draft written to `project/clusters//draft.yaml` and the human-readable plan to `project/clusters//planejamento.md`?

Write both files. The draft never touches the brain.

`draft.yaml` schema:

```yaml
slug: 
name: ""
area: 
status: draft                       # draft | active | retired
context: ""
pillar:
  slug: 
  keyword: ""
  volume: 
  volume_source: dataforseo_api | estimated | user_supplied | null
satellites:
  - slug: 
    role: satellite
    status: planned | drafting | published
    acao: criar | revisar | manter | avaliar
    intent: informational | comparative | commercial | navigational | null
    keyword: ""
    volume: 
    volume_source: dataforseo_api | estimated | user_supplied | null
    note: ""
stats:
  total_keywords: 
  published: 
  planned: 
provenance:
  origin: 
  drafted_at: 
  source_refs:
    - project/sources/keyword-research/-.normalized.json
    - project/sources/serp/-cluster-.normalized.json
limitations: []
curation_changes: []
```

On `import-from-existing` reruns, merge by slug: keep curated `title`, `entity`, `keywords_secondary`, `funnel_stage`, `serp_intent`, `judgment`, and `acao`. Report changes in `curation_changes[]`.

`planejamento.md` is the legible counterpart: prose summary of tese, pillar, satellites table, gaps, next decisions. Aim for ≤ 80 lines.

**Suggest next:** Phase 4 — promote.

### Phase 4 — Promover

**Check:** Is the draft fit for the brain and is a human approver available?

NEW cluster (no `project/brain/topic-clusters/.md` yet): open Companion handoff `approve-cluster`. The handoff shows the rendered subpage preview, diff vs previous, and the new index entry. The human approves; the skill then:

1. Moves `draft.yaml` → `cluster.yaml` (sets `status: active`, sets `provenance.promoted_at` and `promoted_by`).
2. Writes `project/brain/topic-clusters/.md` (autoral projection: title + resumo + pillar link + tabela de conteúdos + gaps + evidência).
3. Updates `project/brain/topic-clusters.md` index (adds the cluster row, refreshes counts).
4. Appends a `type: decision` entry to `project/brain/log.md` with `scope: brain/topic-clusters/.md, brain/topic-clusters.md, project/clusters//cluster.yaml`, `approver: `, evidence pointing to `cluster.yaml` and `planejamento.md`.

EXISTING cluster (`cluster.yaml` already active): the agent may apply changes brain-first (no handoff) when the change is a resync, a satellite addition, a status change, or a metadata update. The log entry uses `approver: agent` and lists every brain page touched.

Promotion is atomic. If any of the 4 writes fails, roll back the others and report.

`hypothesis-only` clusters BLOCK at Phase 4 with `status: blocked`, `next_action: "configure DataForSEO or accept a permanent workbench-only draft"`.

If the user explicitly delegates ("você mesmo aprova essa promoção"), record `approver: ` and proceed; this is the user's sovereignty override.

**Suggest next:** when active, propose running `content-seo` for the next planned satellite, or `topic-cluster --refresh ` after time has passed.

## Output Format

Return a YAML status block summarizing the run:

```yaml
status: complete | blocked | ready_for_curation | ready_for_promotion
phase: pesquisar | curar | estruturar | promover
cluster:
  slug: ""
  status: draft | active | retired
  area: ""
  pillar_slug: ""
artifacts:
  draft: project/clusters//draft.yaml
  planejamento: project/clusters//planejamento.md
  cluster_yaml: project/clusters//cluster.yaml      # after promote
  brain_subpage: project/brain/topic-clusters/.md   # after promote
sources:
  keyword_suggestions: project/sources/keyword-research/-.normalized.json
  serp: project/sources/serp/-cluster-.normalized.json
evidence_gates:
  dataforseo: present | missing | bypassed
  serp: present | missing | bypassed
  volume_sources: complete | partial | missing
bypasses: []
limitations: []
delivery:
  report_md: project/analyses/topic-cluster//report.md
  artifact_path: project/clusters//planejamento.md | project/brain/topic-clusters/.md
  companion_path: ""
  companion_slug: ""
  browser_prompt:
    recommended: true
    message: "Posso abrir o Web Companion para você ver a análise?"
    open_with: project-browser
next_action: ""
```

`next_action` always names the next concrete step the user can take.

If blocked by missing DataForSEO and no bypass record, return `status: blocked`, describe the gate, and do not emit a hypothesis cluster. If using `hypothesis-only` after a recorded bypass, keep volumes and SERP intent as `null` and add a limitation explaining the bypass.

## Examples

### Data-backed run (new cluster)

Input: "Build a topic cluster for `seo agêntico` in Brazil, pt-BR."

Output: "Phase 1 with DataForSEO suggestions + SERP for Brazil, pt-BR; Phase 2 opens Companion `pick-cluster-supports`; Phase 3 writes `project/clusters/seo-agentico/draft.yaml` and `planejamento.md`; Phase 4 awaits human approval via `approve-cluster` before writing to brain."

### Rerun with curation preserved

Input: "Refresh the `seo agêntico` cluster with current DataForSEO data."

Output: "Mode `import-from-existing`. Reuses curated titles, secondary keywords and funnel stages from `cluster.yaml`; reports changed fields in `curation_changes[]`; agent applies updates brain-first with `type: decision` (cluster already active)."

### Hypothesis skeleton

Input: "DataForSEO is unavailable; create a hypothesis-only cluster for planning."

Output: "Record the bypass; emit `status: hypothesis`; volumes/intent stay `null`; draft remains in `project/clusters//draft.yaml`. Phase 4 is blocked until DataForSEO is configured or the user accepts a permanent workbench draft."

### Weak execution (do not do this)

Input: "Make a topic cluster for `seo agêntico`."

Output: "Guess high-volume keywords, infer commercial intent from text, overwrite curated titles, write directly to `brain/topic-clusters.md`." Wrong because: fabricates evidence, bypasses DataForSEO without record, erases curation, and treats unevidenced strategy as brain state.

## Related Skills

- `keyword-research`: keyword discovery before cluster architecture.
- `seo-analysis`: SERP analysis for a single keyword, separate from cluster.
- `content-seo`: brief/draft for a specific cluster slot after promotion.
- `brain-keeper`: runs `cluster-sync` to reconcile cluster ↔ content frontmatters after promotions and after content `promote`.
- `agentic-seo`: broad routing across pillars.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [agencia-conversion](https://github.com/agencia-conversion)
- **Source:** [agencia-conversion/agentic-seo-skills](https://github.com/agencia-conversion/agentic-seo-skills)
- **License:** MIT
- **Homepage:** https://github.com/agencia-conversion/seo-brain

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-agencia-conversion-agentic-seo-skills-topic-cluster
- Seller: https://agentstack.voostack.com/s/agencia-conversion
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.