conversion-agency/agentic-seo-skills / skills/project-init
project-init
VerifiedWhen the user wants to create, initialize, or prepare one Agentic SEO project with the standard local project structure, blank brain templates, content directories, and initial log entry.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.3 KB |
| evals/fixture.md | markdown | 957 B |
| references/seed-from-doc.md | markdown | 8.6 KB |
| references/seed-from-site.md | markdown | 13.3 KB |
references/seed-from-site.md
View on GitHub# Pré-preenchimento do Cérebro a partir do site
Este passo é opcional. Ele só roda quando o usuário, no início do setup (Passo 0),
autoriza pré-preencher o Cérebro pesquisando o site. Sob essa **autorização prévia
do Passo 0**, este passo ESCREVE DIRETO nas páginas do Cérebro (`project/brain/`)
para o usuário revisar e editar no Web Companion. Ele NÃO usa `workbench/` nem exige
registro `type: approval`: esta é a regra do **ONBOARDING** (autorização prévia),
distinta do fluxo `brain-keeper`. Ele NUNCA roda sozinho (sempre depende do "sim" do
Passo 0) e NUNCA inventa fatos, métricas ou decisões.
> Tom e progresso para leigos: ver `docs/output-and-tone.md`. Explique o termo
> técnico em linguagem simples na primeira menção (ex.: "Cérebro do projeto",
> "importar fontes").
>
> Trabalho silencioso: a seleção/leitura das URLs e a coleta da info adicional
> acontecem no agente principal (que tem web fetch e canal com o usuário); o
> subagente recebe esses dados prontos. O usuário vê só o checklist nativo e o
> Cérebro já preenchido para revisar — nunca comandos crus, URLs de debug nem
> exploração.
## Quando este passo se aplica
- O usuário escolheu pré-preencher o Cérebro (`prefill_choice: from_site`).
- Existe um `site_url` válido em `project/.agentic-seo/project.json` (ou o usuário
informou a URL do site principal).
- A estrutura básica do projeto já foi criada (diretórios + arquivos do Cérebro
a partir dos templates). O pré-preenchimento acontece DEPOIS do setup básico,
nunca no lugar dele.
Se não houver `site_url`, este passo não roda: peça a URL ou siga com o Cérebro
em branco (`prefill_choice: blank`).
## O que este passo faz (e o que NÃO faz)
Faz:
1. Combina DUAS fontes de insumo: (a) as extrações das até 10 URLs do site
(`site_extractions`) e (b) as **informações adicionais** que o usuário
forneceu (`additional_info`: páginas-chave, posicionamento, diferenciais,
público, concorrentes, dados). Ambas são entregues prontas pelo agente
principal.
2. Compõe e ESCREVE as páginas do Cérebro (`identity`, `voice`, `technology`,
`review`, `topic-clusters`, `index`) direto em `project/brain/`, combinando o
que foi lido do site com a info adicional do usuário.
3. Registra a escrita no diário (`brain/log.md`) com `type: decision` e
`approver` = nome do usuário (ele autorizou no Passo 0).
4. Abre/oferece o Web Companion em `project/brain/index.md` para o usuário revisar
e editar (pedindo permissão antes de abrir o navegador).
NÃO faz:
- Não inventa fatos de marca, dados de mercado nem decisões técnicas.
- Não abre o navegador sem pedir permissão antes.
- Não embute URLs de runtime (localhost/`127.0.0.1`/rotas do Companion) em nenhuma
página escrita em `project/` — ver "Documentos autossuficientes" abaixo.
## Seleção das URLs (até 10)
Escolha um conjunto pequeno e representativo, não a maior quantidade possível.
Priorize, nesta ordem, as páginas que mais carregam identidade e tese:
1. Home (`/`).
2. Sobre / Quem somos / Sobre nós.
3. Serviços / Produtos / Soluções (a página-âncora da oferta).
4. Páginas de categoria ou pilar do blog.
5. Até 3-5 posts-chave (os mais recentes ou os mais ligados pela navegação).
6. Contato / Time, se ajudar a entender autoridade (E-E-A-T).
Regras:
- Máximo de 10 URLs. Pare em 10 mesmo que existam mais candidatas.
- Apenas o domínio principal (`site_url`); não siga para domínios externos.
- Pule páginas de login, carrinho, checkout, busca interna e páginas legais
pouco informativas, a menos que sejam o único conteúdo disponível.
- Prefira páginas com texto real; descarte páginas quase vazias.
## Extração
Para cada URL, capture o que ajuda a montar o Cérebro:
- Título da página e meta descrição.
- Cabeçalhos (H1/H2) e o texto principal.
- Sinais de marca: aposto, promessa, frase âncora, público.
- Sinais técnicos visíveis: stack aparente, CMS, plataforma.
- Temas recorrentes (insumo para áreas editoriais e topic clusters).
Guarde as URLs efetivamente lidas; elas viram a evidência da ingestão.
## Informações adicionais do usuário (`additional_info`)
O seed combina o site com o texto/posicionamento/dados que o usuário forneceu.
Quando `additional_info` estiver presente, ela é **insumo obrigatório** da
composição — nunca apenas coletada e ignorada.
- **Seleção/leitura das URLs:** quando o usuário citar páginas-chave ou URLs
específicas, priorize-as na seleção das até 10 (mantendo o teto de 10).
- **Distribuição por página do Cérebro:** mapeie cada tipo de conteúdo da
`additional_info` para a página-alvo reaproveitando a tabela de distribuição de
[`seed-from-doc.md`](seed-from-doc.md) — posicionamento/diferenciais/público →
`identity`; tom desejado → `voice`; stack/plataforma → `technology`; temas e
subtemas → `topic-clusters`; ofertas → `products` (opcional); regras editoriais
→ `review`.
- **Precedência em caso de conflito:** a informação fornecida pelo usuário é
autoral e **tem prioridade** sobre a observação do site (o site é evidência
observada). Mas dados/métricas sem comprovação continuam indo para o `log` como
pendência, não para a prosa do Cérebro (ver "Regras duras de composição").
## Escrita das páginas do Cérebro
Escreva DIRETO em cada página do Cérebro (`project/brain/`), combinando o que foi
lido do site com a `additional_info` do usuário (insumo obrigatório quando presente):
- `index` — a HOME do Cérebro. **NUNCA** ponha banner/aviso de "rascunho", "não
validado" ou "aguardando revisão" no topo — a autorização do Passo 0 torna a
escrita canônica, não é rascunho. Escreva: 1 parágrafo curto de introdução
(o que a marca é + que este é o Cérebro que os agentes leem antes de agir) e a
seção `## Páginas` com um H3 (wikilink) por sub-página canônica (`identity`,
`voice`, `technology`, `topic-clusters`, `review`, `log`, nesta ordem) e **2-4
bullets curtos** em cada, resumindo o que você de fato escreveu naquela página
(identity → aposto/promessa/público/anti-posicionamento/técnica/canais; voice →
registro/termos preferidos/proibidos/atribuição/idioma; technology → stack/CMS/
status técnico/pendências; topic-clusters → nomes dos clusters ativos +
que a tabela única é auto-gerada; review → regra universal + princípios + checklist;
log → o que é registrado). Os bullets derivam do conteúdo semeado — **não
invente; omita o bullet** em vez de adivinhar.
- `identity` — aposto, parágrafo de apresentação, promessa, público,
identidade técnica e canais.
- `voice` — princípios e registro inferidos do tom dos textos.
- `technology` — **APENAS fatos técnicos observados do site** (stack, CMS,
framework, headers, JSON-LD, renderização, sinais de performance). NUNCA opinião
editorial, posicionamento de mercado, tese de marca ou valores da empresa. Guia
rápido — observado vs. opinião:
- Observado (entra em `technology`): "Next.js + Vercel, SSR, schema `Article`",
"WordPress com cache de CDN", "JSON-LD de `Organization` presente na home".
- Opinião (NUNCA em `technology`; roteie): "a marca defende sites estáticos",
"preferimos edge rendering", "stack moderna é diferencial competitivo" →
vai para `identity`, `topic-clusters` (área Tecnologia) ou conteúdos em
`contents/`, conforme o caso.
O que não foi observado fica de fora (não vira gap).
- `review` — regras editoriais específicas do projeto inferidas do material.
- `topic-clusters` — modelo de **tabela única** (sem áreas). A página
`brain/topic-clusters.md` tem um único bloco automático `agentic-clusters` (tabela
plana de todos os clusters ativos) entre as sentinelas — **NÃO** crie H2 por "área"
nem use o antigo `agentic-clusters-by-area`. Para cada cluster que você identificar:
- **(a) Manifesto:** escreva `project/clusters/<slug>/cluster.yaml` a partir de
`templates/project/clusters/cluster.yaml.template` (schema em
`docs/specs/topic-clusters-contract.md`, `contract_version: 1`). Preencha `name`;
um `icon` (um emoji pré-selecionado que represente o tema do cluster, ex.: 🧭, 🚀,
📊); `thesis` (1-3 linhas, só do site/`additional_info`, sem fabricação);
`pillar.slug` apontando para um slug real ou planejado;
`planned_satellites`/`satellite_overrides` vazios salvo evidência;
`provenance.created_by: agent` e `decision_log` apontando para a entrada do log.
**Não há campo `area`.** **Status:** use `status: active` para que o cluster
apareça na tabela do Companion e o usuário possa revisá-lo (modelo de escrita
direta autorizada no Passo 0). NÃO invente dados: `pillar.volume`/`volume_source`
ficam `null` e `evidence: []` quando não houver dado real.
- **(b) Subpágina do cluster:** escreva também a subpágina
`brain/topic-clusters/<slug>.md` a partir de
`templates/project/brain/topic-clusters/_cluster-subpage.md.template`, com a prosa
editorial do cluster (tese/linhas editoriais, **só** do site/`additional_info`,
sem fabricação) mais o bloco `cluster-content` (tabela de conteúdos materializada
por `cluster-sync` entre as sentinelas — não preencha à mão). Sob a **autorização
prévia do Passo 0**, a criação da subpágina é escrita direta (modelo de
onboarding, sem gate `approve-cluster`).
- **(c) Índice/painel:** **NÃO** edite os blocos entre as sentinelas
`<!-- BEGIN cluster-index-table:auto... -->` / `<!-- END cluster-index-table:auto -->`
nem `<!-- BEGIN cluster-content-table:auto... -->` / `<!-- END cluster-content-table:auto -->`
— são regenerados por `cluster-sync`.
Regras duras de composição:
- Escreva direto nas páginas de `project/brain/`, **preservando o frontmatter**
(`title`/`updated`) e **qualquer conteúdo que o usuário já tenha escrito** (não
sobrescreva conteúdo substantivo do usuário; o seed só preenche páginas ainda em
estado de template/placeholder).
- Respeite a **no-gap rule** (ver `docs/brain.md`): nenhum `TODO`/`<fill>`/"a
confirmar" no arquivo autoral. Onde a página não der base para um campo, **omita
a subseção** (não deixe heading vazio) e mande a pendência para o `log` — não
preencha por suposição.
- Não fabrique credenciais, números, casos, datas nem decisões. Se não está no
site nem na info adicional, não entra na prosa do Cérebro.
## Registro no diário (log)
Anexe ao `brain/log.md` exatamente UMA entrada por execução do seed que tenha
alterado conteúdo (append-only, idempotente). Use o token do enum em inglês
`decision` e as chaves em inglês (ver formato em `AGENTS.md`):
```markdown
## YYYY-MM-DD - Cérebro pré-preenchido a partir do site
- type: decision
- scope: project/brain/ (páginas preenchidas pelo seed)
- decision: Cérebro pré-preenchido a partir do site (N páginas lidas) + informações adicionais do usuário, sob autorização prévia do Passo 0.
- evidence: <lista das URLs lidas> + <"informações adicionais fornecidas pelo usuário" quando houver>
- approver: <nome do usuário>
- notes: Onboarding/seed — autorização prévia (Passo 0). Páginas escritas direto no brain para revisão no Companion.
```
O `approver` é o **usuário** (ele autorizou no Passo 0), não `agent`.
## Revisão no Companion (autorização prévia, sem gate de promoção)
Não há mais mover `workbench/`→`brain/` nem registro `type: approval`: as páginas
já foram escritas direto no Cérebro. O usuário só revisa e edita o que já está lá.
- Ofereça abrir o Cérebro numa tela no navegador (handoff `project-browser`, ver
`AGENTS.md` → "Browser handoff"), no modo detached e mirando o projeto do
usuário — nunca preso a um Bash com timeout. **Peça permissão antes de abrir.**
- Após o usuário confirmar que revisou, siga para os próximos passos (ver o
fechamento do `/start`).
Gates que CONTINUAM valendo (não relaxam no onboarding):
- Sempre pedir a autorização do usuário no Passo 0 antes de pré-preencher.
- Sempre pedir permissão ANTES de abrir o navegador.
- Fora do onboarding, criar NOVA subpágina de cluster volta a exigir o handoff
`approve-cluster`. O seed só escreve as subpáginas direto **sob a autorização
prévia do Passo 0** (modelo de escrita direta), com a tabela única `agentic-clusters`
em `topic-clusters.md` e os manifestos `project/clusters/<slug>/cluster.yaml`.
> Decisão (aprovada): clusters semeados no onboarding nascem `status: active` para
> ficarem visíveis na tabela única do Companion e o usuário revisar/editar. Sem
> fabricar dados (`volume`/`volume_source` nulos, `evidence: []` quando não houver). A
> escrita direta da subpágina é coberta pela autorização do Passo 0; fora do
> onboarding, NOVA subpágina segue exigindo `approve-cluster`. Edição/refino posterior
> vem pela interface (já integrada a content) ou pela skill `topic-cluster`.
## Documentos autossuficientes (regra dura)
Toda página escrita em `project/` (páginas do Cérebro, reviews, reports, conteúdos)
precisa ser **autossuficiente** quando lida fora do contexto que a gerou. **NUNCA**
embuta URLs de runtime — `localhost`, `127.0.0.1` ou rotas do Web Companion
(ex.: `.../project/<token>/brain-review`) — no corpo de nenhum arquivo. Essas URLs são
efêmeras (token único, porta efêmera, expiram). Cite URLs públicas ou evidência
relativa na seção `## Evidência`, nunca uma URL de debug do Companion.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |