Pbi Doc Skill for Claude

/pbi-doc — Documentação automática de Power BI

> 📦 Distribuída publicamente: 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

• 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.

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:

• 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.

• 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.

• 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.

• 🚨 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.

• SALVAR em ./_docs/index.html (modo Code) ou retornar como artifact (modo Web).

• 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.

• 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).