Skills: Skill de Geração de Documentação
Última atualização: 2026-08-31
Bom código deve ser autoexplicativo, mas boa documentação evita desvios para os recém-chegados — Skills fazem da documentação um canto não esquecido.
1. Tipos de documentação e Skills
(1) Matriz de tipos de documentação
| Tipo de doc | Fonte de entrada | Formato de saída | Ferramentas do Skill |
|---|---|---|---|
| Docs de API | Definições de rotas/interfaces | Markdown/HTML | Read, Grep, Write |
| README | Configuração do projeto | Markdown | Read, Glob, Write |
| Changelog | git log | Markdown | Bash, Read, Write |
| Comentários de código | Código-fonte | Comentários inline | Read, Edit |
| Docs de arquitetura | Estrutura do projeto | Mermaid + Markdown | Glob, Read, Write |
(2) Padrões de qualidade da documentação
Boa documentação deve ser:
├── Precisa: Consistente com o comportamento real do código
├── Completa: Cobrir todas as interfaces públicas
├── Concisa: Sem enrolação, cada frase tem valor informacional
├── Atualizada: Sincronizada com as mudanças do código
└── Acessível: Formato uniforme, fácil de buscar
2. Geração de documentação de API
(1) Extrair API do código
## Fluxo de geração de docs de API
1. Glob para encontrar arquivos de rotas/controllers
2. Read cada definição de interface
3. Extrair: caminho, método, parâmetros, retornos, exceções
4. Organizar a saída por módulo
(2) Template de documentação
## POST /api/users
### Descrição
Criar um novo usuário
### Parâmetros da requisição
| Parâmetro | Tipo | Obrigatório | Descrição |
|:----------|:-----|:-----------|:----------|
| name | string | Sim | Nome de usuário |
| email | string | Sim | Endereço de email |
### Resposta
| Campo | Tipo | Descrição |
|:------|:-----|:----------|
| id | integer | ID do usuário |
| name | string | Nome de usuário |
### Erros
| Código de status | Descrição |
|:----------------|:----------|
| 400 | Falha na validação dos parâmetros |
| 409 | Email já existe |
3. Geração de README
(1) Detectar automaticamente informações do projeto
## Coleta de informações do README
1. Glob: Detectar arquivos do projeto (package.json/go.mod/pyproject.toml)
2. Read: Ler configuração para stack tecnológica, dependências, scripts
3. Grep: Buscar arquivos de entrada, variáveis de ambiente, itens de configuração
4. Bash: git log --oneline -10 para obter mudanças recentes
(2) Template de README
# Nome do Projeto
> Descrição em uma linha
## Início Rápido
### Pré-requisitos
- Node.js >= 18
- PostgreSQL >= 14
### Instalação
```bash
npm install
cp .env.example .env
npm run dev
Estrutura do Projeto
...
Guia de Desenvolvimento
...
Deploy
...
---
## 4. Geração de Changelog
### (1) Extrair mudanças do Git
```bash
# Obter mudanças entre versões
git log v1.1.0..v1.2.0 --oneline
git log v1.1.0..v1.2.0 --format="%s" --no-merges
(2) Categorizar e organizar
## v1.2.0 (2026-08-15)
### ✨ Novas Funcionalidades
- Adicionar funcionalidade de exportação de usuários (#42)
- Suporte ao modo escuro (#45)
### 🐛 Correções de Bugs
- Corrigir problema de timeout no login (#38)
- Corrigir erro na ordenação de dados (#41)
### 💔 Breaking Changes
- Mudança no formato de resposta da API /users, campo name renomeado para username
5. Skill de documentação na prática
▶ Exemplo: Geração completa de docs do projeto
Alice criou um Skill de geração de documentação do projeto com um clique:
---
name: doc-generator
description: "Geração completa de documentação do projeto com um clique"
triggers:
- keyword: "gen-docs|generate-docs"
tools:
- Read
- Grep
- Glob
- Write
- Bash
---
Bob disse: "O maior inimigo da documentação é ficar desatualizada — Skills extraem informações do código em tempo real, garantindo que docs e código estejam sempre sincronizados."
❓ Perguntas Frequentes
P: Documentação gerada automaticamente precisa de revisão humana? R: Absolutamente. A IA pode extrair informações estruturais, mas significado de negócio e cenários de uso precisam de complemento e confirmação humana. P: Onde a documentação deve ficar? R: Docs de API em
docs/api/, README na raiz do projeto, changelog emCHANGELOG.md, docs de arquitetura emdocs/architecture/. P: Como manter documentação e código sincronizados? R: Adicione etapas de verificação de documentação no CI; quando o código muda, Skills atualizam automaticamente os docs correspondentes; verifique sincronia de docs durante revisão de PR.
📖 Resumo
- Cinco tipos de doc: API, README, changelog, comentários de código, arquitetura
- Docs de API: extrair definições de interfaces do código, exibir por template
- README: detectar automaticamente informações do projeto, preencher template padrão
- Changelog: extrair commits do Git, categorizar e organizar
- Princípio central: docs sincronizados com código, IA extrai estrutura + humano adiciona semântica
📝 Exercícios
- Básico (dificuldade⭐): Crie um Skill de geração de README que detecte automaticamente a stack tecnológica do projeto e exiba um template padrão.
- Intermediário (dificuldade⭐⭐): Crie um Skill de documentação de API que extraia informações de interfaces de arquivos de rotas FastAPI/Express.
- Avançado (dificuldade⭐⭐⭐): Crie um Skill de documentação completa do projeto que exiba README + docs de API + diagrama de arquitetura + changelog como conjunto de quatro peças.
