pbi-doc
- Repo stars 74
- Author updated Live
- Author repo claude-code-powerbi-skills
- Domain
- Security
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- 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
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: pbi-doc
description: Documenta projeto Power BI (PBIP) inteiro em markdown estruturado + HTML navegável (mini-site de…
category: security
runtime: Python
---
# pbi-doc output preview
## PART A: Task fit
- Use case: Documenta projeto Power BI (PBIP) inteiro em markdown estruturado + HTML navegável (mini-site de doc). Use quando o usuário pedir "documenta esse projeto", "gera doc do power bi", "explica esse modelo", "preciso entregar handoff", ou apontar uma pasta PBIP pra mapeamento descritivo (não auditoria)..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Quando usar / Pré-requisitos / Modos de execução” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Documenta projeto Power BI (PBIP) inteiro em markdown estruturado + HTML navegável (mini-site de doc). Use quando o usuário pedir "documenta esse projeto", "gera doc do power bi", "explica esse modelo", "preciso entregar handoff", ou apontar uma pasta PBIP pra mapeamento descritivo (não auditoria).”.
- **02** When the source has headings, the agent prioritizes “Quando usar / Pré-requisitos / Modos de execução” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source mentions slash commands such as `/pbi-doc`, `/pbi-modelo-review`, `/pbi-dax-create`, `/pbi-export-medidas`; use them first when your agent supports command triggers.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Start with a small task and check whether the result follows “Quando usar / Pré-requisitos / Modos de execução”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: pbi-doc
description: Documenta projeto Power BI (PBIP) inteiro em markdown estruturado + HTML navegável (mini-site de…
category: security
source: xperiun/claude-code-powerbi-skills
---
# pbi-doc
## When to use
- Documenta projeto Power BI (PBIP) inteiro em markdown estruturado + HTML navegável (mini-site de doc). Use quando o us…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Quando usar / Pré-requisitos / Modos de execução” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "pbi-doc" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Quando usar / Pré-requisitos / Modos de execução
rules -> SKILL.md triggers / order / output contract
runtime -> Python | read files, write/modify files, run shell commands | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} /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 (Pythonzipfile, 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
.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 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
.tmdlde./SemanticModel/ - Output: salvo em
./_docs/index.html+ 5 markdowns (00-overview.mda04-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
.tmdlda pastaSemanticModel/definition/(model.tmdl, relationships.tmdl, expressions.tmdl se houver) - Os arquivos da pasta
SemanticModel/definition/tables/(1 .tmdl por tabela, excluindo as auto-dateLocalDateTable_*eDateTableTemplate_*)
Pode arrastar individualmente ou zipar a pasta
SemanticModel/e subir 1 ZIP. - Os arquivos
- 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 arquivossó medidas→ só02-medidas.md(útil pra checar mudanças após refator)só tabelas→ só01-tabelas.mdsó relacionamentos→ só03-relacionamentos.mdtabela 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
.tmdlem./SemanticModel/tables/(excluirLocalDateTable_*eDateTableTemplate_*— são auto-geradas, não fazem parte da doc) - Ler
model.tmdl,relationships.tmdl,expressions.tmdl(se existir) - Ler todos os
.tmdlde 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á emreferences/escopo.mddesta skill (seção "Placeholders dotemplates/relatorio.html"). Todos os blocos{{...}}_HTMLsã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.
- ✅ Correto:
SALVAR em
./_docs/index.html(modo Code) ou retornar como artifact (modo Web).Como deve parecer: fundo
#0D0C0Equase preto · gold-grid de papel pautado dourado animado caindo · orbs azul/roxo em cada seção · risca dourada entre seções · cardsvar(--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.
- Cores como
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.htmlpra 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).
Decide Fit First
Design Intent
How To Use It
Boundaries And Review