essential

Audit a web app's SEO — meta tags, crawlability, performance, and content structure

Audit a state income tax PR's parameter values against official PDF sources (read-only, no code changes)

Orchestrates multi-agent workflow to backdate and quality-improve existing state program parameters

Orchestrates multi-agent workflow to create a PolicyEngine dashboard from a natural-language description

Build new UI components for @policyengine/ui-kit — with design token validation, tests, visual preview, and PR creation

Create PR as draft, wait for CI to pass, then mark ready for review (solves the "I'll check back later" problem)

Lists all available tools, commands, skills, and agents in the dashboard builder ecosystem

Deploys a PolicyEngine dashboard to Vercel (and optionally Modal) and registers it in the app

Orchestrates multi-agent workflow to implement new government benefit programs (v2 — agent teams, user checkpoint, requirements tracking)

Orchestrates multi-agent workflow to implement new government benefit programs

Orchestrates multi-agent workflow to implement contributed policy reforms (proposed bills, policy experiments)

Download and extract text from a PDF URL using curl and a PDF text extraction tool.

Apply fixes to a PR based on /review-program findings or PR review comments

Generate social images and posts from a blog post or announcement

Scaffold a new PolicyEngine interactive tool (Next.js 14 + Tailwind 4 + ui-kit theme + embedding boilerplate)

Review an existing PR and post findings to GitHub (read-only, no code changes)

Review any PR — code validation + PDF audit in one pass (read-only, no code changes)

Install PolicyEngine-themed spinner verbs into your Claude Code settings

Write unit tests for source files using Given-When-Then conventions, fixture extraction, and edge case coverage

This repository contains specialized Claude agents for PolicyEngine development across different types of repositories.

You are the API Reviewer Agent responsible for ensuring PolicyEngine API implementations follow best practices, are performant, secure, and properly tested.

You are the App Reviewer Agent responsible for ensuring PolicyEngine React application code follows best practices, is performant, accessible, and provides excellent user experience.

You are the Component Test Writer Agent. Your job is to write comprehensive unit tests for UI components in `@policyengine/ui-kit` using Vitest and React Testing Library.

You are the Design Token Validator Agent. Your job is to review UI components in `@policyengine/ui-kit` and ensure that as many design elements as possible use the existing design tokens rather than hardcoded values.

You audit a web application's HTML content structure, heading hierarchy, semantic elements, and accessibility attributes that affect SEO. You report findings but do NOT make code changes.

You audit a web application's crawlability — whether search engines can discover, access, and understand all the app's content. You report findings but do NOT make code changes.

You audit a web application's HTML entry points for required SEO meta tags, Open Graph tags, Twitter Card tags, canonical URLs, and structured data. You report findings but do NOT make code changes.

You audit a web application's performance characteristics that affect SEO ranking — bundle sizes, code splitting, asset optimization, and loading strategy. You report findings but do NOT make code changes.

You are a specialized agent that compares how two git branches implement the **same government benefit program** and analyzes which implementation approach is better.

Orchestrates content generation from blog posts - social images and social copy

Creates PR, monitors CI, fixes issues iteratively until all tests pass

Validates interactions between benefit programs to prevent integration issues

Gathers authoritative documentation for government benefit program implementations

Automatically enriches code with examples, references, and calculation walkthroughs

Automatically generates comprehensive edge case tests for benefit programs

Comprehensive validator for PolicyEngine implementations - quality standards, domain patterns, naming conventions, and compliance

Merges parallel development branches and fixes basic integration issues

Agents work in separate worktrees and are instructed not to access others. This relies on compliance.

1. **Enable the Claude Code Hook**

Finds or creates GitHub issues for program implementations

Optimizes benefit calculations for performance and vectorization

Ensures PRs are properly formatted with changelog, linting, and tests before pushing

Reviews government program implementations by researching regulations first, then validating code against legal requirements

Creates parameter YAML files and variable Python files for government benefit programs with zero hard-coded values

Creates comprehensive integration tests for government benefit programs ensuring realistic calculations

> **⚠️ ADVANCED WORKFLOW - FOR REFERENCE ONLY**

Builds the data layer for a dashboard — precomputed JSON, PolicyEngine API client, or custom Modal backend

Validates Tailwind v4, Next.js App Router, ui-kit integration, and package manager usage

Runs build and test suite for a dashboard implementation

Validates design token usage, typography, sentence case, and responsive design

Wires frontend components to backend API client and ensures end-to-end data flow works

Checks if dashboard ecosystem components changed during a create-dashboard run and updates the dashboard-overview command accordingly

Validates that the implementation matches plan.yaml — API contract, component completeness, embedding, and state handling

Analyzes natural-language dashboard descriptions and produces structured implementation plans

Generates project structure from an approved dashboard plan into the current working directory

Builds React frontend components following policyengine-app-v2 design system and chart patterns

Use this agent when you need to analyze legislative text to identify and explain key statutes, their references, cross-references, and implications. This includes reviewing bills, acts, regulations, or legal documents to extract statutory provisions, understand their relationships, and summarize their legal significance. <example>Context: The user wants to analyze a piece of legislation to understand its key provisions. user: "Please review this tax reform bill and identify the main statutes" assistant: "I'll use the legislation-statute-analyzer agent to review this bill and identify the key statutes and their references" <commentary>Since the user wants to analyze legislation for statutory content, use the Task tool to launch the legislation-statute-analyzer agent.</commentary></example> <example>Context: The user needs help understanding regulatory text. user: "Can you review Section 401(k) of the Internal Revenue Code and tell me what it refers to?" assistant: "Let me use the legislation-statute-analyzer agent to analyze this section and identify what it refers to" <commentary>The user is asking for analysis of specific statutory provisions, so use the legislation-statute-analyzer agent.</commentary></example>

Validates that all parameters have proper references that corroborate the values

Systematically evaluate PolicyEngine country implementations for quality, completeness, and compliance with standards.

Reviews PolicyEngine output for policy neutrality — flags advocacy, speculation, scope overreach, and one-sided framing in papers, blog posts, tools, and project communications

This document contains the shared standards and guidelines that all PolicyEngine agents must follow, particularly the Rules Engineer and Reviewer agents.

When asked to "action", "merge", or "complete" a PR, follow this checklist BEFORE merging:

Common analysis patterns for PolicyEngine research repositories (CRFB, newsletters, dashboards, impact studies). For population-level estimates (cost, poverty, distributional impacts), use the policyengine-microsimulation skill instead.

Analyze policy impacts for congressional districts and representatives' constituents. Use when the user mentions a specific district (NY-17, CA-52), a representative's name, or asks about geographic policy impacts at district level. Provides HuggingFace district datasets.

Generate marketing content from PolicyEngine blog posts - social media images, social post copy, and branded assets

L0 regularization for neural network sparsification and intelligent sampling - used in survey calibration. Triggers: "L0", "sparsification", "sample selection", "hard concrete", "sparse weights", "household selection", "gate", "survey sparsity", "l0-python"

Survey weight calibration to match population targets - used in policyengine-us-data for enhanced microdata. Triggers: "calibrate", "calibration", "survey weights", "reweighting", "population targets", "benchmarks", "microcalibrate", "weight adjustment", "target matching"

Weighted pandas DataFrames for survey microdata analysis - inequality, poverty, and distributional calculations. Triggers: "weighted mean", "Gini", "poverty rate", "inequality", "MicroDataFrame", "MicroSeries", "weighted statistics", "decile", "quintile", "income distribution", "microdf"

ML-based variable imputation for survey data - used in policyengine-us-data to fill missing values. Triggers: "impute", "imputation", "missing values", "donor", "recipient", "quantile forest", "statistical matching", "PUF", "microimpute", "fill missing"

UK survey data enhancement - FRS with WAS imputation patterns and cross-repo variable workflows. Triggers: "FRS", "Family Resources Survey", "WAS", "Wealth and Assets Survey", "UK data", "UK microdata", "wealth imputation", "policyengine-uk-data"

US survey data enhancement - CPS with PUF imputation patterns and cross-repo variable workflows. Triggers: "CPS", "Current Population Survey", "PUF", "Public Use File", "US data", "US microdata", "enhanced CPS", "policyengine-us-data", "cross-repo", "FINANCIAL_SUBSET"

PolicyEngine design system — tokens, typography, colors, charts, and branding for all project types. Triggers: "brand colors", "design tokens", "PolicyEngine colors", "typography", "font", "color palette", "CSS variables", "design system", "branding guidelines"

Use this skill when updating the PolicyEngine skills source repo or the generated policyengine-claude wrapper — adding skills, fixing skill routing, updating years in code examples, reordering skills, or tuning skill descriptions. Triggers: "update plugin", "fix skill", "wrong skill loaded", "update year", "plugin maintenance", "skill routing", "skill description", "policyengine-claude plugin", "policyengine-skills".

Find and reference PolicyEngine blog posts, research articles, and published analyses for evidence and proof points. Triggers: "find blog post", "PolicyEngine research", "published analysis", "proof point", "has PolicyEngine written about", "blog post about"

PolicyEngine coding standards, formatters, CI requirements, and development best practices. Triggers: "CI failing", "linting", "formatting", "before committing", "PR standards", "code style", "ruff formatter", "prettier", "pre-commit"

Using PolicyEngine web apps to analyze tax and benefit policy impacts - for users of policyengine.org. Triggers: "how to use PolicyEngine", "household calculator", "policy reform on website", "policyengine.org walkthrough", "web app guide"

PolicyEngine writing style for blog posts, documentation, PR descriptions, and research reports - emphasizing active voice, quantitative precision, and neutral tone

ALWAYS LOAD THIS SKILL FIRST before writing any PolicyEngine-Canada code. Contains Canadian federal and provincial tax/benefit rules for household calculations. IMPORTANT: PolicyEngine-Canada does NOT have representative population microdata. Do NOT attempt microsimulation or population-level estimates for Canada. Only provide household-level analysis (single-family impacts, eligibility, benefit amounts). Triggers: "what would", "how much would a", "benefit be", "eligible for", "qualify for", "single parent", "married couple", "family of", "household of", "if they earn", "earning $", "making $", "calculate benefits", "calculate taxes", "benefit for a", "what would I get", "what is the maximum", "what is the rate", "income limit", "benefit amount", "maximum benefit", "compare provinces", "CCB", "Canada Child Benefit", "GST credit", "HST credit", "GST/HST", "OAS", "Old Age Security", "GIS", "Guaranteed Income Supplement", "CWB", "Canada Workers Benefit", "EI", "Employment Insurance", "CPP", "Canada Pension Plan", "RRSP", "TFSA", "Ontario Child Benefit", "OCB", "Ontario Trillium Benefit", "OTB", "BC Climate Action", "Alberta Child Benefit", "Quebec", "CRA", "Canada Revenue Agency", "Canadian", "Canada", "Ontario", "British Columbia", "Alberta", "Saskatchewan", "Manitoba", "Nova Scotia", "New Brunswick", "PEI", "Newfoundland", "Yukon", "NWT", "Nunavut", "provincial tax", "federal tax Canada".

Healthcare program modeling in PolicyEngine-US — Medicaid, ACA marketplace, CHIP, and Medicare. Covers encoding rules, running analyses, and navigating the unique complexity of US healthcare programs. Triggers: "healthcare", "health insurance", "Medicaid", "ACA", "CHIP", "Medicare", "marketplace", "premium tax credit", "APTC", "PTC", "SLCSP", "benchmark plan", "rating area", "age curve", "family tier", "coverage gap", "Medicaid expansion", "MAGI", "medicaid_magi", "aca_magi", "medicaid_income_level", "medicaid_category", "enrollment", "takeup", "take-up", "per capita", "CSR", "cost sharing", "insurance premium", "second lowest silver", "required contribution percentage", "42 CFR", "IRC 36B", "categorical eligibility", "expansion adult", "healthcare reform", "healthcare analysis", "health policy".

ALWAYS LOAD THIS SKILL FIRST before writing any PolicyEngine-UK code. Contains the correct API patterns for household calculations and population simulations using the new policyengine package (not policyengine_uk directly). Triggers: "what would", "how much would a", "benefit be", "eligible for", "qualify for", "single parent", "married couple", "family of", "household of", "if they earn", "with income of", "earning £", "making £", "calculate benefits", "calculate taxes", "benefit for a", "tax for a", "what would I get", "what would they get", "what is the rate", "what is the threshold", "personal allowance", "maximum benefit", "income limit", "benefit amount", "how much is", "Universal Credit", "child benefit", "pension credit", "housing benefit", "council tax", "income tax", "national insurance", "JSA", "ESA", "PIP", "disability living allowance", "working tax credit", "child tax credit", "Scotland", "Wales", "UK", "microsimulation", "population", "reform", "policy impact", "budgetary", "decile".

ALWAYS LOAD THIS SKILL FIRST before writing any PolicyEngine-US code. Contains the correct API patterns for household calculations and population simulations using the new policyengine package. Covers US federal and state taxes/benefits. Triggers: "what would", "how much would a", "benefit be", "eligible for", "qualify for", "single parent", "married couple", "family of", "household of", "if they earn", "earning $", "making $", "calculate benefits", "calculate taxes", "benefit for a", "what would I get", "what is the maximum", "what is the rate", "poverty line", "income limit", "benefit amount", "maximum benefit", "compare states", "TANF", "SNAP", "EITC", "CTC", "SSI", "WIC", "Section 8", "Medicaid", "ACA", "child tax credit", "earned income", "supplemental security", "housing voucher", "microsimulation", "population", "reform", "policy impact", "budgetary", "decile".

Tailwind CSS v4 + shadcn/ui integration patterns for PolicyEngine frontend projects. Covers @theme namespaces, CSS variable conventions, SVG var() usage, and common mistakes. Triggers: "Tailwind v4", "@theme", "shadcn", "CSS variables", "design tokens CSS", "theme.css", "@theme inline"

This skill should be used when setting up a new project that uses @policyengine/ui-kit, debugging CSS or styling issues in a consumer app, or when Tailwind utility classes are not being generated. Also use when creating globals.css, configuring PostCSS, or troubleshooting "no styles", "no spacing", or "no layout" problems. Triggers: "ui-kit import", "globals.css setup", "Tailwind not working", "styles not applying", "utility classes missing", "setup ui-kit", "PostCSS config", "no styling", "CSS broken", "import ui-kit", "theme.css", "no layout", "no spacing", "@tailwindcss/postcss"

PolicyEngine aggregation patterns - using adds attribute and add() function for summing variables across entities

Code organization patterns for PolicyEngine - variable naming conventions, folder structure, file organization

PolicyEngine code writing style guide - formula optimization, direct returns, eliminating unnecessary variables

Testing patterns for PolicyEngine data generation pipelines (policyengine-us-data, policyengine-uk-data)

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

PolicyEngine period handling - converting between YEAR, MONTH definition periods and testing patterns

Recharts chart patterns, formatting, and styling for PolicyEngine apps

PolicyEngine reform patterns - factory functions, contrib parameters, in_effect toggles, registration, and test keys for contributed policy reforms

PolicyEngine code review patterns - validation checklist, common issues, review standards

This skill should be used when writing unit tests, integration tests, or test fixtures for PolicyEngine frontend apps, APIs, SDKs, and standalone tools. NOT for country model packages (policyengine-us, policyengine-uk, etc.) — those use YAML-based tests with their own conventions. Covers the Given-When-Then naming convention, fixture extraction, edge case coverage, and the rule that only modified test files should be run. Triggers: "write tests", "add tests", "unit test", "test file", "test coverage", "write a test for", "test this function", "test this component", "given when then", "test fixtures", "mock setup", "edge cases", "test naming", "test convention"

PolicyEngine testing patterns - YAML test structure, naming conventions, period handling, and quality standards

PolicyEngine variable patterns - variable creation, no hard-coding principle, federal/state separation, metadata standards

PolicyEngine vectorization patterns - NumPy operations, where/select usage, avoiding scalar logic with arrays

ALWAYS LOAD THIS SKILL before setting up any Python environment or installing packages. Defines the standard: uv, Python 3.13, uv pip install, .venv at project root. Triggers: "set up python", "install python", "create a venv", "virtual environment", "pip install", "install packages", "uv pip", "uv venv", "python version", "VIRTUAL_ENV", "venv conflict", "which python", "activate", "deactivate", "run the script", "run with uv", "uv run", "pyproject.toml", "install dependencies", "install requirements", "install the package", "editable install", "pip install -e".

SEO first principles for PolicyEngine web applications - meta tags, crawlability, performance, and dual-mode (standalone + iframe) considerations

PolicyEngine API - Flask REST service powering policyengine.org and programmatic access

PolicyEngine API v2 - Next-generation microservices architecture with monorepo structure

Developing policyengine-app-v2 — the main React frontend for policyengine.org

PolicyEngine Core simulation engine - the foundation powering all PolicyEngine calculations

Reference for the /create-dashboard and /deploy-dashboard orchestrated AI workflow

Mandatory frontend technology requirements for PolicyEngine dashboards and interactive tools — Tailwind CSS v4, Next.js (App Router), @policyengine/ui-kit theme, Vercel deployment

Guidance for working with the PolicyEngine GitHub agent bot

Building standalone interactive calculators and dashboards that embed in policyengine.org

ALWAYS USE THIS SKILL for PolicyEngine microsimulation, population-level analysis, winners/losers calculations. Triggers: "microsimulation", "share who would lose/gain", "policy impact", "national average", "weighted analysis", "cost", "revenue impact", "budgetary", "estimate the cost", "federal revenues", "tax revenue", "budget score", "how much would it cost", "how much would the policy cost", "total cost of", "aggregate impact", "cost to the government", "revenue loss", "fiscal impact", "poverty impact", "child poverty", "deep poverty", "poverty rate", "poverty reduction", "how many people lifted out of poverty", "SPM poverty", "distributional impact", "state tax", "state-level", "California", "New York", "UBI", "universal basic income", "flat tax", "standard deduction", "winners and losers", "winners", "losers", "inequality", "Gini", "decile", "SALT", "marginal tax rate", "effective tax rate". NOT for single-household calculations like "what would my benefit be" — use policyengine-us or policyengine-uk for those. Use this skill's code pattern, but explore the codebase to find specific parameter paths if needed.

Deploying PolicyEngine backend APIs to Modal — workspace setup, authentication, deployment commands, environments, and troubleshooting

ONLY use this skill when users explicitly ask about the PolicyEngine Python package installation, REST API endpoints, API authentication, rate limits, or policyengine.py client library. DO NOT use for household benefit/tax calculations — ALWAYS use policyengine-us or policyengine-uk instead. This skill is about the API/client tooling itself, not about calculating benefits or taxes.

ALWAYS LOAD THIS SKILL before writing any policyengine.py microsimulation code. Contains correct import paths, environment setup, dataset loading, and analysis patterns. Triggers: "write a script", "policyengine.py", "microsimulation script", "run a simulation", "load the dataset", "FRS", "EFRS", "enhanced FRS", "CPS", "enhanced CPS", "by income decile", "by tenure", "by region", "energy spending", "domestic energy", "household net income", "output_dataset", "ensure_datasets", "uk_datasets", "us_datasets", "import datasets", "from policyengine", "Simulation(dataset=", "uk_latest", "us_latest", "plotly", "analysis script", "decile breakdown", "percentile", "groupby", "weighted", "mean", "median", "p25", "p75", "tenure type", "income band", "policy reform script".

Deploying PolicyEngine frontend apps to Vercel - naming, scope, team settings

3 hooks across 3 events