Free SKILL.md scraped from GitHub. Clone the repo or copy the file directly into your Claude Code skills directory.
npx versuz@latest install evolution-foundation-evo-nexus-claude-skills-cs-kb-articlegit clone https://github.com/evolution-foundation/evo-nexus.gitcp evo-nexus/SKILL.MD ~/.claude/skills/evolution-foundation-evo-nexus-claude-skills-cs-kb-article/SKILL.md---
name: cs-kb-article
description: Redige um artigo para base de conhecimento a partir de um problema resolvido ou pergunta frequente. Use quando a resolução de um ticket vale ser documentada para self-service, a mesma pergunta continua aparecendo, um workaround precisa ser publicado, ou um problema conhecido deve ser comunicado aos clientes. / Draft a knowledge base article from a resolved issue or common question. Use when a ticket resolution is worth documenting for self-service, the same question keeps coming up, a workaround needs to be published, or a known issue should be communicated to customers.
argument-hint: "<problema resolvido ou ticket>"
---
# /cs-kb-article
> Se encontrar integrações não configuradas, verifique [CONNECTORS.md](../../CONNECTORS.md).
Redigir um artigo de base de conhecimento pronto para publicação a partir de um problema de suporte resolvido, pergunta frequente ou workaround documentado. Estrutura o conteúdo para pesquisabilidade e self-service.
## Usage
```
/cs-kb-article <problema resolvido, referência de ticket ou descrição do tópico>
```
Exemplos:
- `/cs-kb-article Como configurar SSO com Okta — resolvi isso para 3 clientes no mês passado`
- `/cs-kb-article Ticket #4521 — cliente não conseguia exportar dados com mais de 10k linhas`
- `/cs-kb-article Pergunta frequente: como configurar notificações via webhook`
- `/cs-kb-article Problema conhecido: gráficos do dashboard não carregam no Safari 16`
## Workflow
### 1. Entender o Material Fonte
Analisar o input para identificar:
- **Qual foi o problema?** O problema original, pergunta ou erro
- **Qual foi a solução?** A resolução, workaround ou resposta
- **Quem é afetado?** Tipo de usuário, nível de plano ou configuração
- **Qual é a frequência?** Problema único ou recorrente
- **Qual tipo de artigo se encaixa melhor?** How-to, troubleshooting, FAQ, problema conhecido ou referência (ver tipos de artigo abaixo)
Se uma referência de ticket for fornecida, buscar o contexto completo:
- **int-evo-crm** (`/int-evo-crm`): Puxar o thread do ticket, resolução e quaisquer notas internas
- **Notion MCP**: Verificar se um artigo similar já existe (atualizar vs. criar novo)
- **int-linear-review** (`/int-linear-review`) ou **Linear MCP**: Verificar se há bug report ou feature request relacionado
### 2. Redigir o Artigo
Usando a estrutura de artigo, padrões de formatação e boas práticas de pesquisabilidade abaixo:
- Seguir o template para o tipo de artigo escolhido (how-to, troubleshooting, FAQ, problema conhecido ou referência)
- Aplicar as boas práticas de pesquisabilidade: título em linguagem do cliente, frase de abertura em linguagem simples, mensagens de erro exatas, sinônimos comuns
- Manter escaneável: headers, passos numerados, parágrafos curtos
### 3. Gerar o Artigo
Apresentar o rascunho com metadados:
```
## Rascunho de Artigo KB
**Título:** [Título do artigo]
**Tipo:** [How-to / Troubleshooting / FAQ / Problema Conhecido / Referência]
**Categoria:** [Área de produto ou tópico]
**Tags:** [Tags pesquisáveis]
**Público:** [Todos os usuários / Admins / Desenvolvedores / Plano específico]
---
[Conteúdo completo do artigo — usando o template apropriado abaixo]
---
### Notas de Publicação
- **Fonte:** [Ticket #, conversa com cliente, ou discussão interna]
- **Artigos existentes para atualizar:** [Se isso tem sobreposição com conteúdo existente]
- **Revisão necessária de:** [SME ou time se precisar verificar precisão técnica]
- **Data de revisão sugerida:** [Quando revisitar para verificar precisão]
```
### 4. Oferecer Próximos Passos
Após gerar o artigo:
- "Quer que eu verifique se um artigo similar já existe no Notion?"
- "Devo ajustar a profundidade técnica para um público diferente?"
- "Quer que eu redija um artigo complementar (ex: um how-to para acompanhar este guia de troubleshooting)?"
- "Devo criar uma versão apenas interna com detalhes técnicos adicionais?"
---
## Estrutura de Artigo e Padrões de Formatação
### Elementos Universais de Artigo
Todo artigo KB deve incluir:
1. **Título**: Claro, pesquisável, descreve o resultado ou problema (não jargão interno)
2. **Overview**: 1-2 frases explicando o que o artigo cobre e para quem é
3. **Corpo**: Conteúdo estruturado adequado ao tipo de artigo
4. **Artigos relacionados**: Links para conteúdo complementar relevante
5. **Metadados**: Categoria, tags, público, data da última atualização
### Regras de Formatação
- **Usar headers (H2, H3)** para dividir o conteúdo em seções escaneáveis
- **Usar listas numeradas** para passos sequenciais
- **Usar listas de bullets** para itens não sequenciais
- **Usar negrito** para nomes de elementos de UI, termos-chave e ênfase
- **Usar blocos de código** para comandos, chamadas de API, mensagens de erro e valores de configuração
- **Usar tabelas** para comparações, opções ou dados de referência
- **Usar callouts/notas** para avisos, dicas e ressalvas importantes
- **Manter parágrafos curtos** — 2-4 frases no máximo
- **Uma ideia por seção** — se uma seção cobre dois tópicos, dividir
## Escrevendo para Pesquisabilidade
Artigos são inúteis se os clientes não conseguem encontrá-los. Otimizar cada artigo para busca:
### Boas Práticas de Título
| Bom Título | Título Ruim | Por quê |
|------------|-----------|-----|
| "Como configurar SSO com Okta" | "Configuração SSO" | Específico, inclui o nome da ferramenta que clientes buscam |
| "Fix: Dashboard mostra página em branco" | "Problema no Dashboard" | Inclui o sintoma que os clientes vivenciam |
| "Rate limits e quotas da API" | "Informações da API" | Inclui os termos específicos que clientes buscam |
| "Erro: 'Connection refused' ao importar dados" | "Problemas de Importação" | Inclui a mensagem de erro exata |
### Otimização de Palavras-Chave
- **Incluir mensagens de erro exatas** — clientes copiam e colam texto de erro na busca
- **Usar linguagem do cliente**, não terminologia interna — "não consigo fazer login" não "falha de autenticação"
- **Incluir sinônimos comuns** — "deletar/remover", "dashboard/página inicial", "exportar/baixar"
- **Adicionar fraseamentos alternativos** — abordar o mesmo problema de ângulos diferentes no overview
- **Taguear por áreas de produto** — garantir que categoria e tags correspondam à forma como clientes pensam sobre o produto
### Fórmula de Frase de Abertura
Começar cada artigo com uma frase que recoloca o problema ou tarefa em linguagem simples:
- **How-to**: "Este guia mostra como [realizar X]."
- **Troubleshooting**: "Se você estiver vendo [sintoma], este artigo explica como corrigir."
- **FAQ**: "[Pergunta nas palavras do cliente]? Aqui está a resposta."
- **Problema conhecido**: "Alguns usuários estão vivenciando [sintoma]. Aqui está o que sabemos e como contornar."
## Templates por Tipo de Artigo
### Artigos How-to
**Objetivo**: Instruções passo a passo para realizar uma tarefa.
**Estrutura**:
```
# Como [realizar tarefa]
[Overview — o que este guia cobre e quando usá-lo]
## Pré-requisitos
- [O que é necessário antes de começar]
## Passos
### 1. [Ação]
[Instrução com detalhes específicos]
### 2. [Ação]
[Instrução]
## Verificar se Funcionou
[Como confirmar o sucesso]
## Problemas Comuns
- [Problema]: [Solução]
## Artigos Relacionados
- [Links]
```
**Boas práticas**:
- Começar cada passo com um verbo
- Incluir o caminho específico: "Vá em Configurações > Integrações > Chaves de API"
- Mencionar o que o usuário deve ver após cada passo ("Você deve ver um banner verde de confirmação")
- Testar os passos você mesmo ou verificar com uma resolução recente de ticket
### Artigos de Troubleshooting
**Objetivo**: Diagnosticar e resolver um problema específico.
**Estrutura**:
```
# [Descrição do problema — o que o usuário vê]
## Sintomas
- [O que o usuário observa]
## Causa
[Por que isso acontece — explicação breve e sem jargão]
## Solução
### Opção 1: [Correção principal]
[Passos]
### Opção 2: [Alternativa se a Opção 1 não funcionar]
[Passos]
## Prevenção
[Como evitar isso no futuro]
## Ainda Com Problemas?
[Como obter ajuda]
```
**Boas práticas**:
- Começar com sintomas, não causas — clientes buscam pelo que veem
- Fornecer múltiplas soluções quando possível (correção mais provável primeiro)
- Incluir uma seção "Ainda com problemas?" que aponta para o suporte
- Se a causa raiz for complexa, manter a explicação voltada ao cliente simples
### Artigos FAQ
**Objetivo**: Resposta rápida a uma pergunta comum.
**Estrutura**:
```
# [Pergunta — nas palavras do cliente]
[Resposta direta — 1-3 frases]
## Detalhes
[Contexto adicional, nuances ou explicação se necessário]
## Perguntas Relacionadas
- [Link para FAQ relacionado]
- [Link para FAQ relacionado]
```
**Boas práticas**:
- Responder a pergunta na primeira frase
- Manter conciso — se a resposta precisa de um passo a passo, é um how-to, não um FAQ
- Agrupar FAQs relacionados e criar links entre eles
### Artigos de Problema Conhecido
**Objetivo**: Documentar um bug conhecido ou limitação com um workaround.
**Estrutura**:
```
# [Problema Conhecido]: [Descrição breve]
**Status:** [Investigando / Workaround Disponível / Correção em Progresso / Resolvido]
**Afetados:** [Quem/o que é afetado]
**Última atualização:** [Data]
## Sintomas
[O que os usuários vivenciam]
## Workaround
[Passos para contornar o problema, ou "Nenhum workaround disponível"]
## Prazo de Correção
[Data prevista de correção ou status atual]
## Atualizações
- [Data]: [Atualização]
```
**Boas práticas**:
- Manter o status atualizado — nada corrói a confiança mais rápido do que um artigo de problema conhecido desatualizado
- Atualizar o artigo quando a correção for lançada e marcar como resolvido
- Se resolvido, manter o artigo ativo por 30 dias para clientes ainda buscando os sintomas antigos
## Cadência de Revisão e Manutenção
Bases de conhecimento decaem sem manutenção. Seguir esse cronograma:
| Atividade | Frequência | Quem |
|----------|-----------|-----|
| **Revisão de novo artigo** | Antes de publicar | Revisão de par + SME para conteúdo técnico |
| **Auditoria de precisão** | Trimestral | Time de suporte revisa artigos de maior tráfego |
| **Verificação de conteúdo obsoleto** | Mensal | Sinalizar artigos não atualizados em 6+ meses |
| **Atualizações de problemas conhecidos** | Semanal | Atualizar status em todos os problemas conhecidos abertos |
| **Revisão de analytics** | Mensal | Verificar quais artigos têm baixas avaliações de utilidade ou altas taxas de rejeição |
| **Análise de gaps** | Trimestral | Identificar principais tópicos de tickets sem artigos KB |
### Ciclo de Vida do Artigo
1. **Rascunho**: Escrito, precisa de revisão
2. **Publicado**: Ativo e disponível para clientes
3. **Precisa de atualização**: Sinalizado para revisão (mudança de produto, feedback ou idade)
4. **Arquivado**: Não mais relevante mas preservado para referência
5. **Retirado**: Removido da base de conhecimento
### Quando Atualizar vs. Criar Novo
**Atualizar existente** quando:
- O produto mudou e os passos precisam ser atualizados
- O artigo está majoritariamente correto mas falta um detalhe
- Feedback indica que clientes estão confusos com uma seção específica
- Um workaround ou solução melhor foi encontrado
**Criar novo** quando:
- Uma nova feature ou área de produto precisa de documentação
- Um ticket resolvido revela um gap — nenhum artigo existe para esse tópico
- O artigo existente cobre muitos tópicos e deve ser dividido
- Um público diferente precisa da mesma informação explicada de forma diferente
## Taxonomia de Links e Categorização
### Estrutura de Categorias
Organizar artigos em uma hierarquia que corresponde à forma como os clientes pensam:
```
Primeiros Passos
├── Configuração de conta
├── Configuração inicial
└── Guias de início rápido
Features e How-tos
├── [Área de feature 1]
├── [Área de feature 2]
└── [Área de feature 3]
Integrações
├── [Integração 1]
├── [Integração 2]
└── Referência de API
Troubleshooting
├── Erros comuns
├── Problemas de performance
└── Problemas conhecidos
Billing e Conta
├── Planos e preços
├── Dúvidas de billing
└── Gerenciamento de conta
```
### Boas Práticas de Links
- **Link de troubleshooting para how-to**: "Para instruções de configuração, veja [Como configurar X]"
- **Link de how-to para troubleshooting**: "Se encontrar erros, veja [Troubleshooting X]"
- **Link de FAQ para artigos detalhados**: "Para um passo a passo completo, veja [Guia de X]"
- **Link de problemas conhecidos para workarounds**: Manter a cadeia do problema para a solução curta
- **Usar links relativos** dentro do KB — sobrevivem melhor a reestruturações do que URLs absolutas
- **Evitar links circulares** — se A linka para B, B não deve linkar de volta para A a menos que ambos sejam pontos de entrada genuinamente úteis
## Boas Práticas de Escrita KB
1. Escrever para o cliente que está frustrado e buscando uma resposta — ser claro, direto e útil
2. Todo artigo deve ser encontrável através de busca usando as palavras que um cliente digitaria
3. Testar seus artigos — seguir os passos você mesmo ou pedir a alguém não familiarizado com o tópico para segui-los
4. Manter artigos focados — um problema, uma solução. Dividir se um artigo estiver crescendo demais
5. Manter agressivamente — um artigo errado é pior que nenhum artigo
6. Rastrear o que está faltando — todo ticket que poderia ter sido um artigo KB é um gap de conteúdo
7. Medir impacto — artigos que não recebem tráfego ou não reduzem tickets precisam ser melhorados ou retirados