Nl Tax Evidence Indexer

NL Tax Evidence Indexer

Catalog whatever evidence the user has - files in uploads//evidence/, and values stated in chat - into a single structured index. This skill is conversational: it does not assume the user has dropped a complete folder of documents.

When to use

• The user mentions having (or being about to share) tax documents.
• A workflow skill (annual / provisional) needs evidence for a section.
• New files appear in uploads/ or evidence/.
• The user wants to record a value in chat ("my 2025 employer paid me EUR 52,400") that should be tracked alongside files.

Read first (every turn)

Bundled paths below are relative to this skill's own directory: reference/ and templates/ are subfolders, and _shared/ is the plugin-shared folder at ../_shared/. Resolve bundled files with host file tools (Read first, Glob or Grep if a path is not obvious). Do not use Bash to discover or read plugin files: in Cowork, shell commands run in an isolated VM that may not see the plugin cache even when Read and Glob can. If the host has already expanded ${CLAUDE_PLUGIN_ROOT} or ${CLAUDE_SKILL_DIR}, those absolute paths are fine for file tools; otherwise search within the loaded plugin/skill tree and resolve relative to this skill directory. Resolve every workspace/... path against workspace_root recorded in session-progress.yaml (or profile.yaml); never create a second workspace/ tree.

1. _shared/knowledge/methods/interactive-elicitation.md - the conversational contract.
2. reference/evidence-types.md, reference/extraction-boundaries.md
3. workspace/shared/session-progress.yaml - to see which evidence questions are open.
4. workspace/taxpayer/evidence-index.yaml if it exists. Otherwise prepare to create it from templates/evidence-index.yaml.

Items 2-3 are internal rules. Do not quote or summarize them to the user unless the user offers credentials, asks for login/submission help, or a specific uploaded item needs review.

How files arrive (folder drop AND host attachments)

uploads/ and evidence/ are the canonical evidence locations, but the user does not have to put files there by hand. Accept all of these:

• Folder drop - files the user placed in uploads/ or evidence/ directly.
• Host attachment - files attached in the chat UI (Cowork, Claude Code,

Codex). Hosts place these somewhere in the session working directory - often the workspace root or a host-specific attachments path, not uploads/.

• Stated in chat - no file at all; record as a user_chat item.

When the user mentions attaching or sharing a file and it is not in uploads/ or evidence/, look for it in the working directory (and any host attachment path visible to you). When found, prefer copying it into uploads/ with its original filename before indexing — but only via a byte-faithful mechanism: a shell copy (python3 -c "import shutil; shutil.copy2(src, dst)" under the allowed Bash(python3:*) tool) when the shell can see both paths, or a host file-copy facility if one exists. Never round-trip a binary file (PDF, image, xlsx) through Read + Write — that corrupts it. If no faithful copy is possible (no shell access to the attachment path, binary content), index the file in place: record its real path in file_path, note location: host_attachment in the item's notes, and continue — cataloging does not require the file to live in uploads/. Never ask the user to re-upload a file that is already in the session; never treat "it's not in uploads/" as "the user has no evidence".

What this skill does

• Scan uploads/ and evidence/ for new files; classify each one.
• Hash each file (sha256) for integrity tracking.
• Record user-stated values as evidence items with extraction_status: "user_chat" (no file).
• Drive the conversation when a workflow needs evidence that is not yet present.
• Generate review questions for items the user must verify.

Conversational behavior

The indexer never tries to do everything in one shot. Its turn-by-turn loop is:

1. Inventory pass. List what is currently in uploads/ and evidence/, plus any host-attached files elsewhere in the session (copy those into uploads/ first - see How files arrive). Diff against existing entries in evidence-index.yaml. Add or update items as needed.
2. Tell the user what was found. One short sentence per file: "Found jaaropgaaf-2025.pdf - looks like a 2025 jaaropgaaf from {employer}, confidence 0.85." Do not paste long extracts.
3. Ask only about gaps that are blocking the active workflow. If the active workflow is annual_2025 and there is no jaaropgaaf and no employment income recorded, ask: "Do you have a 2025 jaaropgaaf? You can attach it here in the chat, drop it into uploads/, or just tell me the amount."
4. Accept whichever the user offers - file or chat - and record it accordingly.
5. Defer politely. If the user can't provide it now, mark extraction_status: "deferred", add to missing-info.md, and move on.

Batch at most three evidence questions per turn.

Two paths for every fact

Each item in evidence-index.yaml carries a source field:

• file - a real file in uploads/ or evidence/.
• user_chat - a value the user stated. Includes quote (verbatim user text) and stated_at.
• unknown - promised but not yet provided (deferred). Set extraction_status: "deferred"; this matches the source: unknown + deferred-status provenance used in profile.yaml and the workflow skills.

For user_chat items, set file_path: null, file_sha256: null, extraction_status: "user_chat", and put the stated amounts under extracted_fields with a clear key (e.g., gross_employment_income_eur).

Evidence classification

For each file or user-stated item, determine:

• evidence_type (jaaropgaaf, bankafschrift, woz_beschikking, hypotheek_jaaroverzicht, voorlopige_aanslag_beschikking, definitieve_aanslag, etc.)
• tax_year
• owner (taxpayer or partner)
• confidence (0.0-1.0)
• review_required (true if confidence . If no shell can reach the file at all, set file_sha256: null (the schema permits a null hash) and continue — cataloging and classification do not depend on the hash. Never copy bundled scripts into workspace/, and never execute a .py file located under workspace/, uploads/, or evidence/ (the inline -c` hash/copy commands above run no file-based script and are fine).
• Do not add generic safety-warning paragraphs to normal user-facing replies.

Output files

Write or update:

• workspace/taxpayer/evidence-index.yaml (seed from templates/evidence-index.yaml on first write)
• workspace/shared/evidence-review-questions.md (seed from templates/evidence-review-questions.md on first write)
• workspace/shared/session-progress.yaml (record answered/open evidence question_ids)
• workspace/shared/missing-info.md (when items are deferred)

Do NOT write to:

• workspace/annual/**
• workspace/provisional/**

End-of-turn report

After each turn, report to the user in 2-4 sentences:

• How many files indexed (added / updated).
• How many user-stated values recorded.
• The one or two next pieces of evidence that would unblock the active workflow.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cyanxxy
• Source: cyanxxy/nl-tax-agent-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.