Taxonomia do Blog
Gerencie tags, categorias e clusters de tópicos em plataformas CMS.
Comandos
| Comando | Propósito |
|---|---|
/blog taxonomy suggest <arquivo> | Extrair tags e categorias candidatas do conteúdo |
/blog taxonomy sync <cms> | Enviar taxonomia para o CMS via API autenticada |
/blog taxonomy audit [diretório] | Verificar tags finas, tags órfãs, inchaço de taxonomia |
Fluxo de Sugestão de Tags
Passo 1: Analisar Estrutura do Conteúdo
Leia o arquivo alvo e extraia:
- Todos os cabeçalhos H2 e H3 (sinais primários de tópico)
- Frases em negrito e itálico (sinais de ênfase)
- Tags/categorias existentes no frontmatter, se presentes
Passo 2: Análise de Frequência
Varre o texto do corpo em busca de frases de alta frequência:
- Termos de 1 palavra: mínimo 4 ocorrências (excluindo palavras irrelevantes)
- Frases de 2 palavras: mínimo 3 ocorrências
- Frases de 3 palavras: mínimo 2 ocorrências
Exclua palavras comuns não-tag: artigos, preposições, conjunções, pronomes.
Passo 3: Agrupamento Semântico
Agrupe candidatos relacionados em clusters:
- Mesclar variantes singular/plural (manter a forma mais comum)
- Mesclar formas com e sem hífen
- Agrupar sinônimos sob o termo de maior frequência
Passo 4: Desduplicar e Ranquear
- Correspondência fuzzy em nomes slugificados (distância Levenshtein <= 2)
- Pontuar cada candidato:
(frequência * 2) + (presença_em_cabeçalho * 5) + (ênfase * 1) - Retornar as 5-10 principais sugestões ranqueadas
Formato de Saída
## Sugestões de Tags: [Título do Post]
| Ranking | Tag | Pontuação | Fonte |
|---------|-----|-----------|-------|
| 1 | marketing-de-conteudo | 18 | H2 + 6 menções |
| 2 | estrategia-seo | 14 | H3 + 4 menções |
| 3 | pesquisa-de-palavras-chave | 11 | 5 menções + negrito |
### Categorias Sugeridas
- Primária: [categoria de melhor ajuste]
- Secundária: [segunda categoria opcional]
Adaptadores CMS
Visão Geral dos Adaptadores
| CMS | Tipo de API | Método de Autenticação | Modelo de Tags |
|---|---|---|---|
| WordPress | REST | Senhas de Aplicativo (base64) | Entidades de primeira classe com IDs |
| Shopify | GraphQL (API de Admin) | Token de acesso da API de Admin | Array de strings em Artigo |
| Ghost | REST (API de Admin) | Chave de API com assinatura JWT | Entidades de primeira classe |
| Strapi | REST ou GraphQL | Token de API (Bearer) | Tipo de conteúdo definido pelo usuário |
| Sanity | GROQ / Mutações | Token de projeto (Bearer) | Tipo de documento |
Adaptador WordPress
Listar tags:
GET {CMS_URL}/wp-json/wp/v2/tags?per_page=100&search={palavra-chave}
Authorization: Basic {base64(usuário:senha_app)}
Criar tag:
POST {CMS_URL}/wp-json/wp/v2/tags
Body: {"name": "Nome da Tag", "slug": "nome-da-tag", "description": "Opcional"}
Listar categorias (hierárquicas, suporta campo pai):
GET {CMS_URL}/wp-json/wp/v2/categories?per_page=100
Criar categoria:
POST {CMS_URL}/wp-json/wp/v2/categories
Body: {"name": "Categoria", "slug": "categoria", "parent": 0}
Atribuir tags a um post:
POST {CMS_URL}/wp-json/wp/v2/posts/{id}
Body: {"tags": [1, 2, 3], "categories": [4]}
Paginação: siga o cabeçalho X-WP-TotalPages para listagem completa.
Adaptador Shopify
Tags no Shopify são arrays de strings no objeto Artigo, não entidades de primeira classe.
Atualizar tags de artigo (API GraphQL de Admin):
mutation {
articleUpdate(id: "gid://shopify/Article/123", article: {
tags: ["tag-um", "tag-dois", "tag-tres"]
}) {
article { id tags }
userErrors { field message }
}
}
Listar todas as tags em uso (GraphQL):
{
articles(first: 250) {
edges {
node { id title tags }
}
}
}
Cabeçalho de autenticação: X-Shopify-Access-Token: {token}
Nota: API REST marcada como legada em out/2024. GraphQL é obrigatório para novos apps a partir de abr/2025.
Adaptador Ghost
Listar tags:
GET {CMS_URL}/ghost/api/admin/tags/?limit=all
Authorization: Ghost {jwt_token}
Criar tag:
POST {CMS_URL}/ghost/api/admin/tags/
Body: {"tags": [{"name": "Nome da Tag", "slug": "nome-da-tag"}]}
Geração de JWT: assine com a chave de API de admin (formato id:secret), iat = agora, exp = 5 min,
audience = /admin/.
Adaptador Strapi
Endpoint gerado automaticamente a partir dos tipos de conteúdo. Configuração típica:
GET {CMS_URL}/api/tags?pagination[pageSize]=100
POST {CMS_URL}/api/tags
Body: {"data": {"name": "Nome da Tag", "slug": "nome-da-tag"}}
Authorization: Bearer {api_token}
Strapi v4+ usa o wrapper data. Verifique o esquema do seu tipo de conteúdo para os nomes dos campos.
Adaptador Sanity
Consultar tags (GROQ):
*[_type == "tag"] { _id, name, slug }
Criar tag (API de Mutações):
POST https://{project_id}.api.sanity.io/v2024-01-01/data/mutate/{dataset}
Body: {"mutations": [{"create": {"_type": "tag", "name": "Tag", "slug": {"current": "tag"}}}]}
Authorization: Bearer {token}
Fluxo de Auditoria de Taxonomia
Passo 1: Inventário
Varrer todos os posts no diretório alvo (ou buscar do CMS). Construir um mapa:
- nome_da_tag -> [lista de arquivos/IDs de posts usando esta tag]
- nome_da_categoria -> [lista de arquivos/IDs de posts]
Passo 2: Verificações de Saúde
| Verificação | Limite | Ação |
|---|---|---|
| Arquivos de tag fina | < 5 posts por tag | Recomendar noindex ou mesclagem |
| Tags órfãs | 0 posts | Recomendar exclusão |
| Inchaço de tags | > 50 tags no total | Recomendar consolidação |
| Profundidade de categoria | > 3 níveis | Recomendar achatamento |
| Posts sem categoria | Nenhuma categoria atribuída | Atribuir a categoria apropriada |
| Slugs duplicados | Mesmo slug, nome diferente | Mesclar na versão canônica |
Passo 3: Recomendações
Agrupar descobertas por prioridade:
- Crítico: tags órfãs criando páginas de arquivo vazias (desperdício de rastreamento)
- Alta: tags finas com < 3 posts (má experiência do usuário, sinal SEO fraco)
- Média: inchaço de tags acima de 50 (taxonomia diluída, navegação mais difícil)
- Baixa: inconsistências de nomenclatura (maiúsculas/minúsculas misturadas, hífen vs espaço)
Formato de Saída
## Auditoria de Taxonomia: [Site/Diretório]
**Total de tags**: [n] | **Total de categorias**: [n]
**Saudáveis**: [n] | **Finas**: [n] | **Órfãs**: [n]
### Problemas Críticos
- [lista de tags órfãs]
### Recomendações
1. Mesclar [tag-a] e [tag-b] (mesmo tópico, [n] posts combinados)
2. Excluir tags órfãs: [lista]
3. Adicionar noindex aos arquivos de tag com < 5 posts
Diretrizes para Todo o Site
- Busque de 5 a 10 categorias principais por site (tópicos amplos)
- Tags devem ter pelo menos 5 posts antes de criar uma página de arquivo
- Use formato de slug consistente: minúsculas, separado por hífen
- Todo post precisa de exatamente 1 categoria primária
- Tags por post: 3-8 recomendadas, nunca exceda 15
Variáveis de Ambiente
| Variável | Propósito | Exemplo |
|---|---|---|
| CMS_TYPE | Identificador da plataforma | wordpress, shopify, ghost, strapi, sanity |
| CMS_URL | URL base do CMS | https://example.com |
| CMS_API_KEY | Credencial de autenticação | Senha de aplicativo, token de API ou chave |
Estas devem ser definidas no ambiente do shell. Nunca armazene credenciais em arquivos ou
as cometa ao controle de versão. A skill as lê via $CMS_TYPE, $CMS_URL,
e $CMS_API_KEY em tempo de execução.
Tratamento de Erros
- Variáveis de ambiente ausentes: Se CMS_TYPE, CMS_URL ou CMS_API_KEY não estiver definida, informe qual variável está faltando e forneça o formato esperado
- Credenciais inválidas: Se a API do CMS retornar 401/403, informe "Falha na autenticação - verifique CMS_API_KEY" e não tente novamente
- Timeouts de conexão: Se o endpoint do CMS estiver inacessível após 10 segundos, informe o timeout e sugira verificar CMS_URL
- Slugs de tag duplicados: Se uma tag já existir no CMS, pule a criação e anote "Tag já existe: [nome]"
- Limites de taxa: Se a API do CMS retornar 429, aguarde e tente novamente uma vez. Informe se o limite persistir
- CMS não suportado: Se CMS_TYPE não for uma das 5 plataformas suportadas, liste as opções válidas e saia