irs-pt — Case Study
back- Agent Skill
- Python (stdlib only)
- Markdown
- MIT
The question
Every freelancer in Portugal asks the same thing in March: is it worth assigning this invoice to my activity? I could not find an answer that started with the arithmetic instead of the portal. Under the regime simplificado the answer is close to binary — expenses only matter once 15% of gross service income passes the automatic deduction — and almost nobody is told that before they start classifying receipts one by one.
What I built
An open-source assistant packaged as an agent skill: it runs inside Claude and any agent that reads the agentskills format, asks two or three questions, and does the threshold maths before it mentions invoices at all. It explains, calculates and recommends — it never submits anything to the Portal das Finanças.
- Works out the year's threshold first and says, in one sentence, whether invoices change anything
- Handles mixed activity (sales, services, other services) and income on top of a salaried job
- Reads the e-Fatura CSV export locally and proposes a classification invoice by invoice
- Shows a preview and asks for confirmation before listing what to click in the portal
- Ends with one next action and the year's deadlines
Technical decisions
The maths before the portal — the whole point is the question nobody answers first. Getting the order right is the product; the parser is the easy half.
Python with no dependencies — parse_efatura.py is stdlib only and reads the CSV on your own machine. Tax data does not leave the computer, and there is nothing to install or trust.
Volatile values in one file — IAS, thresholds and deadlines live in references/valores-anuais.md, apart from the structural rules that do not change every year. Updating for a new tax year is one file, not a hunt.
The human clicks — it is not tax advice, and it does not act. The line between "explains" and "submits" is the safety property; it is written into the skill's inviolable rules, not just the README.
What I learned
Writing software for a rule someone else wrote means reading the primary source: the CIRS articles, not the blog posts about them. And shipping something in public with "tested by one person — her own return" on the label is a different kind of honesty than a portfolio demo, because strangers rely on it.