文件
- 作者仓库星标 74
- 作者仓库 claude-code-powerbi-skills
- 领域
- 安全
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @xperiun · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
[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
# /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).
章节与文件索引
按说明文件中的顺序排列。
何时使用
先决条件
执行模式
代码模式(克劳德代码·桌面·基于文件)
Web 模式(Claude.ai · 基于上传)
文件/命令 -> claude-code/pbi-doc/ · claude-web/pbi-doc.zip · zipfile · /pbi-modelo-review · .pbix · /pbi-dax-create · /pbi-export-medidas · .SemanticModel/
内容校验值 -> 2b95461109e0
当前原文的自动摘译,尚未人工审校。
何时使用
分析师继承了 N 个表和 M 个测量值的
.pbix,需要快速理解领导者要求将文件移交到另一个团队数据团队中新成员的预加入需要模型的“用户手册”以与报告一起循环连续文档:与每个版本一起运行以保持文档在 Git 中的活力先决条件
PBIP 格式的项目(Power BI 项目)— 包含
.SemanticModel/和.Report/的文件夹。如果用户只有.pbix,则先指示转换:Power BI Desktop → File → Save as → Power BI Project (.pbip)访问文件.tmdl(通过文件系统或上传 - 参见下面的“执行模式”) 如果缺少PBIP,则返回短信:此项目仍为.pbix(二进制)。为了便于我记录,请另存为 Power BI 项目:File → Save as → Power BI Project (.pbip)。它变成一个文本文件夹,然后我可以阅读它。通知您何时转换。执行模式
该技能自动检测环境并调整输入/输出:
代码模式(克劳德代码·桌面·基于文件)
检测:我有权访问文件系统,并且当前文件夹包含
.SemanticModel/输入:我自动从./SemanticModel/读取.tmdl输出:保存在 Power BI 项目根目录中的./_docs/index.html+ 5 个降价(00-overview.md到04-dependencias.md) 幂等:运行 2 次覆盖Web 模式(Claude.ai · 基于上传)
检测:我无权访问文件系统(claude.ai web) 输入:我要求用户附加文件:要我记录,请附加到此聊天: - 文件夹
SemanticModel/definition/中的文件.tmdl(model.tmdl、relationships.tmdl、表达式.tmdl,如果有) - 文件夹SemanticModel/definition/tables/中的文件(每个表 1 个 .tmdl,不包括自动日期LocalDateTable_*和DateTableTemplate_*)