# Policyengine Parameter Patterns

> PolicyEngine parameter patterns - YAML structure, naming conventions, metadata requirements, federal/state separation

- **Type:** Skill
- **Install:** `agentstack add skill-policyengine-policyengine-claude-policyengine-parameter-patterns-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [PolicyEngine](https://agentstack.voostack.com/s/policyengine)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [PolicyEngine](https://github.com/PolicyEngine)
- **Source:** https://github.com/PolicyEngine/policyengine-claude/tree/main/skills/technical-patterns/policyengine-parameter-patterns-skill

## Install

```sh
agentstack add skill-policyengine-policyengine-claude-policyengine-parameter-patterns-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# PolicyEngine Parameter Patterns

Comprehensive patterns for creating PolicyEngine parameter files.

## Critical: Required Structure

Every parameter MUST have this exact structure:
```yaml
description: [One sentence description].
values:
  YYYY-MM-DD: value

metadata:
  unit: [type]       # REQUIRED
  period: [period]   # REQUIRED
  label: [name]      # REQUIRED
  reference:         # REQUIRED
    - title: [source]
      href: [url]
```

**Missing ANY metadata field = validation error**

---

## 1. File Naming Conventions

### Study Reference Implementations First
**Before creating ANY parameter files, read 3-5 files from a similar program in another state.** Match their structure — don't invent your own. This is the single most effective way to produce correct parameter files.

Search broadly by program concept (not just program name):
```bash
# For a childcare program, search by concept keywords:
Glob 'policyengine_us/parameters/gov/states/*/*/*child*care*/'
Glob 'policyengine_us/parameters/gov/states/*/*/*ccap*/'
Glob 'policyengine_us/parameters/gov/states/*/*/*ccfa*/'
```

Good references by program type:
- **TANF**: DC, IL, TX — `/parameters/gov/states/{st}/{agency}/tanf/`
- **Childcare**: MA CCFA, CO CCAP — `/parameters/gov/states/{st}/{agency}/ccfa/` or `ccap/`
- **LIHEAP**: AZ — `/parameters/gov/states/az/{agency}/liheap/`

### Naming Patterns

**Dollar amounts → `/amount.yaml`**
```
income/deductions/work_expense/amount.yaml     # $120
resources/limit/amount.yaml                    # $6,000
payment_standard/amount.yaml                   # $320
```

**Percentages/rates → `/rate.yaml` or `/percentage.yaml`**
```
income_limit/rate.yaml                         # 1.85 (185% FPL)
benefit_reduction/rate.yaml                    # 0.2 (20%)
income/disregard/percentage.yaml               # 0.67 (67%)
```

**Thresholds → `/threshold.yaml`**
```
age_threshold/minor_child.yaml                 # 18
age_threshold/elderly.yaml                     # 60
income/threshold.yaml                          # 30_000
```

---

## 2. Description Field

### The ONLY Acceptable Formula

```yaml
description: [State] [verb] [category] to [this X] under the [Full Program Name] program.
```

**Components:**
1. **[State]**: Full state name (Indiana, Texas, California)
2. **[verb]**: ONLY use: limits, provides, sets, excludes, deducts, uses
3. **[category]**: What's being limited/provided (gross income, resources, payment standard)
4. **[this X]**: ALWAYS use generic placeholder
   - `this amount` (for currency-USD)
   - `this share` or `this percentage` (for rates/percentages)
   - `this threshold` (for age/counts)
5. **[Full Program Name]**: ALWAYS spell out (Temporary Assistance for Needy Families, NOT TANF)

### Copy These Exact Templates

**For income limits:**
```yaml
description: [State] limits gross income to this amount under the Temporary Assistance for Needy Families program.
```

**For resource limits:**
```yaml
description: [State] limits resources to this amount under the Temporary Assistance for Needy Families program.
```

**For payment standards:**
```yaml
description: [State] provides this amount as the payment standard under the Temporary Assistance for Needy Families program.
```

**For disregards:**
```yaml
description: [State] excludes this share of earnings from countable income under the Temporary Assistance for Needy Families program.
```

### Keep Descriptions Practical

Descriptions should focus on what matters for simulation, not copy regulatory language verbatim. Omit regulatory details that have no practical impact:

```yaml
# ❌ Too literal — no one simulates a 1-week-old:
description: Rhode Island defines the infant/toddler age range as 1 week up to 3 years under the Child Care Assistance Program.

# ✅ Practical:
description: Rhode Island defines the infant/toddler age range as up to 3 years under the Child Care Assistance Program.
```

### Description Validation Checklist

Run this check on EVERY description:
```python
# Pseudo-code validation
def validate_description(desc):
    checks = [
        desc.count('.') == 1,  # Exactly one sentence
        'TANF' not in desc,     # No acronyms
        'SNAP' not in desc,     # No acronyms
        'this amount' in desc or 'this share' in desc or 'this percentage' in desc,
        'under the' in desc and 'program' in desc,
        'by household size' not in desc,  # No explanatory text
        'based on' not in desc,           # No explanatory text
        'for eligibility' not in desc,    # Redundant
    ]
    return all(checks)
```

**CRITICAL: Always spell out full program names in descriptions!**

---

## 3. Values Section

### Format Rules
```yaml
values:
  2024-01-01: 3_000    # Use underscores
  # NOT: 3000

  2024-01-01: 0.2      # Remove trailing zeros
  # NOT: 0.20 or 0.200

  2024-01-01: 2        # No decimals for integers
  # NOT: 2.0 or 2.00
```

### Effective Dates

**Use exact dates from sources:**
```yaml
# If source says "effective July 1, 2023"
2023-07-01: value

# If source says "as of October 1"
2024-10-01: value

# NOT arbitrary dates:
2000-01-01: value  # Shows no research
```

**Date format:** `YYYY-MM-01` (always use 01 for day)

### Effective Date Accuracy

**Use the program's effective date, not filing or publication dates:**
```yaml
# Regulation filed June 5, 2003; effective January 1, 2004
❌ 2003-06-05: 500    # Filing date — WRONG
✅ 2004-01-01: 500    # Effective date — CORRECT
```

**Beware backward extrapolation:** A parameter's first entry (e.g., `2006-07-01: 20`) is returned for ALL prior periods. If the program didn't exist before that date, add an explicit zero:
```yaml
# ❌ Phantom $20 appears in 2005:
values:
  2006-07-01: 20

# ✅ Zero before program start:
values:
  2000-01-01: 0
  2006-07-01: 20
```

**Don't duplicate unchanged values.** If a value is the same across eras, keep one entry at the earliest applicable date.

**Before removing "duplicate" date entries**, verify ALL sub-categories — what looks identical at the top level may differ in specific combinations (e.g., School Age Part Time rates changed while other age/time categories stayed the same).

**Flag unverified historical values** in the PR description rather than silently including them.

---

## 4. Metadata Fields (ALL REQUIRED)

### unit
Common units:
- `currency-USD` - Dollar amounts
- `/1` - Rates, percentages (as decimals)
- `month` - Number of months
- `year` - Age in years
- `bool` - True/false
- `person` - Count of people

### period
- `year` - Annual values
- `month` - Monthly values
- `day` - Daily values
- `eternity` - Never changes

**Match `period` to the parameter's semantic meaning.** A dimensionless rate or ratio should use `period: year`, not the period of the quantity it modifies (e.g., don't use `period: week` for a weekly copay *rate* — the rate itself is time-invariant).

### label
Pattern: `[State] [PROGRAM] [description]`
```yaml
label: Montana TANF minor child age threshold
label: Illinois TANF earned income disregard rate
label: California SNAP resource limit
```
**Rules:**
- Spell out state name
- Abbreviate program (TANF, SNAP)
- No period at end

### reference
**Requirements:**
1. At least one source (prefer two)
2. Must contain the actual value
3. **Title: Include FULL section path** (all subsections and sub-subsections)
4. **PDF links: Add `#page=XX` at end of href ONLY** (never in title)
5. **Verify page numbers** — open the PDF and confirm the page number is correct before using it

**Reference Source Hierarchy — prefer online over PDF:**
1. **Online statute/regulation** (best): Cornell LII, state legislature sites, public.law
   - Example: `https://www.law.cornell.edu/regulations/rhode-island/218-RICR-20-00-4.6`
2. **Official government HTML page**: `.gov` pages with section anchors
3. **PDF with verified page number** (last resort): Only when no online HTML version exists
   - Rate schedules, policy manuals without HTML versions
   - Always verify the `#page=XX` is correct

Why: Online references are linkable, searchable, and don't require page number verification. PDF page numbers are error-prone (file page vs printed page) and links break when documents are updated.

**Title Format - Include ALL subsection levels (NO page numbers):**
```yaml
# ❌ BAD - Too generic:
title: OAR 461-155  # Missing subsections!
title: Section 5    # Which subsection?
title: TEA Manual, page 13  # Page number belongs in href, not title!

# ✅ GOOD - Full section path, no page number:
title: OAR 461-155-0030(2)(a)(B)     # All levels included
title: 7 CFR § 273.9(d)(6)(ii)(A)    # Federal regulation with all subsections
title: Indiana Admin Code 12-14-2-3.5(b)(1)  # State admin code
title: Arkansas TEA Manual Section 5.2.3    # Manual with section (page in href)
```

**PDF Link Format - Always include page in href:**

**CRITICAL: Use the PDF file page number, NOT the printed page number inside the document.**
- The `#page=XX` value is the page position in the PDF file (1st page = 1, 2nd page = 2, etc.)
- This may differ from the page number printed on the document itself
- **Why?** When users click the link, they must land directly on the page showing the referenced values

```yaml
# ❌ BAD - No page number:
href: https://state.gov/manual.pdf

# ✅ GOOD - Page anchor in href (file page number):
href: https://humanservices.arkansas.gov/wp-content/uploads/TEA_MANUAL.pdf#page=13
href: https://adminrules.idaho.gov/rules/current/16/160503.pdf#page=8
```

**Complete Examples:**
```yaml
✅ GOOD (page number in href only):
reference:
  - title: OAR 461-155-0030(2)(a)(B)
    href: https://oregon.public.law/rules/oar_461-155-0030
  - title: Oregon DHS TANF Policy Manual Section 4.3.2
    href: https://oregon.gov/dhs/tanf-manual.pdf#page=23

✅ GOOD:
reference:
  - title: 7 CFR § 273.9(d)(6)(ii)(A)
    href: https://www.ecfr.gov/current/title-7/section-273.9#p-273.9(d)(6)(ii)(A)
  - title: Arkansas TEA Manual Section 2100
    href: https://humanservices.arkansas.gov/wp-content/uploads/TEA_MANUAL.pdf#page=45

❌ BAD (page number in title):
reference:
  - title: Arkansas TEA Manual, page 13  # Page belongs in href!
    href: https://humanservices.arkansas.gov/wp-content/uploads/TEA_MANUAL.pdf

❌ BAD (missing info):
reference:
  - title: Federal LIHEAP regulations  # Too generic - no section!
    href: https://www.acf.hhs.gov/ocs  # No specific page
  - title: OAR 461-155  # Missing subsections (2)(a)(B)!
    href: https://oregon.gov/manual.pdf  # Missing #page=XX
```

### Reference Verification Rules

**Distinguish statute from regulation.** Cite the statute that establishes a rule and the regulation that implements it separately — they are different legal instruments.

**Prefer direct document URLs** over landing-page or index-page URLs. Agency websites frequently reorganize navigation pages while direct document links remain stable.

**Annotate reference coverage windows.** When a source has a known publication cutoff (e.g., last published in 2011), note which values it corroborates — don't cite it for values postdating the cutoff.

**Secondary sources (WorkWorld, SSA reports) are simplified.** They may omit eligibility requirements, payment categories, or add interpretive language. Always treat the Admin Code/state regulation as authoritative; use secondary sources for cross-verification only.

**Verify regulation text is present.** When fetching from legal databases (Cornell LII, Westlaw), verify the content contains actual regulation body text, not just a JavaScript shell — many databases render client-side.

**When a regulation portal migrates domains**, update ALL parameter files referencing the old domain in one pass — broken redirects are systematic.

**For state policy choices, cite the state regulation**, not the federal CFR that merely sets the ceiling.

---

## 5. Federal/State Separation

### Federal Parameters
Location: `/parameters/gov/{agency}/{program}/`
```yaml
# parameters/gov/hhs/fpg/first_person.yaml
description: HHS sets this amount as the federal poverty guideline for one person.
```

### State Parameters
Location: `/parameters/gov/states/{state}/{agency}/{program}/`
```yaml
# parameters/gov/states/ca/dss/tanf/income_limit/rate.yaml
description: California uses this multiplier of the federal poverty guideline for TANF income eligibility.
```

---

## 5.5 Parameter Folder Organization

### Core Principles

1. **Group logically** - Parameters that relate to the same aspect should be together
2. **Don't create subfolder for 1 file** - If only 1 parameter for an aspect, keep it at parent level
3. **Payment standard at root** - Main benefit amounts can stay at program root

### Common Aspects (adapt to your program)

- `income/` - Income limits, deductions, disregards
- `eligibility/` - Age thresholds, citizenship requirements
- `resources/` - Asset/resource limits

### Study Existing Implementations

Each program is different. Before organizing, look at similar programs:
```bash
ls policyengine_us/parameters/gov/states/{state}/{agency}/
```

---

## 6. Common Parameter Patterns

### Income Limits (as FPL multiplier)
```yaml
# income_limit/rate.yaml
description: State uses this multiplier of the federal poverty guideline for program income limits.
values:
  2024-01-01: 1.85  # 185% FPL

metadata:
  unit: /1
  period: year
  label: State PROGRAM income limit multiplier
```

### Benefit Amounts
```yaml
# payment_standard/amount.yaml
description: State provides this amount as the monthly program benefit.
values:
  2024-01-01: 500

metadata:
  unit: currency-USD
  period: month
  label: State PROGRAM payment standard amount
```

### Age Thresholds (Simple)
```yaml
# age_threshold/minor_child.yaml
description: State defines minor children as under this age for program eligibility.
values:
  2024-01-01: 18

metadata:
  unit: year
  period: eternity
  label: State PROGRAM minor child age threshold
```

### Age-Based Eligibility (Bracket Style) - PREFERRED

**When eligibility depends on age ranges, use a single bracket-style parameter instead of separate min/max files.**

```yaml
# eligibility/by_age.yaml
description: Massachusetts determines eligibility for the Bay Transportation reduced fare program based on age.

metadata:
  threshold_unit: year
  amount_unit: bool
  period: year
  type: single_amount
  label: Massachusetts Bay Transportation reduced fare age eligibility
  reference:
    - title: MBTA Reduced Fare Program
      href: https://www.mbta.com/fares/reduced

brackets:
  - threshold:
      2024-01-01: 0
    amount:
      2024-01-01: false    # Under 18: not eligible
  - threshold:
      2024-01-01: 18
    amount:
      2024-01-01: true     # Ages 18-64: eligible
  - threshold:
      2024-01-01: 65
    amount:
      2024-01-01: false    # 65+: not eligible (different program)
```

**Federal example (SNAP student eligibility):**
```yaml
# parameters/gov/usda/snap/student_age_eligibility_threshold.yaml
description: The United States includes students in this age range for SNAP eligibility.

brackets:
  - threshold:
      2018-01-01: 0
    amount:
      2018-01-01: true     # Under 18: eligible
  - threshold:
      2018-01-01: 18
    amount:
      2018-01-01: false    # Ages 18-49: not eligible (student restrictions)
  - threshold:
      2018-01-01: 50
    amount:
      2018-01-01: true     # 50+: eligible

metadata:
  type: single_amount
  threshold_unit: year
  amount_unit: bool
  label: SNAP student age eligibility threshold
  reference:
    - title: 7 U.S. Code § 2015 - Eligibility disqualifications
      href: https://www.law.cornell.edu/uscode/text/7/2015
```

**When to use bracket-style:**
- ✅ Eligibility varies by age range (eligible for ages X-Y only)
- ✅ Multiple age cutoffs affect the same benefit
- ✅ Boolean eligibility that changes at different thresholds
- ✅ Non-contiguous eligibility (e.g., eligible under 18 AND over 50, but not 18-49)

**When NOT to use bracket-style:**
- ❌ Single threshold (just use simple `thr

…

## Source & license

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

- **Author:** [PolicyEngine](https://github.com/PolicyEngine)
- **Source:** [PolicyEngine/policyengine-claude](https://github.com/PolicyEngine/policyengine-claude)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-policyengine-policyengine-claude-policyengine-parameter-patterns-skill
- Seller: https://agentstack.voostack.com/s/policyengine
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.