policyengine-us
US tax-benefit domain knowledge for analysts computing household or population impacts with the policyengine package (pe.us). Load for: which entity a US program attaches to (tax_unit vs spm_unit vs person), tax-unit role flags and filing status, post-OBBBA current-law values (2026 CTC, standard deduction, SALT cap), the parameter tree (gov.irs / gov.states.{xx} / gov.usda.snap / gov.ssa), state income-tax and credit coverage, and SNAP monthly/FPL semantics. Triggers: EITC, CTC, SNAP, TANF, SSI, income tax, state income tax, standard deduction, SALT cap, federal poverty level, spm_unit, tax_unit, filing status, is_tax_unit_dependent, household_net_income, in_poverty, state credit, CalEITC, ca_eitc, ny_eitc, OBBBA. NOT for: implementing new US variables/parameters (use policyengine-model-development); Medicaid/ACA/CHIP/Medicare (use policyengine-healthcare); the core calculate_household / Simulation / reform mechanics shared across countries (use the policyengine skill).
PolicyEngine · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add PolicyEngine/policyengine-claude --skill policyengine-us技能说明
name: policyengine-us description: | US tax-benefit domain knowledge for analysts computing household or population impacts with the policyengine package (pe.us). Load for: which entity a US program attaches to (tax_unit vs spm_unit vs person), tax-unit role flags and filing status, post-OBBBA current-law values (2026 CTC, standard deduction, SALT cap), the parameter tree (gov.irs / gov.states.{xx} / gov.usda.snap / gov.ssa), state income-tax and credit coverage, and SNAP monthly/FPL semantics. Triggers: EITC, CTC, SNAP, TANF, SSI, income tax, state income tax, standard deduction, SALT cap, federal poverty level, spm_unit, tax_unit, filing status, is_tax_unit_dependent, household_net_income, in_poverty, state credit, CalEITC, ca_eitc, ny_eitc, OBBBA. NOT for: implementing new US variables/parameters (use policyengine-model-development); Medicaid/ACA/CHIP/Medicare (use policyengine-healthcare); the core calculate_household / Simulation / reform mechanics shared across countries (use the policyengine skill). metadata: category: domain
PolicyEngine US domain knowledge
This skill is the US-specific layer for analysts using the policyengine package. It assumes
you already know the shared mechanics — pe.us.calculate_household, population Simulation,
reform dicts, datasets — from the policyengine skill; read that first for anything not
US-specific. For building new US variables or parameters, use policyengine-model-development.
For Medicaid / ACA / CHIP / Medicare, use policyengine-healthcare.
Verified against policyengine 4.21.0 / policyengine-us 1.764.6 (2026-07). Re-verify law-year values before reporting — the model updates continuously.
The six entities, and which program lives on which
US taxes and benefits are administered by different units, so the model has six entities. A program's variable is defined on exactly one of them, and reading it from the wrong entity is the most common US mistake.
| Entity | Plural key | What it groups |
|---|---|---|
person | people | individuals |
marital_unit | marital_units | a married couple (or a single person) |
family | families | a nuclear family (Census-style) |
tax_unit | tax_units | a tax-filing unit (a 1040) |
spm_unit | spm_units | a Supplemental Poverty Measure resource-sharing unit |
household | households | everyone at a physical address |
Which entity a program attaches to (verified — entity and definition period both matter):
| Program / measure | Variable | Entity | Period |
|---|---|---|---|
| Federal income tax | income_tax | tax_unit | year |
| EITC | eitc | tax_unit | year |
| Child Tax Credit | ctc | tax_unit | year |
| State income tax (aggregate) | state_income_tax | tax_unit | year |
| SNAP | snap | spm_unit | month |
| TANF | tanf | spm_unit | year |
| SSI | ssi | person | month |
| Net income | household_net_income | household | year |
| Total benefits | household_benefits | household | year |
| Total taxes | household_tax | household | year |
| In poverty (SPM) | in_poverty | spm_unit | year |
| Person in poverty | person_in_poverty | person | year |
| Is a child | is_child | person | year |
Rules of thumb: income tax and its credits (EITC, CTC, CDCC, education, and the aggregate
state_income_tax) are tax-unit variables; means-tested transfers keyed to a resource-sharing
unit (SNAP, TANF, school meals, housing) are spm_unit variables; SSI is a person-level
benefit (each individual's own SSI), rolled up into household_benefits. Poverty is measured on
the spm_unit. On a calculate_household result you read these as dot-attributes on the singular
entity — result.tax_unit.eitc, result.spm_unit.snap, result.person[0].ssi,
result.household.household_net_income.
Tax-unit roles and filing status
tax_unit={"filing_status": ...} accepts SINGLE, JOINT, SEPARATE, HEAD_OF_HOUSEHOLD,
SURVIVING_SPOUSE.
Three person-level role flags exist: is_tax_unit_head, is_tax_unit_spouse,
is_tax_unit_dependent. You usually do not set them for a simple family — minor children in
the people list are inferred as dependents automatically, the first adult is the head, and
JOINT designates the second adult as the spouse. Setting them wrong is worse than omitting them.
When you do need them: adult dependents. An adult in the people list is not auto-inferred
as a dependent. A 20-year-old student, a supported parent, or any qualifying relative must be
flagged is_tax_unit_dependent: True, or the model treats them as an independent unit member and
their credit vanishes. Verified — a HOH filer with a 20-year-old earning $4,000:
import policyengine as pe
def odc(dependent):
kid = {"age": 20, "employment_income": 4_000}
if dependent:
kid["is_tax_unit_dependent"] = True
return pe.us.calculate_household(
people=[{"age": 45, "employment_income": 40_000}, kid],
tax_unit={"filing_status": "HEAD_OF_HOUSEHOLD"},
household={"state_code": "CA"},
year=2026,
).tax_unit.ctc
assert odc(False) == 0 # adult not treated as a dependent -> no credit
assert odc(True) == 500 # $500 credit for other dependents (ODC)
Household calculation
state_code (not state_code_str) goes in the household dict. A low-income married couple with
two children, showing where each program lands:
import policyengine as pe
r = pe.us.calculate_household(
people=[
{"age": 35, "employment_income": 25_000},
{"age": 33, "employment_income": 0},
{"age": 8},
{"age": 5},
],
tax_unit={"filing_status": "JOINT"},
household={"state_code": "NY"},
year=2026,
)
assert round(r.tax_unit.ctc) == 4_400 # 2 children x $2,200 (OBBBA, 2026)
assert round(r.tax_unit.eitc) == 7_316 # federal EITC (tax_unit)
assert round(r.sp
阅读完整来源 ↗