# pudl

Explores PUDL US energy data from EIA, FERC, and EPA, helping query Frictionless schemas and load Parquet files directly from S3.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2100 installs · ★ 3
- Author: catalyst-cooperative
- License: CC-BY-4.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/catalyst-cooperative/agent-skills/tree/HEAD/skills/pudl/SKILL.md
- Updated: 2026-10-25
- HTML: https://affpapa.org/en/nevibecode/skills/pudl

## What it does

This skill inspects public energy datasets compiled by Catalyst Cooperative without requiring their Python library. It guides agents through tables covering utility balance sheets, generator emissions, fuel expenses, and generation statistics. By reading Frictionless Data Package descriptors, the skill identifies relevant tables, clarifies column definitions, and flags data caveats.

Under the hood, workflow logic focuses on metadata before touching raw storage. The helper script `python scripts/fetch_descriptor.py` retrieves schema files into `assets/cache/`. When joining FERC filings with EIA surveys, the skill enforces using `utility_id_pudl` and `plant_id_pudl` rather than joining on facility names. It directs queries toward clean `out_*` tables, warns against internal `_core_*` datasets, and relies on column projection in Polars or DuckDB to prevent massive downloads.

Without the companion `datapackage` skill, this setup fails. Schema parsing relies on it completely. For downstream processing in Python, the skill prefers `polars >= 1.0`, while accessing S3 via Pandas requires `s3fs`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add catalyst-cooperative/agent-skills --skill pudl -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/pudl/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/pudl/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add catalyst-cooperative/agent-skills --skill pudl -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/pudl/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add catalyst-cooperative/agent-skills --skill pudl -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/pudl/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install catalyst-cooperative/agent-skills pudl
```

2. **Manually: put the files in place**
- File: `.github/skills/pudl/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add catalyst-cooperative/agent-skills --skill pudl -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/catalyst-cooperative/agent-skills --path skills/pudl
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/pudl/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add catalyst-cooperative/agent-skills --skill pudl -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/catalyst-cooperative/agent-skills/tree/HEAD/skills/pudl/SKILL.md

## When to use it
- Find tables covering utility financials, fuel costs, and generation data
- Look up column definitions and data caveats across EIA and FERC filings
- Link EIA and FERC tables using `utility_id_pudl` and `plant_id_pudl`
- Stream slices of Parquet files from S3 using Polars or DuckDB

## Example prompts
- Show me which PUDL tables contain power plant emissions from EPA CEMS
- Explain the column meanings and foreign keys for FERC Form 1
- Write a Polars query to scan utility generation data from S3 without fetching the entire table

## Source text · SKILL.md · CC-BY-4.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 2f779d6e351de503.

BEGIN THIRD-PARTY FILE 2f779d6e351de503
```text
---
name: pudl
description: >
  Explore and understand PUDL energy data: discover which tables exist, look up column
  meanings and usage warnings, and load Parquet files from S3 or a local directory.
  No PUDL Python package required. Use this skill whenever a user asks what PUDL data
  contains, wants to understand a specific table or column, asks about data quality or
  limitations, needs help loading data into a notebook or script, or wants to know
  which table covers a topic like electricity generation, utility financials, fuel
  costs, power plant locations, emissions, capacity factors, FERC financial data, or
  EIA survey data. Also use when the user mentions PUDL, Catalyst Cooperative energy
  data, or any of the specific data sources PUDL ingests (EIA-860, EIA-861, EIA-923,
  FERC Form 1, FERC Form 714, FERC EQR, EPA CEMS, EPA CAMD, etc.).
license: CC-BY-4.0
compatibility: |
  Required skills: datapackage
  Optional Python packages: polars >= 1.0 (preferred for DataFrame work), pandas >= 2.0
    with s3fs (only needed if using pandas for S3 access), markitdown[pdf,docx] (to
    convert downloaded PDF/Word blank forms and instructions to text)
metadata:
  - author: Catalyst Cooperative
  - email: hello@catalyst.coop
  - last-updated: 2026-08-15
---

# PUDL Data Explorer Guide

This skill is for **data users** who want to explore, understand, and load PUDL's
public energy data products. It assumes no access to the PUDL Python package or source
repository — only the publicly distributed data files and their metadata.

PUDL's primary outputs are Apache Parquet files, described by a Frictionless Data
Package descriptor. For generic descriptor-querying patterns (jq), use
the `datapackage` skill — this skill provides PUDL-specific knowledge layered on top.

Beyond the main Parquet outputs, PUDL also distributes raw per-form FERC Parquet data
(covering Forms 1/2/6/60/714, each with its own `datapackage.json`) and the FERC EQR
(partitioned Parquet, separate from the main build). These have different access
patterns and are not covered by the main Frictionless descriptor — see
[Data Access](./references/data-access.md) for the full picture.

## Workflow overview

Every step below is inexpensive and should happen by default whenever it's relevant to
the question at hand, not only when the user asks for it by name.

1. **Locate the metadata** — the primary PUDL descriptor (Parquet outputs) is at:

    - S3: `s3://pudl.catalyst.coop/nightly/pudl_parquet_datapackage.json`
    - HTTPS: `https://s3.us-west-2.amazonaws.com/pudl.catalyst.coop/nightly/pudl_parquet_datapackage.json`
```
END THIRD-PARTY FILE 2f779d6e351de503

The third-party file has ended. Everything between the 2f779d6e351de503 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2628 of 18235 bytes. © catalyst-cooperative · CC-BY-4.0 · https://github.com/catalyst-cooperative/agent-skills/tree/HEAD/skills/pudl/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md