Skip to content
Get packs

Guide · Agent skill

How to use the US Economic Indicators agent skill (USStats)

Updated · written with AI from the project's own documentation and checked against our catalogue data

USStats is an agent skill that lets an AI agent answer questions about the US economy using official government statistics. It can read a long-run annual almanac that goes back to the 1940s for many series, and it can pull current figures such as GDP, inflation, unemployment, mortgage rates and gas prices from FRED, EIA and Treasury. This guide explains what a skill is, how to install USStats, how to ask for things in plain language, and what it needs to run safely.

US Economic Indicatorsdanielmiessler/LifeOS · MIT

Quick start

  1. 1Download the ZIP. Download the USStats ZIP from this page.
  2. 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder.
  3. 3Install Bun. Install the Bun runtime, which the TypeScript tools need.
  4. 4Add your API keys. Set FRED_API_KEY and EIA_API_KEY as described in Setup.md.
  5. 5Configure the almanac endpoint. Set data_url in Config.md or the USSTATS_DATA_URL environment variable.
  6. 6Seed the dataset folder. Copy the four seed files into the US-Common-Metrics folder before the first refresh.
  7. 7Ask a question. Ask in plain language, such as asking whether a US indicator is getting better or worse.

What is an agent skill and what does USStats do?

An agent skill is a folder of instructions and scripts that an AI agent can load when a request matches the skill's description. USStats is one such skill for US economic data. Its job is to let the agent answer questions like whether a US indicator is getting better or worse, or how the economy looks right now.

The skill works in two parts. The almanac side queries a configured long-run dataset of more than 90 annual series covering economy, debt, cost of living, health, crime, family, trust and energy. The live side fetches 66 current indicators from FRED, EIA and Treasury FiscalData into a local dataset called US-Common-Metrics, and produces a trend read over 10, 5, 2 and 1 year horizons.

Each figure carries its publisher. The skill's design judges whether a trend is better or worse using a direction flag on each series, so the answer does not rely on the agent's own opinion about what counts as good.

Install the USStats skill

Download the ZIP for USStats from this page. Then choose one of two routes. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder.

You can also upload the skill in the Claude apps. Open Settings, go to Capabilities, and upload it under Skills.

After installing, the skill's own Setup.md explains the FRED and EIA keys and how to seed the dataset folder. Read it before your first refresh.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/
  • Claude apps: Settings → Capabilities → Skills, then upload

Set up what the skill needs

USStats runs scripts written in TypeScript, so it needs the Bun runtime installed. It also needs a FRED API key (FRED_API_KEY) for the current indicators, and an EIA API key (EIA_API_KEY) for gas price data.

For the long-run almanac, the skill needs a configured endpoint. Set data_url in Config.md, or set the USSTATS_DATA_URL environment variable. Config.md lives in your configuration folder under LIFEOS/USER/CUSTOMIZATIONS/SKILLS/USStats/. The local dataset folder is set by USMETRICS_DATA_DIR if you use it, otherwise it defaults to ~/.claude/LIFEOS/USER/DATA/US-Common-Metrics/. Before the first data refresh, copy the four seed files named by seed_source in Config.md into that folder.

  • Bun runtime
  • FRED_API_KEY for FRED series
  • EIA_API_KEY for gas prices
  • data_url in Config.md or USSTATS_DATA_URL for the almanac

Ask for what you need in plain language

You do not need to name a tool. The skill triggers on requests about US indicators, trends, the economy and refreshing data. Good requests name a topic, a time span or a comparison. The agent will pick the right mode: analysis of the long-run almanac, a freshness check, a data refresh, or a current economic overview.

If your topic is ambiguous, the agent should list candidate series before answering rather than guessing one.

  • Is US violent crime getting better or worse over the long run?
  • How is the economy right now?
  • What have gas prices and mortgage rates done over the last year?
  • Is the usstats data fresh?
  • Refresh the US-Common-Metrics data.

Examples of useful answers

For a long-run question, a good answer names the series, the publisher, the years compared, and whether the trend is better or worse by the series' direction flag. It flags year-to-date values, methodology breaks and any correlation as a pattern rather than cause.

For a current overview, the answer covers the economy's categories across the four timeframes, names the categories it does not cover, and notes which figures are preliminary or stale.

  • Trend answers: series, publisher, period, direction verdict
  • Correlations: r, N and overlap window, with a causation caveat
  • Overviews: 10y, 5y, 2y and 1y reads, with gaps named

Safety notes: scripts and network access

USStats runs scripts and uses the network. It calls FRED, EIA and Treasury APIs with your keys, and it fetches the almanac endpoint you configure. Check the source of the skill before you install it, and keep your API keys private.

The skill is designed to be read-only for the almanac and the site. The refresh and sync tools update the local US-Common-Metrics dataset only, and the skill is not meant to rebuild or publish the almanac site or refresh other data sites. Do not ask it to do those tasks.

  • Runs scripts and makes network calls
  • Keep FRED_API_KEY and EIA_API_KEY private
  • Refresh writes only to the local US-Common-Metrics dataset

Tips for getting reliable results

Ask for a freshness check before relying on a current number, because sources publish on their own schedules. When you quote a figure, keep the period and publisher with it. Treat the output as a starting point for your own verification.

The skill is not designed for personal finance or investment decisions, and its figures are national aggregates.

  • Run a freshness check before you publish a number
  • Quote the period and publisher with every figure
  • Use the 10y, 5y, 2y and 1y views together to avoid reading one short window

What people use it for

  • Checking whether US violent crime or wages have improved over several decades
  • Getting a 10y, 5y, 2y and 1y overview of current GDP, inflation and unemployment
  • Comparing gas prices and mortgage rates over the last year with publisher named
  • Checking whether the local US-Common-Metrics data is fresh before writing about it

Frequently asked questions

How do I install the USStats agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.

What does USStats require to run?

It requires the Bun runtime, a FRED API key (FRED_API_KEY), an EIA API key (EIA_API_KEY) for gas price data, and a configured almanac endpoint set by data_url in Config.md or USSTATS_DATA_URL.

Is USStats free to use?

The skill is published under the MIT licence. The data it reads is public-domain government and published survey data, and each series names its publisher. Check the skill's own licence file for terms.

Why does the skill need a FRED API key?

FRED is the source for most of the current indicators, so the live side of the skill needs the key to fetch them. EIA's key is needed for gas price data. Without them, the affected metrics are reported as missing rather than hidden.

What should I do if the data looks out of date?

Ask the agent to check freshness, which compares the local dataset with its upstream sources, then refresh the US-Common-Metrics data if needed. Figures marked preliminary or stale should not be presented as final.

How does USStats compare with asking a chatbot about the economy?

USStats pulls figures from FRED, EIA and Treasury data at query time and names each publisher, rather than relying on recalled numbers. It is narrower than a general assistant: it is not for personal finance, investments or health surveillance.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

USStats suits analysts, students and journalists who want US trend data from official sources without manual downloads, and who are comfortable installing a script-based skill with API keys. If you need personal finance or investment advice, pathogen or health surveillance, or work on publishing other data sites, pick a different tool.

Download the skill