Tax Organizer

Tax Organizer for Personal & Consultant

Organizes and processes personal tax documents to generate accurate, tax reports and drafts. Use when user uploads or describes tax forms (W-2, 1099s, K-1s, 1098), mentions rental properties, royalties, partnerships/S-corps, business expenses, donations, or needs Schedule E drafts. Handles complex income sources, expense matching, per diem optimization, and charitable receipt identification.

When to Use

• Organizing personal and consultant tax documents
• Processing rental property expenses, income, and depreciation
• Matching business trip expenses with per diem optimization
• Generating tax-ready XLS reports for accountant review
• Classifying W-2s, 1099s, and donation receipts
• Tracking incremental document additions across multiple sessions

Usage

Navigate to your tax year folder and run this skill.
Drop documents anytime — the skill detects new files and only processes what's changed.

Folder Structure

The skill expects and creates this layout in the working directory:

Tax-2025/
├── README.md                     # Global config + instructions
├── Rental-123-Main-St/
│   ├── README.md                 # Business config (see template below)
│   └── (drop receipts/invoices here)
├── Freelance-Consulting/
│   ├── README.md
│   └── ...
├── W2s/                          # W-2 forms
├── 1099s/                        # All 1099 variants
├── Donations/                    # Charitable contribution receipts
├── Unclassified/                 # Files the skill couldn't classify
├── Reports/                      # Generated XLS outputs
└── .processed-files.log          # Internal: tracks processed files

Special folders

• W2s/ — W-2 forms. Organized for reference (Form 1040, not Schedule E).
• 1099s/ — All 1099 variants (NEC, MISC, INT, DIV, K-1, etc.).
• Donations/ — Charitable contribution receipts (Form 8283 / Schedule A).
• Unclassified/ — Documents that couldn't be auto-classified. Flagged for manual review.
• Reports/ — Generated XLS report files. Regenerated on every run.

Root README.md Template

When no root README.md exists, generate one from this template (fill in from user responses):

# Tax Documents — {{TAX_YEAR}}

## Instructions

This folder organizes your tax documents for the {{TAX_YEAR}} tax year.

### How to use

1. **Drop receipts and documents** into the tax year folder
   — or into any existing business subfolder
2. **Run the skill** — it scans your documents, identifies business
   lines, and guides you through setup
3. **Add more documents anytime** — the skill detects new files and
   only processes what's changed

### Special folders

- `W2s/` — Drop W-2 forms here (organized for reference)
- `1099s/` — Drop all 1099 forms here
- `Donations/` — Drop charitable contribution receipts here

## Filing Information

- **Tax Year**: {{TAX_YEAR}}
- **Filing Status**: {{FILING_STATUS}}
- **Preparer**: {{PREPARER_NAME}}

Business README.md Template

Each business folder gets a README.md that serves as both config and documentation. Generate from this template:

# {{BUSINESS_NAME}}

## Business Information

- **Type**: {{BUSINESS_TYPE}}
- **EIN**: {{EIN}}
- **Address**: {{ADDRESS}}
- **Ownership**: {{OWNERSHIP_PERCENTAGE}}%

## Property Details

- **In-Service Date**: {{IN_SERVICE_DATE}}
- **Cost Basis**: ${{COST_BASIS}}
- **Land Value**: ${{LAND_VALUE}}
- **Depreciation Method**: {{DEPRECIATION_METHOD}}

## Business Trips

### {{TRIP_NAME}} — {{TRIP_DESTINATION}}

- **Dates**: {{TRIP_START}} – {{TRIP_END}}
- **Purpose**: {{TRIP_PURPOSE}}

## Important Events

- **{{EVENT_DATE}}**: {{EVENT_DESCRIPTION}}

## Notes

Business types: Residential Rental, Commercial Rental, Royalties, Partnership (K-1), S-Corp (K-1), Freelance/Self-Employment, Farm Rental

Depreciation methods:

• Residential rental: Straight-line over 27.5 years
• Commercial rental: Straight-line over 39 years
• Include mid-month convention for the placed-in-service year

Incremental Processing

The skill maintains a .processed-files.log in the root folder to track what has been processed:

# Tax Organizer — Processed Files Log
# Format: SHA256_HASH | ORIGINAL_PATH | ORGANIZED_PATH | TIMESTAMP
a1b2c3d4... | ./invoice_march.pdf | ./Rental-123-Main-St/2024-03-15 Plumber Co - Repairs - Pipe fix.pdf | 2024-12-01T10:30:00
e5f6g7h8... | ./receipt.jpg | ./Rental-123-Main-St/2024-04-20 Home Depot - Supplies - Door hardware.jpg | 2024-12-01T10:30:00

Processing rules

On each run, hash all files in the directory tree (excluding Reports/ and the log itself), then compare against .processed-files.log:

| Condition | Action | |------------------------------------------------|--------------------------------------| | New file (hash not in log) | Process normally | | Duplicate file (same hash, different path) | Flag as duplicate, skip, notify user | | Already processed (hash + path match) | Skip silently | | Moved/renamed (hash matches, path changed) | Update log entry, skip reprocessing |

Report to user: "Found X new files, Y duplicates, Z already processed"

Workflow

Execute these 9 steps in order:

---

Step 1: Scan & Discover

1. Scan the working directory recursively for all documents: PDF, JPG, PNG, JPEG, TIFF, XLS, XLSX, CSV, EML, MSG. For

XLS/XLSX files, use the /xlsx skill to read their contents.

1. Exclude Reports/ folder and .processed-files.log
2. Compute SHA-256 hash for each file found
3. Load .processed-files.log if it exists
4. Categorize every file as: new, already-processed, duplicate, or moved/renamed (see Processing Rules above, use mv instead of cp)
5. Detect existing README.md configs in business folders
6. Report to user:

• Total files found
• New files to process
• Duplicates found
• Already processed (skipped)
• File types breakdown

If there are zero new files to process, skip to Step 8 (regenerate reports) or inform the user and stop.

---

Step 2: Interactive Business Setup

First run (no root README.md found):

1. Ask user for:

• Tax year
• Filing status (Single, Married Filing Jointly, Married Filing Separately, Head of Household, Qualifying Surviving

Spouse)

• Preparer name (their name or accountant's name)

1. Generate the root README.md using the template above
2. Create empty special folders: W2s/, 1099s/, Donations/, Unclassified/, Reports/
3. Analyze the new documents found in Step 1 and identify likely business lines:

• Property addresses on invoices/receipts → suggest a rental or commercial property folder
• Payer names on 1099-NEC/MISC → suggest a freelance or royalty folder
• K-1 forms → suggest a Partnership or S-Corp folder
• Group documents that share an address or entity name into a single proposed business

1. Present the suggested business lines to the user, for example:

``` I found documents referencing these potential business lines:

1. "456 Oak Ave" — appears on 3 receipts and a 1098. Looks like a rental property.
2. "Acme Consulting LLC" — appears on a 1099-NEC. Looks like freelance income.

For each one I'll ask a few questions to set it up. ```

1. For each confirmed business line, ask:

• Business name (suggest one based on address or entity name)
• Business type (Residential Rental, Commercial Rental, Royalties, Partnership, S-Corp, Freelance/Self-Employment,

Farm Rental)

• EIN (if applicable)
• Address (pre-fill from document if found)
• Ownership percentage
• For rentals: in-service date, cost basis, land value, depreciation method

1. For each business, ask if there were any related business trips:

• Trip name, destination, date range, purpose

1. Generate a README.md in each business folder using the template above
2. If any documents don't suggest a clear business line, ask the user whether to create a new business folder or

place them in Unclassified/

Subsequent runs (root README.md exists):

1. Parse existing README.md configs from root and all business folders
2. If new documents suggest a business line not covered by any existing folder, prompt the user to set it up

(same flow as steps 4–9 above, for the new business only)

1. Do NOT re-prompt for existing businesses unless user explicitly requests changes
2. Proceed to Step 3

---

Step 3: Document Classification

For each new/unprocessed document, read and classify it:

| Document Type | Destination | Identification Clues | |----------------------|--------------------------|-----------------------------------------------------------------------------------------| | W-2 | W2s/ | "Wage and Tax Statement", Form W-2, boxes for wages/withholding | | 1099-NEC | 1099s/ | "Nonemployee Compensation", Box 1 | | 1099-MISC | 1099s/ | "Miscellaneous Income", rents/royalties boxes | | 1099-INT | 1099s/ | "Interest Income" | | 1099-DIV | 1099s/ | "Dividends and Distributions" | | 1099-K | 1099s/ | "Payment Card and Third Party Network" | | 1099-B | 1099s/ | "Proceeds From Broker", stock/investment sales | | 1099-R | 1099s/ | "Distributions From Pensions" | | 1099-S | 1099s/ | "Proceeds From Real Estate Transactions" | | 1099-G | 1099s/ | "Government Payments" | | Schedule K-1 | 1099s/ | Partner's/Shareholder's share of income | | Donation receipt | Donations/ | 501(c)(3) reference, "tax-deductible", "charitable contribution", church/nonprofit name | | Business expense | Matching business folder | Vendor name, property address, expense context matches a business | | Unclassifiable | Unclassified/ | Cannot determine type or business; flag for manual review |

Classification logic for business expenses:

1. Check if the document mentions a property address matching a business folder
2. Check if the vendor name appears in previous documents for a business
3. Check if the expense date falls within a business trip date range
4. If multiple businesses could match, ask the user
5. If no match found, place in Unclassified/

---

Step 4: Extract Information

For each document, extract all relevant data fields:

All documents:

• Date (transaction date, statement date, or tax year)
• Vendor / payer name
• Amount(s)
• Description / memo

W-2 fields:

• Employer name and EIN
• Employee name and SSN (last 4 only — do not store full SSN)
• Box 1: Wages, tips, other compensation
• Box 2: Federal income tax withheld
• Box 3: Social security wages
• Box 4: Social security tax withheld
• Box 5: Medicare wages
• Box 6: Medicare tax withheld
• Box 12 codes (DD, W, etc.)
• Box 13: Statutory employee, retirement plan, third-party sick pay
• State wages and withholding

1099 fields (varies by type):

• Payer name, TIN
• Recipient name
• All box amounts relevant to the 1099 type
• State tax withheld if applicable

Expense fields:

• Vendor name
• Transaction date
• Amount (pre-tax, tax, total)
• Expense category (map to Schedule E line — see line reference table)
• Payment method if visible
• Property/business reference if visible

Donation fields:

• Organization name
• Date of contribution
• Amount (or fair market value for non-cash)
• Cash vs. non-cash
• 501(c)(3) status / tax-exempt confirmation
• Description of donated items (non-cash)
• Whether goods/services were received in return

Spreadsheet files (XLS/XLSX):

• Invoke the /xlsx skill to read and extract data from Excel files
• These may contain multiple transactions (bank statements, property management reports, accounting exports)
• Extract each row as a separate transaction with the fields above
• CSV files can be read directly without the /xlsx skill

When extraction is incomplete:

• Use filename clues (dates in filename, vendor name patterns)
• Use file metadata (creation date, modification date)
• Flag incomplete extractions — never silently guess missing values
• Mark confidence level: HIGH (clear document), MEDIUM (partial info), LOW (mostly inferred)

---

Step 5: Business Trip Expense Matching

1. Parse trip date ranges from each business folder's README.md:

• Extract trip name, destination city + state, start date, end date, purpose

1. For each expense document dated within a trip's date range, check if it matches trip-related categories:

• Airfare / flights
• Hotels / lodging
• Meals (50% deductible per IRS rules)
• Taxi / rideshare / car rental
• Conference / registration fees
• Parking and tolls
• Baggage fees

1. Also check expenses ±1 day outside trip dates — flag as "potentially trip-related" for user review
2. Look up GSA per diem rates for the trip destination:

• Use the GSA per diem API or published rates for the tax year
• Lodging rate (per night)
• M&IE rate (meals and incidental expenses per day)
• First and last day of travel: 75% of M&IE rate

1. Calculate per diem totals:

• Lodging: nightly rate × number of nights
• M&IE: full-day rate × (trip days − 2) + 75% rate × 2 (first/last day)
• If trip is 1 day: 75% of M&IE, no lodging

1. Compare actual tracked expenses vs. per diem allowance
2. Recommend whichever method produces the larger deduction, noting:

• Per diem: simpler, no receipt tracking needed for meals
• Actual: may be higher for expensive destinations
• IRS requires consistency within a trip (can't mix methods)

1. Tag matched expenses with trip name for reporting

---

Step 6: Rename & Organize Files

1. Generate a rename/organize plan for all new files. Naming convention:

`` YYYY-MM-DD Vendor - Category - Description.ext `` Examples:

• 2024-03-15 Plumber Co - Repairs - Kitchen pipe fix.pdf
• 2024-04-20 Home Depot - Supplies - Door hardware.jpg
• 2024-01-31 Acme Corp - W2 - Wages.pdf
• 2024-12-15 Red Cross - Donation - Annual gift.pdf
• 2024-09-06 Marriott - Travel - BiggerPockets Conference hotel.pdf

1. Show the complete before/after plan to the user:

``` File Organization Plan:

NEW FILES (5): ├── invoicemarch.pdf │ → Rental-123-Main-St/2024-03-15 Plumber Co - Repairs - Pipe fix.pdf ├── receipt.jpg │ → Rental-123-Main-St/2024-04-20 Home Depot - Supplies - Door hardware.jpg ├── W2acme.pdf │ → W2s/2024-01-31 Acme Corp - W2 - Wages.pdf ...

DUPLICATES (1): ├── invoicemarchcopy.pdf (same as invoice_march.pdf) — SKIPPED

UNCLASSIFIED (1): ├── mysterydoc.pdf → Unclassified/mysterydoc.pdf — NEEDS REVIEW ```

1. Wait for user approval before executing any file operations
2. Copy files to their organized locations (preserve originals)
3. Update .processed-files.log with entries for each p

…

Source & license

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

• Author: elderengineer
• Source: elderengineer/tax-organizer
• License: MIT

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