What the skill tells Claude

This is the skill's instruction file, SKILL.md, as Claude reads it.

Access comprehensive U.S. and international economic data from the Federal Reserve Economic Data (FRED) database via the FRED API.

What This Skill Does

This skill enables you to:

  • Retrieve economic indicators: GDP, inflation, unemployment, interest rates, stock indices, and more
  • Access time series data: Get historical observations with custom date ranges
  • Search for series: Find economic data by keywords or tags
  • Transform data: Apply percent changes, year-over-year comparisons, and frequency conversions
  • Explore categories: Browse the FRED taxonomy to discover related datasets
  • Get metadata: Access series descriptions, sources, releases, and tags

When To Use This Skill

Use this skill when you need:

  • Current or historical economic indicators for analysis or reporting
  • Macroeconomic data for financial modeling or forecasting
  • Comparison of multiple economic metrics over time
  • Data for charts, visualizations, or economic dashboards
  • Information about economic releases, sources, or data categories

Prerequisites

API KEY REQUIRED: This skill does not ship with an API key. Get a free key at https://fredaccount.stlouisfed.org/apikeys and set it as the FRED_API_KEY environment variable (or pass api_key=... to FREDClient). If no key is available, ask the user for one before making any call.

  • The client reads FRED_API_KEY from the environment by default
  • Alternatively, pass the key explicitly: FREDClient(api_key='...')
  • Never hardcode or print the key

Invocation

The user triggers this skill by mentioning economic data or FRED-related requests:

Get the latest GDP data
Show me unemployment rates for the past year
What's the current inflation rate?
Search FRED for housing price data
Get Federal Funds Rate history from 2020 to 2024

Or explicitly with FRED references:

/fred Get GDP growth rate
Use FRED to find consumer sentiment data
Query the Federal Reserve database for interest rates

Workflow

1. Initialize the Client

When a FRED-related request is detected:

  1. Initialize the FREDClient using the Python script in scripts/fred_client.py
  2. The client reads the key from the FRED_API_KEY environment variable
  3. Users may instead pass their own key explicitly
from scripts.fred_client import FREDClient

# Initialize (reads FRED_API_KEY from the environment)
client = FREDClient()

# Or optionally with a custom API key
# client = FREDClient(api_key='custom_api_key')

2. Determine the Data Request

Based on the user's query, identify:

  • Specific indicator: GDP, unemployment, inflation, etc.
  • Date range: Start and end dates for observations
  • Data transformation: Units (levels, percent change, year-over-year)
  • Frequency: Daily, weekly, monthly, quarterly, annual
  • Search query: Keywords if the user wants to find series

3. Retrieve Data

Use the appropriate FREDClient method:

For specific indicators (use helper methods):

# GDP data
gdp_data = client.get_gdp(
    observation_start='2020-01-01',
    observation_end='2024-01-01',
    units='pc1'  # Percent change from year ago
)

# Unemployment rate
unemployment = client.get_unemployment_rate(
    observation_start='2023-01-01'
)

# Inflation (CPI)
inflation = client.get_inflation(
    observation_start='2023-01-01',
    units='pc1'  # Year-over-year percent change
)

# Federal Funds Rate
fed_funds = client.get_federal_funds_rate(
    observation_start='2023-01-01'
)

For any series by ID:

# Get series observations by series ID
data = client.get_series_observations(
    series_id='SERIES_ID',
    observation_start='2020-01-01',
    observation_end='2024-01-01',
    units='lin',  # Linear/levels
    frequency='m'  # Monthly
)

For searching series:

# Search for series
results = client.search_series(
    search_text='housing prices',
    limit=10
)

4. Process and Present Results

Extract the relevant data from the API response:

# API responses contain 'observations' array
observations = data['observations']

# Each observation has 'date' and 'value'
for obs in observations:
    date = obs['date']
    value = obs['value']

Present the data in a clear, user-friendly format:

  • Tables: For multiple data points
  • Charts: For visualizations (describe or create)
  • Summary: Latest value and key insights
  • Analysis: Trends, changes, comparisons

5. Handle Multiple Indicators

When comparing multiple indicators:

# Retrieve multiple series
gdp = client.get_gdp(observation_start='2023-01-01', units='pc1')
inflation = client.get_inflation(observation_start='2023-01-01', units='pc1')
unemployment = client.get_unemployment_rate(observation_start='2023-01-01')

# Combine and present
indicators = {
    'GDP Growth': gdp['observations'][-1]['value'],
    'Inflation': inflation['observations'][-1]['value'],
    'Unemployment': unemployment['observations'][-1]['value']
}

Data Transformation Options

Units Parameter

Transform data using the units parameter:

  • lin - Levels (no transformation) - DEFAULT
  • chg - Change
  • ch1 - Change from year ago
  • pch - Percent change
  • pc1 - Percent change from year ago
  • pca - Compounded annual rate of change
  • cch - Continuously compounded rate of change
  • cca - Continuously compounded annual rate of change
  • log - Natural log

Most common: - Use lin for raw values (index levels, rates) - Use pc1 for year-over-year percent change (growth rates) - Use pch for period-over-period percent change

Frequency Parameter

Aggregate data to different frequencies:

  • d - Daily
  • w - Weekly
  • bw - Biweekly
  • m - Monthly
  • q - Quarterly
  • sa - Semiannual
  • a - Annual

Common Series IDs

Reference the FRED_SERIES_IDS.md file in references/ for a comprehensive list of frequently used series.

Key indicators: - GDP - Gross Domestic Product - CPIAUCSL - Consumer Price Index (Inflation) - UNRATE - Unemployment Rate - DFF - Federal Funds Effective Rate - SP500 - S&P 500 Index - DGS10 - 10-Year Treasury Rate

See references/fred-ID-parentID-Names.csv for the complete FRED category hierarchy and series IDs.

Available Methods

The FREDClient provides comprehensive API access. Refer to references/FRED_API_METHODS.md for the complete method documentation.

Core methods: - get_series() - Get series metadata - get_series_observations() - Get data values - search_series() - Search for series - get_series_categories() - Get series categories - get_category() - Get category information - get_releases() - Get data releases - get_tags() - Get and search tags

Helper methods for common indicators: - get_gdp() - GDP data - get_inflation() - CPI inflation - get_unemployment_rate() - Unemployment - get_federal_funds_rate() - Fed Funds Rate - get_sp500() - S&P 500 Index - get_10year_treasury() - 10-Year Treasury Rate - get_housing_starts() - Housing Starts - get_retail_sales() - Retail Sales - get_industrial_production() - Industrial Production

Error Handling

Handle common errors gracefully:

try:
    data = client.get_series_observations('SERIES_ID')
except requests.exceptions.HTTPError as e:
    # Handle HTTP errors (404, 400, etc.)
    if e.response.status_code == 400:
        # Invalid series ID or parameters
        pass
except requests.exceptions.RequestException as e:
    # Handle network errors
    pass

Common issues: - Invalid series ID: Suggest using search_series() to find the correct ID - Date format errors: Ensure dates are in YYYY-MM-DD format - API key issues: Verify the API key is valid - Rate limits: FRED has rate limits; space out requests if needed

Output Format

Present data clearly and concisely:

For Single Indicator Queries

GDP Growth Rate (Year-over-Year)
Latest: Q3 2024 = 2.8%

Recent Quarters:
Q3 2024: 2.8%
Q2 2024: 3.0%
Q1 2024: 1.6%
Q4 2023: 3.2%

For Multiple Indicators

Economic Indicators Summary (Latest Values)

GDP Growth:        2.8% (Q3 2024)
Inflation (CPI):   3.2% (Nov 2024)
Unemployment:      3.7% (Nov 2024)
Fed Funds Rate:    5.33% (Dec 2024)

For Time Series Data

Create tables or describe trends:

Federal Funds Rate (2023-2024)

Date       | Rate
-----------|------
2023-01-01 | 4.55
2023-04-01 | 4.83
2023-07-01 | 5.12
2023-10-01 | 5.33
2024-01-01 | 5.33

For Search Results

Series matching "housing prices":

1. CSUSHPISA - S&P/Case-Shiller U.S. National Home Price Index
   Frequency: Monthly | Units: Index

2. MSPUS - Median Sales Price of Houses Sold for the U.S.
   Frequency: Quarterly | Units: Dollars

3. HOSMEDUSM052N - Monthly Supply of Houses in the U.S.
   Frequency: Monthly | Units: Months' Supply

Best Practices

  1. Date Ranges: Default to the most relevant recent period unless specified
  2. Data Freshness: Mention the observation date to show data currency
  3. Context: Provide brief context about what the indicator measures
  4. Comparisons: When appropriate, compare to historical values or benchmarks
  5. Visualizations: Suggest or create charts for time series data
  6. Sources: Credit FRED and cite the series ID for transparency

Constraints

  • API Key Required: Cannot function without a valid FRED API key
  • Data Availability: Some series have limited historical data
  • Release Schedules: Data is updated on specific schedules; latest values may be preliminary
  • Rate Limits: Be mindful of API rate limits for bulk requests
  • Internet Required: Requires active internet connection to access FRED API

Examples

Example 1: Latest GDP Growth

User: "What's the latest GDP growth rate?"

Process: 1. Initialize client with API key 2. Call client.get_gdp(units='pc1', limit=4) for latest quarters 3. Extract and present the most recent value with context

Output:

GDP Growth Rate (Latest)

Q3 2024: 2.8% (year-over-year)

The U.S. economy grew at an annual rate of 2.8% in the third quarter of 2024.

Recent Trend:
Q3 2024: 2.8%
Q2 2024: 3.0%
Q1 2024: 1.6%
Q4 2023: 3.2%

Example 2: Economic Dashboard

User: "Create an economic dashboard with key indicators"

Process: 1. Retrieve multiple indicators: GDP, inflation, unemployment, Fed Funds, S&P 500 2. Get latest values for each 3. Present in a dashboard format

Output:

Economic Dashboard - December 2024

GDP Growth:        2.8%  (Q3 2024, year-over-year)
Inflation (CPI):   3.2%  (Nov 2024, year-over-year)
Unemployment:      3.7%  (Nov 2024)
Fed Funds Rate:    5.33% (effective rate)
S&P 500:          4,783  (latest close)
10-Year Treasury:  4.23% (yield)

Example 3: Historical Analysis

User: "Show me unemployment rates from 2020 to 2024"

Process: 1. Call client.get_unemployment_rate(observation_start='2020-01-01', observation_end='2024-12-31') 2. Process monthly data 3. Highlight key trends (COVID impact, recovery)

Output:

Unemployment Rate (2020-2024)

Peak during COVID-19:
Apr 2020: 14.8% (pandemic peak)

Recent Values (2024):
Nov 2024: 3.7%
Oct 2024: 3.7%
Sep 2024: 3.8%

The unemployment rate has stabilized near historic lows after the sharp increase during the COVID-19 pandemic in 2020.

Example 4: Data Search

User: "Find housing market data on FRED"

Process: 1. Call client.search_series('housing market', limit=10) 2. Present relevant series with descriptions 3. Offer to retrieve specific series data

Output:

Housing Market Data Series on FRED:

1. HOUST - Housing Starts: Total New Privately Owned
   Frequency: Monthly | Units: Thousands

2. CSUSHPISA - S&P/Case-Shiller U.S. National Home Price Index
   Frequency: Monthly | Units: Index (Jan 2000 = 100)

3. MORTGAGE30US - 30-Year Fixed Rate Mortgage Average
   Frequency: Weekly | Units: Percent

4. MSPUS - Median Sales Price of Houses Sold for the U.S.
   Frequency: Quarterly | Units: Dollars

5. PERMIT - New Private Housing Units Authorized by Building Permits
   Frequency: Monthly | Units: Thousands

Would you like to retrieve data from any of these series?

Additional Resources

  • FRED Website: https://fred.stlouisfed.org/
  • API Documentation: https://fred.stlouisfed.org/docs/api/fred/
  • Get API Key: https://fredaccount.stlouisfed.org/apikeys
  • Popular Series: https://fred.stlouisfed.org/tags/series?t=nation

Files in This Skill

  • SKILL.md - This documentation
  • scripts/fred_client.py - FRED API Python client
  • references/FRED_API_METHODS.md - Complete method documentation
  • references/FRED_SERIES_IDS.md - Common series IDs
  • references/fred-ID-parentID-Names.csv - FRED category hierarchy
  • assets/icon.png - Skill icon

Shared as is, with no warranty. Not investment, legal or tax advice. See Disclosures.