huashu-excel: an agent skill that makes spreadsheet numbers survive questioning

The audit trail problem in spreadsheet analysis

The README opens with the question every analyst has been asked: how exactly did you get this number? The failure it targets is structural. Code that is wrong throws exceptions; spreadsheet analysis that is wrong delivers confidently. An inflated total and the correct total look identical in a report, and by the time someone challenges the figure, the trail back to the raw cells is cold.

huashu-excel, by alchaincyf, is a data-analysis skill for coding agents that exists to make that question answerable. Its pipeline reads raw cells before any dataframe library touches the file, treats the sheet's own subtotal and total rows as free checksums to reconcile against, and runs a final master check before delivery: if the numbers do not reconcile, the skill declines to hand them over. The pitch, in the author's framing, is a professional report from a messy Excel file, with every figure defensible.

The worked example: a 161 percent error with zero warnings

The README demonstrates on a deliberately dirty sales table: a title row above the real two-level header, merged cells, thousands separators, subtotal rows inside the data region, and a fully duplicated row. The straightforward approach, a common read-excel call with header tweaks and thousand-separator cleanup, reports a January total of 34,893,234 against a true value of 13,367,767, an error of plus 161 percent, with zero errors, zero NaNs and zero warnings.

The failure decomposes into three silent mistakes: a totals row counted as a store, a regional subtotal counted as another store, and the duplicate row counted twice. The skill's profiling stage instead lists every problem before computing anything, two-level headers with the exact row indexes, four subtotal rows identified by position, text-stored numbers flagged column by column, and inconsistent date formats enumerated per pattern. The README attributes the stakes with references: research from 1998 finding 86 percent of spreadsheets contain errors, and the EuSpRIG collection of public incidents including the well-known Reinhart-Rogoff selection mistake.

Installing and using it

One command installs the skill through the skills CLI, which detects your agent:

npx skills add alchaincyf/huashu-excel

Manual installation clones the repository into your agent's skills directory, with the README's table mapping Claude Code to ~/.claude/skills/, multi-agent runtimes to ~/.agents/skills/, and project-level installs to the .claude or .agents folders inside a repository. The skill claims cross-agent compatibility: Claude Code, Cursor, Codex and others that read SKILL.md.

The scripts also run standalone, without any agent, and the README shows them directly:

python3 scripts/profile_table.py 你的表.xlsx      # 算数字之前先看清楚
python3 scripts/verify_numbers.py 你的表.xlsx     # 退出码 1 = 有对不上的
python3 scripts/verify_visual.py 报告.html        # 退出码 1 = 图画错了
python3 scripts/verify_docx.py   报告.docx        # 退出码 1 = Word 换台机器就走样

Usage is conversational otherwise: ask for a full analysis, a reconciliation of two numbers that disagree, or just a health check of the table, and the skill picks the matching pipeline.

Eight steps, and why alignment is one of them

The standard workflow runs eight stages: profile the table's structure and dirt, clean into a canonical analysis table with every step replayable, align with the user, analyze, reconcile, deliver, verify visuals, and run quality control from an agent that did not participate in the work. The README's argument for stage three is the most interesting part. Users ask for analysis before they have seen the data, so interrogating them upfront produces guesses; instead the skill cleans first, reports what the table actually contains in plain language with one or two visible phenomena, and only then asks what question the analysis should answer and what decision it serves.

The guardrail against autopilot is written into the skill: after each script, three questions must be answered, what did I see, what does it mean, what to check next. If the next action after running a script is identical to the plan before it, the skill's own rule says nobody actually looked at the output. That is methodology encoded as procedure, which is precisely what a skill file is for.

Reconciliation, exit codes, and the master check

The reconciliation stage is the signature move. The demo table carries its own subtotal rows, and the skill cross-checks computed column sums against them: one check passes to the cent, another fails by ten currency units against a subtotal that the test-data author had hand-typed wrong, a 0.00 percent relative error no eyeball would ever catch.

Failure is enforced, not suggested: verify_numbers.py exits with code 1 when anything fails to reconcile, and the master check's own output says the numbers must not enter any deliverable until resolved. The other gates cover what spreadsheets break silently in delivery: verify_visual.py renders the HTML report and flags out-of-bounds or overlapping charts and figures whose numbers disagree with the text, while verify_docx.py catches Word documents with platform-bound fonts, missing east-Asian font declarations, blank pages and broken table headers. Exit codes make the whole chain scriptable in CI or a pre-delivery hook.

Scope and limitations

The dependency story is a design statement: openpyxl is required only for reading and writing .xlsx, while CSV analysis and report generation run on the standard library alone. No pandas, no plotting libraries, no network, no subagents or sandbox features, and the README notes the full pipeline has been verified in interpreters where pandas and numpy are blocked. The deliberate cost is that profiling must work at the moment before tooling decisions are made, so it cannot lean on anything heavy.

For an English-speaking audience, the primary friction is language: the README, prompts and example phrasings are in Chinese, and the methodology prose assumes that context, though the scripts themselves take file paths and exit codes and work regardless. The project is MIT licensed, has no releases or tags, and its last push was on 2026-09-15, so it is fresh and moving. It is also honest about what it is not: the eight scripts are a discipline, not a BI platform, and the README concedes that a perfectly reconciled report can still be wrong about the fiscal year if a column name does not mean what it says.

Against raw pandas and data-prep suites

The default alternative is the one the README mocks: a quick read-excel call plus a sum, maybe a visual once-over in Excel itself. That workflow's failure mode, confident wrong numbers, is exactly what the profiling and reconciliation gates exist to block, and the demo's 161 percent error with zero warnings is the entire argument in one table. Data-prep and spreadsheet-audit tools occupy the professional middle; they catch structural problems interactively but sit outside the agent workflow and do not, as a rule, reconcile your computed numbers against the sheet's own totals.

huashu-excel's actual position is methodology as an installable artifact. The eight steps, the three questions after each script, the refusal to deliver on a failed master check, all of that could be a style guide, and for teams that live in agents, packaging it as a skill means the discipline runs the same way for every member on every file. The scripts standing alone keep the door open for the agent-averse, which is more than most skill repositories offer.

Editorial conclusion

huashu-excel fits anyone whose deliverables are numbers from messy Excel files, especially Chinese-language teams running Claude Code, Cursor or similar agents, and it stays useful as four standalone verification scripts even without an agent. Skip it if your tables are already clean and schema-managed, if you need a visual BI layer, or if your team cannot operate Chinese-language documentation comfortably. Test the core claim on your own worst file: run python3 scripts/profile_table.py on it, then verify_numbers.py, and see whether the reconciliation catches anything your current process would have shipped.

Frequently asked questions

Official sources

1. alchaincyf/huashu-excel on GitHub
2. Issues
3. License: MIT
4. README