pbi doc
- Repo stars 74
- Author repo claude-code-powerbi-skills
- Domain
- Security
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @xperiun · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# /pbi-doc — Documentação automática de Power BI
> **📦 Distribuída publicamente:** [github.com/xperiun/claude-code-powerbi-skills](https://github.com/xperiun/claude-code-powerbi-skills) — pasta `claude-code/pbi-doc/` (skill nativa) + `claude-web/pbi-doc.zip` (upload no Claude.ai). Mudança aqui exige sincronizar lá: atualizar pasta + regenerar ZIP (Python `zipfile`, ver CLAUDE.md) + commit + bump CHANGELOG. Repo é open-source, leiame público — evitar referências internas (Xperiun-only) na SKILL.md.
Gera documentação completa de um projeto Power BI (formato PBIP) em duas formas:
- **Markdown** versionável Git (5 arquivos: overview, tabelas, medidas, relacionamentos, dependências)
- **HTML standalone** navegável (mini-site com sidebar fixa, busca, syntax highlight em DAX)
A doc descreve o que **existe** no modelo — tabelas, colunas tipadas, medidas com DAX explicadas em PT, relacionamentos com cardinalidade, grafo de dependências entre medidas. **Não opina sobre qualidade** (essa é função da `/pbi-modelo-review`).
## Quando usar
- Analista herdou um `.pbix` de N tabelas e M medidas e precisa entender rápido
- Líder pedindo handoff documentado pra outro time
- Pré-onboarding de novo membro no time de dados
- Precisa de "manual de uso" do modelo pra circular junto com o relatório
- Documentação contínua: rodar a cada release pra manter doc viva no Git
**Não usar quando:**
- Quer auditoria de qualidade / anti-patterns → use `/pbi-modelo-review`
- Quer criar uma medida nova → use `/pbi-dax-create`
- Quer só extrair lista de medidas em CSV (skill futura `/pbi-export-medidas`)
## Pré-requisitos
1. **Projeto em formato PBIP** (Power BI Project) — pasta com `.SemanticModel/` e `.Report/`. Se o usuário só tem `.pbix`, instruir conversão **antes**:
- `Power BI Desktop → File → Save as → Power BI Project (.pbip)`
2. Acesso aos arquivos `.tmdl` (via filesystem ou upload — ver "Modos de execução" abaixo)
Se faltar PBIP, retornar mensagem curta:
> Esse projeto ainda está em `.pbix` (binário). Pra eu documentar, salva como Power BI Project: `File → Save as → Power BI Project (.pbip)`. Vira uma pasta de texto e aí eu consigo ler. Avisa quando converter.
E encerrar — não tentar nada.
## Modos de execução
A skill detecta automaticamente o ambiente e adapta input/output:
### Modo Code (Claude Code · Desktop · file-based)
- **Detecção**: tenho acesso a filesystem e a pasta atual contém `.SemanticModel/`
- **Input**: leio automaticamente os `.tmdl` de `./SemanticModel/`
- **Output**: salvo em `./_docs/index.html` + 5 markdowns (`00-overview.md` a `04-dependencias.md`) na raiz do projeto Power BI
- **Idempotente**: rodar 2x sobrescreve
### Modo Web (Claude.ai · upload-based)
- **Detecção**: não tenho acesso a filesystem (claude.ai web)
- **Input**: peço ao usuário pra anexar os arquivos:
> Pra eu documentar, anexe nesse chat:
> - Os arquivos `.tmdl` da pasta `SemanticModel/definition/` (model.tmdl, relationships.tmdl, expressions.tmdl se houver)
> - Os arquivos da pasta `SemanticModel/definition/tables/` (1 .tmdl por tabela, **excluindo** as auto-date `LocalDateTable_*` e `DateTableTemplate_*`)
>
> Pode arrastar individualmente ou zipar a pasta `SemanticModel/` e subir 1 ZIP.
- **Output**:
- HTML completo (mini-site navegável) como **artifact** (Claude.ai renderiza inline + botão de download)
- Os 5 markdowns como blocos de código no chat (copiáveis um a um) OU 1 ZIP com todos
- **Não persiste**: cada conversa nova requer novo upload
### Detecção automática
Verificar se a pasta `.SemanticModel/` é acessível via filesystem:
- ✅ Sim → Modo Code (file-based)
- ❌ Não → Modo Web (peço uploads)
Se ambíguo, perguntar uma vez:
> Você tá rodando isso no **Claude Code** (CLI/IDE com acesso à pasta) ou no **claude.ai** (web)? Pra Code eu leio a pasta sozinho; pra web preciso que você suba os arquivos.
### Trade-offs por modo
| Aspecto | Code | Web |
|---|---|---|
| Setup | 1× (instala skill) | 0 (só sobe arquivo) |
| Por uso | comando único | anexar TMDL toda vez |
| Modelo grande (>200 medidas) | OK | pode estourar contexto Free |
| Persistência | salva em disco | só na conversa (baixar artifact) |
| Custo | tokens Claude Code | tokens claude.ai (Free incluído) |
## Inputs
- **Escopo** (opcional, default: `tudo`)
- `tudo` → todos os 5 arquivos
- `só medidas` → só `02-medidas.md` (útil pra checar mudanças após refator)
- `só tabelas` → só `01-tabelas.md`
- `só relacionamentos` → só `03-relacionamentos.md`
- `tabela X` → restringe descrição às tabelas específicas (separadas por vírgula)
Se não especificado, perguntar **uma vez**:
> Documento o projeto inteiro (5 arquivos) ou prefere algo específico — só medidas, só relacionamentos, ou tabelas específicas?
## Processo
### 1. Detectar e mapear
- Confirmar `.SemanticModel/`
- Listar `.tmdl` em `./SemanticModel/tables/` (excluir `LocalDateTable_*` e `DateTableTemplate_*` — são auto-geradas, não fazem parte da doc)
- Ler `model.tmdl`, `relationships.tmdl`, `expressions.tmdl` (se existir)
- Ler **todos** os `.tmdl` de tabelas
- Inventariar:
- **Tabelas**: nome, tipo (fato/dim/measures-only), descrição, granularidade inferida, lista de colunas, partição/source M
- **Medidas**: nome, expressão DAX, displayFolder (agrupa), formatString, descrição (se existir), referências a outras medidas
- **Relacionamentos**: from, to, cardinalidade, direção, ativo
- **Dependências**: medida X usa medida Y; medida Z usa coluna W
### 2. Gerar 5 arquivos markdown
Ler templates em `templates/` e preencher com dados reais. Salvar em `./_docs/` na raiz do projeto Power BI:
| Arquivo | Conteúdo |
|---|---|
| `_docs/00-overview.md` | Sumário (N tabelas, N medidas, N relacionamentos, fontes, propósito inferido) |
| `_docs/01-tabelas.md` | Cada tabela: descrição, granularidade, colunas tipadas, source M (resumo) |
| `_docs/02-medidas.md` | Agrupadas por displayFolder. Cada uma: nome, DAX, explicação PT linha-a-linha |
| `_docs/03-relacionamentos.md` | Lista detalhada + diagrama em ASCII art (matriz simples) |
| `_docs/04-dependencias.md` | Grafo: árvore "medida X → usa Y → usa Z" + lista reverse "Y é usada por: A, B, C" |
### 3. Gerar HTML standalone
**🚨 REGRA INVIOLÁVEL — usar templates/relatorio.html LITERAL:**
1. **LER** `templates/relatorio.html` — esse arquivo já tem **todo o CSS, todo o HTML estrutural, todos os tokens DS v4 (Bebas Neue, accent-gold, gold-grid + beams animados, orb-v2 elipses blue/purple, riscas section+section::before, brackets), todo o JS de scroll spy/busca**. CSS são ~600 linhas inline + HTML completo com gold-grid, sidebar, topbar, sections.
2. **SUBSTITUIR APENAS os placeholders `{{...}}`** pelos valores reais derivados dos `.tmdl`. Lista completa dos placeholders está em `references/escopo.md` desta skill (seção "Placeholders do `templates/relatorio.html`"). Todos os blocos `{{...}}_HTML` são gerados pelo Claude com base no inventário do modelo.
3. **PROIBIDO:**
- ❌ Trocar o CSS por outro
- ❌ Inventar nova paleta de cores (usar SÓ os tokens do template: `--accent-gold-bright #E8C9A0`, `--accent-glow #7099FF`, `--neon-magenta #C47FFF`, etc.)
- ❌ Mudar fontes (DS v4 usa Bebas Neue + Barlow Condensed + Outfit + JetBrains Mono — nada de Segoe UI, Arial, system-ui)
- ❌ Remover o `<div class="gold-grid">`, os `<div class="section-orb">`, ou qualquer ornamento decorativo do template
- ❌ Gerar HTML "do zero" porque parece mais fácil — **isso queima toda a identidade visual Xperiun**
- ❌ **Tocar em qualquer coisa dentro de comentários `<!-- ... -->`** — comentários são instruções pra você, não conteúdo a substituir. Mantém como tá.
- ❌ **Tocar em `<style>...</style>` ou `<script>...</script>`** — CSS e JS ficam intocados.
4. **🚨 ENCODING — UTF-8 PURO, sem escape.** Caracteres PT-BR (`ã`, `ç`, `é`, `á`, `õ`, `ê`, `í`, `ú`) e símbolos especiais (`├`, `└`, `─`, `→`, `↔`, `↑`, `↓`, `⚠`, `·`, `—`) devem aparecer como **caracteres reais UTF-8**, NÃO como sequências escapadas/HTML entities/mojibake.
- ✅ Correto: `dependências`, `└─`, `→`, `Incomparáveis`
- ❌ Errado (mojibake): `dependências`, `âââ`, `â`, `Incomparáveis`
- ❌ Errado (entities desnecessárias): `dependências`
- **Sintoma de erro:** se algum acento aparece como sequência de 2-3 chars estranhos (`ã`, `â`, `é`), o parser HTML pode quebrar e o resto da página renderiza como texto cru. Refaz garantindo UTF-8.
5. **SALVAR** em `./_docs/index.html` (modo Code) ou retornar como artifact (modo Web).
6. **Como deve parecer:** fundo `#0D0C0E` quase preto · gold-grid de papel pautado dourado animado caindo · orbs azul/roxo em cada seção · risca dourada entre seções · cards `var(--gradient-surface)` com border `--border-faint` · números em Bebas Neue gold · DAX com syntax highlight via spans `.k .f .s .c`. Estilo "editorial premium dark" — não dashboard genérico tipo Vercel/Stripe.
7. **Sintomas de erro:**
- Cores como `#f5a623` (laranja) ou `#7c6af7` (roxo genérico), ou fonte `'Segoe UI'` → ignorou o template, refaz.
- Acentos como `ã` ou `â` → encoding quebrado, refaz com UTF-8 puro.
- Texto solto sem quebras (SVG/tabela aparecendo como prosa) → encoding mojibake quebrou o parser HTML, refaz.
### 4. Resumir no chat
Mensagem curta:
- Quantidade do que foi documentado (5 tabelas, 19 medidas, 4 relacionamentos)
- Path dos arquivos gerados
- Sugestão: "Abre `_docs/index.html` pra ver navegável"
## Outputs
```
[raiz do projeto Power BI do usuário]/
├── SemanticModel/ ← input (não tocar)
├── Report/ ← input (não tocar)
└── _docs/ ← OUTPUT da skill
├── 00-overview.md
├── 01-tabelas.md
├── 02-medidas.md
├── 03-relacionamentos.md
├── 04-dependencias.md
└── index.html ← versão visual standalone
```
## Edge cases
| Cenário | O que fazer |
|---|---|
| Sem `.SemanticModel/` | Mensagem de pré-requisito (PBIP), encerra |
| Pasta `_docs/` já existe | **Sobrescrever** (idempotente) — avisar no chat |
| Modelo gigante (>200 medidas) | Avisar tempo + processar em chunks |
| Tabelas auto-date (`LocalDateTable_*`, `DateTableTemplate_*`) | **Excluir da doc** — são tabelas-fantasma, não fazem parte do modelo intencional |
| Medida com DAX muito complexo (>30 linhas) | Mostrar DAX completo + explicar em **blocos** (se / agg / contexto) |
| Modelo sem nenhuma descrição declarada | Inferir propósito a partir de naming + estrutura, mas sinalizar "descrição inferida (não há `description:` declarado)" |
## Tom da documentação
Estilo Xperiun:
- **PT-BR direto, não robótico**. Em vez de "A tabela X possui Y colunas", escrever "Vendas — fato principal do modelo, 1 linha = 1 item de NFe, 12 colunas (5 chaves + 7 atributos)"
- Pode usar metáforas concretas pra explicar DAX complexo
- Manter tom de "colega sênior explicando o modelo pro novo membro do time"
- PT-BR com **todos os acentos** (regra inviolável CLAUDE.md)
Exemplos de **bom** vs **ruim**:
❌ Ruim: "A medida 'Faturamento' calcula o resultado da multiplicação entre QtdItens e PrecoUnitario."
✅ Bom: "**Faturamento** — multiplica quantidade × preço linha-a-linha em fVendas e soma o total. É a medida-mãe: várias outras (Margem Bruta, %YoY, etc) dependem dela."
## Idempotência e segurança
- Rodar 2x **sobrescreve** `_docs/`
- Não modifica nada em `.SemanticModel/` ou `.Report/` — somente leitura
- Não commita nada (segue regra git inviolável CLAUDE.md)
- Operação 100% local — zero rede, zero XMLA
## Branding
HTML tem footer fixo:
- "Doc gerada por Claude Code + /pbi-doc · Xperiun"
- CTA: "Quero usar esse skill no meu Power BI →"
- Meta: "XPERIUN · O Sistema Operacional dos Incomparáveis · pages.xperiun.com"
Branding sempre Xperiun.
## Tempo típico
- Modelo pequeno (≤30 tabelas, ≤80 medidas): **2–4 min**
- Modelo médio (~50 tabelas, ~150 medidas): **5–8 min**
- Modelo grande (>200 medidas): **10–15 min**
Avisar se >5min esperados.
## Versão atual
`v0.1` — protótipo interno Xperiun OS. Quando estabilizar, vira pacote no repo público `xperiun/claude-code-powerbi-skills` (lead magnet).
Sections and files
Listed in source order.
sections -> Quando usar → Pré-requisitos → Modos de execução → Modo Code (Claude Code · Desktop · file-based) → Modo Web (Claude.ai · upload-based) → Detecção automática
terms -> 📦 Distribuída publicamente · Markdown · HTML standalone · existe · Não opina sobre qualidade · Não usar quando · Projeto em formato PBIP · antes
files/cmd -> claude-code/pbi-doc/ · claude-web/pbi-doc.zip · zipfile · /pbi-modelo-review · .pbix · /pbi-dax-create · /pbi-export-medidas · .SemanticModel/
body sha256 -> 2b95461109e0
Quando usar
Analista herdou um
.pbixde N tabelas e M medidas e precisa entender rápido Líder pedindo handoff documentado pra outro time Pré-onboarding de novo membro no time de dados Precisa de "manual de uso" do modelo pra circular junto com o relatório Documentação contínua: rodar a cada release pra manter doc viva no GitPré-requisitos
Projeto em formato PBIP (Power BI Project) — pasta com
.SemanticModel/e.Report/. Se o usuário só tem.pbix, instruir conversão antes:Power BI Desktop → File → Save as → Power BI Project (.pbip)Acesso aos arquivos.tmdl(via filesystem ou upload — ver "Modos de execução" abaixo) Se faltar PBIP, retornar mensagem curta: Esse projeto ainda está em.pbix(binário). Pra eu documentar, salva como Power BI Project:File → Save as → Power BI Project (.pbip). Vira uma pasta de texto e aí eu consigo ler. Avisa quando converter.Modos de execução
A skill detecta automaticamente o ambiente e adapta input/output:
Modo Code (Claude Code · Desktop · file-based)
Detecção: tenho acesso a filesystem e a pasta atual contém
.SemanticModel/Input: leio automaticamente os.tmdlde./SemanticModel/Output: salvo em./_docs/index.html+ 5 markdowns (00-overview.mda04-dependencias.md) na raiz do projeto Power BI Idempotente: rodar 2x sobrescreveModo Web (Claude.ai · upload-based)
Detecção: não tenho acesso a filesystem (claude.ai web) Input: peço ao usuário pra anexar os arquivos: Pra eu documentar, anexe nesse chat: - Os arquivos
.tmdlda pastaSemanticModel/definition/(model.tmdl, relationships.tmdl, expressions.tmdl se houver) - Os arquivos da pastaSemanticModel/definition/tables/(1 .tmdl por tabela, excluindo as auto-dateLocalDateTable_*eDateTableTemplate_*)