convez.ai
SkillDados & AnalyticsIntermediário
BayramAnnakov

Excel Hygiene

BayramAnnakov/excel-hygiene

Auditor automático de planilhas Excel com duas camadas de verificação

Ver no GitHub
BomPluginScore · de 0 a 100

Skill que funciona como 'segunda opinião' para arquivos .xlsx, combinando verificações mecânicas determinísticas (openpyxl) com raciocínio baseado na taxonomia de erros Panko–Halverson. Detecta números armazenados como texto, fórmulas sobrescritas, erros de célula, SUMs truncados, percentuais formatados incorretamente e outras anomalias estruturais.

Instalação

$npx convez-ai BayramAnnakov/excel-hygiene

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
18
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Validar integridade de arquivos .xlsx antes de enviar para stakeholders
  • Detectar erros mecânicos (números como texto, fórmulas sobrescritas, células de erro)
  • Identificar inconsistências lógicas e estruturais em planilhas de negócio
  • Servir como base genérica para skills de domínio específico com regras customizadas

Veredito

Skill bem arquitetado que resolve um problema prático tangível — validação de planilhas. A separação entre camada mecânica (determinística, alta confiança) e raciocínio baseado em taxonomia (confirmável) é sólida. Recomendado para equipes que trabalham intensivamente com Excel e precisam de governança de dados antes de distribuição.

README

A tradução para o português deste README ainda está na fila.

excel-hygiene

A rigorous "second pair of eyes" on any .xlsx before it goes out — packaged as a Claude Code / Agent Skills skill.

It combines two layers:

  1. A deterministic Python script (scripts/check_excel.py, openpyxl-only) for precise, reproducible mechanical checks.
  2. LLM reasoning driven by the full Panko–Halverson (2008) spreadsheet-error taxonomy embedded in SKILL.md — violations vs errors · qualitative vs quantitative · mistakes / slips / lapses · life-cycle stages — applied with general business and spreadsheet knowledge.

The script is a floor, not a ceiling: the skill explicitly tells the agent to reason beyond the listed checks, never to treat them as a fixed checklist. It is client-agnostic — no business rules are baked in.

What the script catches (mechanical, high-confidence)

CheckWhat it flags
Number as textA numeric value stored as a string → SUM silently skips it, the total is understated
Number over formulaA static number sitting in a column that is otherwise formulas → a formula may have been overwritten
Cell error#DIV/0! / #REF! / … literals (EN and RU), and formulas that divide by zero
Truncated SUMA vertical SUM that stops before the last populated data row → a row may be dropped
Percent as whole numberA value > 1 in a column whose header contains % → likely off by ×100

Everything else — logic errors, omissions, ambiguous units, structural smells — is surfaced by the agent's reasoning against the taxonomy, and marked "confirm" (lower confidence than the script).

Install

This is a personal/project skill — just drop the folder where Claude Code looks for skills.

Personal (all projects):

git clone https://github.com/BayramAnnakov/excel-hygiene ~/.claude/skills/excel-hygiene
pip install -r ~/.claude/skills/excel-hygiene/requirements.txt

Project-scoped (this repo only):

git clone https://github.com/BayramAnnakov/excel-hygiene .claude/skills/excel-hygiene
pip install -r .claude/skills/excel-hygiene/requirements.txt

The same SKILL.md folder also works in other Agent-Skills hosts (e.g. Cursor) — point them at their skills directory instead.

Usage

Once installed, the agent invokes it automatically when you ask it to review a spreadsheet ("check this xlsx for errors"), or you can call it directly:

/excel-hygiene

You can also run the mechanical checker on its own, no agent required:

python3 scripts/check_excel.py path/to/file.xlsx

Try it on the bundled example, which trips every check:

python3 scripts/check_excel.py examples/broken.xlsx

The two-layer pattern (generic + your domain skill)

excel-hygiene is the universal layer. It deliberately does not know your numbers. For project-specific thresholds — your exact bonus %, margin rate, segment bands, program conditions — it will not assert a verdict; it flags "this looks off, confirm against your rules."

Those rules belong in a separate domain skill you author with your own thresholds, sitting on top of this one:

LayerSkillCatchesWho can define it
Genericexcel-hygiene (this)mechanical checks + generic logic/omission (totals that don't add up, % > 100%, missing rows, units mismatch, …)universal — no project rules needed
Domainyour skillyour exact thresholds and business rulesonly you / your expert

The simplest way to create that domain skill is to ask the agent in plain language: "create a skill that holds my offer rules: bonus = X%, margin ≥ Y, … and save it to .claude/skills/."

Requirements

  • Python 3
  • openpyxl ≥ 3.1 (pip install -r requirements.txt)

The script reads both formulas and values; it assumes a simple table with headers in row 1 of each sheet. It is conservative / high-precision by design — it would rather miss a borderline case than cry wolf.

Credits

Error framework: Panko, "Revisiting the Panko–Halverson Taxonomy of Spreadsheet Errors" (EuSpRIG 2008); Reason, "Human Error" (1990); Rajalingham (2005); Powell, Lawson & Baker (2007).

Built by Empatika Labs.

License

Apache-2.0.

Ver o original no GitHub

Bom para

Relacionados