Skip to content
Back to search

je-validator

SkillWorks with Claude CodeGitHub

Use this skill to validate a QuickBooks-style journal-entry Excel export before importing it into QuickBooks Online. It maps each transaction's account name against a chart of accounts (a bundled manufacturing-company COA by default, or your own COA file), checks double-entry debits/credits balance to the cent per entry, flags blank/zero/trailing junk rows, and writes an import-ready CSV for QBO's native JE importer. Trigger on requests like "validate this journal entry file," "check this JE export against our chart of accounts," "is this ready to import into QuickBooks," or when the user hands you a journal-entry .xlsx file.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ingenaitive--je-validator-skill/badge.svg)](/listings/ingenaitive--je-validator-skill)

HTML

<a href="/listings/ingenaitive--je-validator-skill"><img src="/api/listings/ingenaitive--je-validator-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 56 lines
  1. ---
  2. name: je-validator
  3. description: Use this skill to validate a QuickBooks-style journal-entry Excel export before importing it into QuickBooks Online. It maps each transaction's account name against a chart of accounts (a bundled manufacturing-company COA by default, or your own COA file), checks double-entry debits/credits balance to the cent per entry, flags blank/zero/trailing junk rows, and writes an import-ready CSV for QBO's native JE importer. Trigger on requests like "validate this journal entry file," "check this JE export against our chart of accounts," "is this ready to import into QuickBooks," or when the user hands you a journal-entry .xlsx file.
  4. ---
  5. # JE Validator
  6. Validates a double-entry journal-entry Excel export against a chart of accounts, before it goes anywhere near QuickBooks Online's native CSV/Excel importer (Settings → Import Data → Journal Entries).
  7. ## When to use this
  8. - The user hands you (or names) a journal-entry `.xlsx` file and asks you to check, validate, or confirm it's import-ready.
  9. - The user wants to try the tool out with no files of their own yet — run it with no arguments to validate the bundled demo.
  10. ## Quick start
  11. ```bash
  12. # Try it with the bundled sample (manufacturing COA + sample JE file, no setup needed)
  13. python scripts/validate_je.py
  14. # Validate a real file against the bundled manufacturing COA
  15. python scripts/validate_je.py path/to/journal_entries.xlsx
  16. # Validate against the user's own chart of accounts instead
  17. python scripts/validate_je.py path/to/journal_entries.xlsx --coa path/to/their_coa.xlsx
  18. # Choose output paths
  19. python scripts/validate_je.py path/to/journal_entries.xlsx --report report.csv --out import_ready.csv
  20. ```
  21. All script paths are relative to this skill's directory.
  22. ## What it checks
  23. 1. **Account mapping** — every account name is matched against the chart of accounts in tiers: exact `FullyQualifiedName` match → ambiguous leaf-name match (flagged, lists every full-path candidate) → fuzzy "possible match" suggestion (never auto-applied) → phantom account (no match at all, flagged).
  24. 2. **Double-entry balance** — total debits must equal total credits per journal entry, to the cent, after rounding.
  25. 3. **Per-line sanity** — exactly one of Debit/Credit per line and it's positive; blank rows and zero-amount rows are flagged as phantom rows, never silently dropped.
  26. 4. **Sheet-level noise** — a trailing "Total"/"Subtotal" row or trailing blank rows at the end of the sheet are detected and excluded from entries (reported as a `NOTE`, not a failure, since they're sheet formatting, not transaction data).
  27. 5. **Grouping-key continuity** — if a journal/entry-ID column exists, a blank ID on what looks like a continuation line is forward-filled to the previous entry and flagged via a `NOTE`, rather than silently becoming its own (wrong) one-line entry. If no ID column exists at all, rows are grouped into entries by blank-row-separated blocks instead.
  28. Columns are auto-detected from the file's own headers (Account/GL Account/Account Name, Debit/Credit or a single signed Amount column, Journal No./Entry ID/Transaction ID, Date, Description/Memo) — there's no fixed template to match. If required columns can't be confidently identified, the script stops and reports exactly what it found and what's missing/ambiguous, rather than guessing.
  29. ## Output
  30. - **Validation report** (`validation_report.csv` by default): one row per journal entry — `SourceFile, EntryId, Status, ErrorCount, Errors`.
  31. - **Import-ready CSV** (`je_import_ready.csv` by default): only entries that passed validation, rewritten in QBO's exact native-importer header format (`Journal No., Journal Date, Account Name, Description, Debits, Credits`), with account names normalized to their full `FullyQualifiedName`.
  32. ## Files
  33. - `scripts/validate_je.py` — main entry point (run this).
  34. - `scripts/column_detect.py` — header-mapping heuristics.
  35. - `scripts/coa_match.py` — chart-of-accounts loading and account-name matching tiers.
  36. - `scripts/build_fixtures.py` — regenerates the bundled COA/demo/test fixtures; not needed at run time.
  37. - `references/manufacturing_coa.xlsx` — bundled default chart of accounts (manufacturing company).
  38. - `references/sample_journal_entries.xlsx` — demo JE file (2 clean entries, 2 with intentional defects) used when no file is given.
  39. - `test_files/` — regression fixtures, each isolating exactly one defect: `je_good.xlsx`, `je_bad_unbalanced.xlsx`, `je_bad_rounding.xlsx`, `je_bad_phantom_blank_row.xlsx`, `je_bad_phantom_zero_row.xlsx`, `je_bad_ambiguous_leaf.xlsx`, `je_bad_trailing_total_row.xlsx`, `je_bad_broken_grouping.xlsx`. Re-run all of these after any change to validation logic.
README.md · README · 67 lines
  1. # JE Validator
  2. A Claude skill (and standalone script) that validates a double-entry journal-entry Excel export before you import it into accounting software — mapping each transaction's account name against a chart of accounts, confirming debits/credits balance to the cent per entry, and flagging anything that would trip up a native importer.
  3. Ships with a bundled manufacturing-company chart of accounts as a default, a demo file so you can try it with zero setup, and an 8-case regression suite. See `SKILL.md` for the full feature list and validation rules.
  4. ## Usage
  5. You can use this three ways — none of them require Claude at all unless you want one of the AI-assisted options.
  6. ### Option 0: Plain Python (no AI product needed)
  7. ```bash
  8. git clone https://github.com/ingenaitive/je-validator-skill.git
  9. cd je-validator-skill
  10. python3 -m venv venv
  11. ./venv/bin/pip install -r requirements.txt
  12. # Try the bundled demo (zero setup)
  13. ./venv/bin/python scripts/validate_je.py
  14. # Validate your own file
  15. ./venv/bin/python scripts/validate_je.py path/to/your_journal_entries.xlsx
  16. # Validate against your own chart of accounts instead of the bundled manufacturing one
  17. ./venv/bin/python scripts/validate_je.py path/to/your_journal_entries.xlsx --coa path/to/your_coa.xlsx
  18. ```
  19. ### Option 1: Claude Code
  20. Clone this repo, then copy the skill folder (this one — the folder containing `SKILL.md`) into either:
  21. - **Project-scoped** (shareable via your own repo): `<your-project>/.claude/skills/je-validator/`
  22. - **Personal** (available across all your projects): `~/.claude/skills/je-validator/`
  23. No registration step — Claude Code auto-discovers skills in those locations. If it doesn't pick it up right away in an existing session, run `/reload-skills`. Then just ask Claude Code to validate a journal-entry file and it'll invoke this skill.
  24. ### Option 2: Claude Desktop app / claude.ai (web)
  25. claude.ai and the Claude Desktop app support uploading custom Skills in this same format.
  26. **1. Build the zip correctly.** The skill folder itself (named `je-validator`, containing `SKILL.md`) needs to be at the top level inside the zip — e.g. `je-validator-skill.zip` → `je-validator/SKILL.md` — not `SKILL.md` sitting bare at the zip root, and not wrapped in an extra outer folder. If you downloaded this repo via GitHub's "Download ZIP" button, it wraps everything in a `je-validator-skill-main` folder first, so you'll need to re-zip:
  27. - Unzip the GitHub download.
  28. - Open the extracted folder, select everything inside it (Cmd+A), right-click → **"Compress [n] Items"**.
  29. - Rename the resulting `Archive.zip` to something clear, e.g. `je-validator-skill.zip`.
  30. **2. Upload it.** The exact menu location has varied between app versions — check both of these in the app, since one of them will have a Skills section with an upload/+ button:
  31. - **Customize → Skills**
  32. - **Settings → Capabilities → Skills**
  33. **3. Enable code execution.** Turn on **Settings → Capabilities → "Create and edit files"** — the skill needs this to actually run the Python script. If the exact label has changed, look for whatever capability governs running code / creating files.
  34. **4. Try it.** Start a new chat, attach one of the files from `test_files/` (e.g. `je_bad_unbalanced.xlsx` or `je_good.xlsx`) or your own journal-entry Excel file, and ask something like *"Validate this journal entry file using the je-validator skill."*
  35. Available on Free/Pro/Max/Ultra/Team/Enterprise plans (Team/Enterprise admins can disable user-uploaded skills org-wide).
  36. Note: in claude.ai / Claude Desktop, the skill runs in a sandboxed environment, so attach your Excel file to the chat rather than pointing the script at a local file path.
  37. ## Output
  38. Each run writes:
  39. - `validation_report.csv` — one row per journal entry (`SourceFile, EntryId, Status, ErrorCount, Errors`)
  40. - `je_import_ready.csv` — only entries that passed, reformatted in QBO's exact native-importer header format (`Journal No., Journal Date, Account Name, Description, Debits, Credits`)
  41. ## Roadmap
  42. Built for QuickBooks Online first; designed to add other double-entry platforms (e.g. Bigcapital) as additional output-format targets within this same skill, rather than as separate repos/skills.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.