Agent skills
policyengine-parameter-pattern...

Agent skill

policyengine-parameter-patterns

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

Stars 163

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/policyengine-parameter-patterns

SKILL.md

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 naming, examine:

DC TANF: /parameters/gov/states/dc/dhs/tanf/
IL TANF: /parameters/gov/states/il/dhs/tanf/
TX TANF: /parameters/gov/states/tx/hhs/tanf/

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:

[State]: Full state name (Indiana, Texas, California)
[verb]: ONLY use: limits, provides, sets, excludes, deducts, uses
[category]: What's being limited/provided (gross income, resources, payment standard)
[this X]: ALWAYS use generic placeholder
- this amount (for currency-USD)
- this share or this percentage (for rates/percentages)
- this threshold (for age/counts)
[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.

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)

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

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:

At least one source (prefer two)
Must contain the actual value
Title: Include FULL section path (all subsections and sub-subsections)
PDF links: Add #page=XX at end of href ONLY (never in title)

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

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

Group logically - Parameters that relate to the same aspect should be together
Don't create subfolder for 1 file - If only 1 parameter for an aspect, keep it at parent level
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 threshold.yaml)
❌ Non-boolean values that scale with age (use single_amount brackets with currency amounts)

Disregard Percentages

yaml

# income/disregard/percentage.yaml
description: State excludes this share of earned income from program calculations.
values:
  2024-01-01: 0.67  # 67%

metadata:
  unit: /1
  period: eternity
  label: State PROGRAM earned income disregard percentage

7. Validation Checklist

Before creating parameters:

Studied reference implementations (DC, IL, TX)
All four metadata fields present
Description is one complete sentence
Values use underscore separators
Trailing zeros removed from decimals
References include subsections and page numbers
Label follows naming pattern
Effective date matches source document

8. Common Mistakes to Avoid

Missing Metadata

yaml

❌ WRONG - Missing required fields:
metadata:
  unit: currency-USD
  label: Benefit amount
  # Missing: period, reference

Generic References

yaml

❌ WRONG:
reference:
  - title: State TANF Manual
    href: https://state.gov/tanf

✅ CORRECT:
reference:
  - title: State TANF Manual Section 5.2, page 15
    href: https://state.gov/tanf-manual.pdf#page=15

Arbitrary Dates

yaml

❌ WRONG:
values:
  2000-01-01: 500  # Lazy default

✅ CORRECT:
values:
  2023-07-01: 500  # From source: "effective July 1, 2023"

Real-World Examples from Production Code

CRITICAL: Study actual parameter files, not just examples!

Before writing ANY parameter:

Open and READ 3+ similar parameter files from TX/IL/DC
COPY their exact description pattern
Replace state name and specific details only

Payment Standards

yaml

# Texas (actual production)
description: Texas provides this amount as the payment standard under the Temporary Assistance for Needy Families program.

# Pennsylvania (actual production)
description: Pennsylvania limits TANF benefits to households with resources at or below this amount.

Income Limits

yaml

# Indiana (should be)
description: Indiana limits gross income to this amount under the Temporary Assistance for Needy Families program.

# Texas (actual production)
description: Texas limits countable resources to this amount under the Temporary Assistance for Needy Families program.

Disregards

yaml

# Indiana (should be)
description: Indiana excludes this share of earnings from countable income under the Temporary Assistance for Needy Families program.

# Texas (actual production)
description: Texas deducts this standard work expense amount from gross earned income for Temporary Assistance for Needy Families program calculations.

Pattern Analysis

ALWAYS spell out full program name
Use "under the [Program] program" or "for [Program] program calculations"
One simple verb (limits, provides, excludes, deducts)
One "this X" placeholder
NO extra explanation ("based on X", "This is Y")

Common Description Mistakes to AVOID

❌ WRONG - Using acronyms:

yaml

description: Indiana sets this gross income limit for TANF eligibility by household size.
# Problems: "TANF" not spelled out, unnecessary "by household size"

✅ CORRECT:

yaml

description: Indiana limits gross income to this amount under the Temporary Assistance for Needy Families program.

❌ WRONG - Adding explanatory text:

yaml

description: Indiana provides this payment standard amount based on household size.
# Problem: "based on household size" is unnecessary (evident from breakdown)

✅ CORRECT:

yaml

description: Indiana provides this amount as the payment standard under the Temporary Assistance for Needy Families program.

❌ WRONG - Missing program context:

yaml

description: Indiana sets the gross income limit.
# Problem: No program name, no "this amount"

✅ CORRECT:

yaml

description: Indiana limits gross income to this amount under the Temporary Assistance for Needy Families program.

Authoritative Source Requirements

ONLY use official government sources:

✅ State codes and administrative regulations
✅ Official state agency websites (.gov domains)
✅ Federal regulations (CFR, USC)
✅ State plans and official manuals (.gov PDFs)

NEVER use:

❌ Third-party guides (singlemotherguide.com, benefits.gov descriptions)
❌ Wikipedia
❌ Nonprofit summaries (unless no official source exists)
❌ News articles

For Agents

When creating parameters:

READ ACTUAL FILES - Study TX/IL/DC parameter files, not just skill examples
Include ALL metadata fields - missing any causes errors
Use exact effective dates from sources
Follow naming conventions (amount/rate/threshold)
Write simple descriptions with "this" placeholders and full program names
Include ONLY official government references with subsections and pages
Format values properly (underscores, no trailing zeros)

Maintainer

majiayu000 Core maintainer

Source details

Full Name: majiayu000/claude-skill-registry
Branch: main
Path in repo: skills/data/policyengine-parameter-patterns
License: MIT License

Featured Tools

Join Our Newsletter

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

PolicyEngine Parameter Patterns

Critical: Required Structure

1. File Naming Conventions

Study Reference Implementations First

Naming Patterns

2. Description Field

The ONLY Acceptable Formula

Copy These Exact Templates

Description Validation Checklist

3. Values Section

Format Rules

Effective Dates

4. Metadata Fields (ALL REQUIRED)

unit

period

label

reference

5. Federal/State Separation

Federal Parameters

State Parameters

5.5 Parameter Folder Organization

Core Principles

Common Aspects (adapt to your program)

Study Existing Implementations

6. Common Parameter Patterns

Income Limits (as FPL multiplier)

Benefit Amounts

Age Thresholds (Simple)

Age-Based Eligibility (Bracket Style) - PREFERRED

Disregard Percentages

7. Validation Checklist

8. Common Mistakes to Avoid

Missing Metadata

Generic References

Arbitrary Dates

Real-World Examples from Production Code

Payment Standards

Income Limits

Disregards

Pattern Analysis

Common Description Mistakes to AVOID

Authoritative Source Requirements

For Agents

Recommended Agent Skills

agent-ops-spec

agent-ops-state

agent-ops-spec

agent-ops-testing

agent-ops-testing

agent-ops-state