AgentSkillsCN

fred-navigator

利用 fredapi 导航 FRED 数据集类别与系列，支持自然语言查询，并具备意图识别与双重校验功能。

SKILL.md
--- frontmatter
name: fred-navigator
description: Navigate FRED categories and series using fredapi, supporting natural-language queries with intent recognition and double validation.
metadata:
  short-description: FRED navigation and lookup

FRED Navigator

Purpose

Provide a reliable workflow to navigate FRED categories and series, with support for:

  1. •Direct category_id
  2. •Direct series_id
  3. •Natural-language query → intent recognition → double validation

Inputs

  • •category_id: FRED category id
  • •series_id: FRED series id
  • •query: natural language request
  • •limit: number of candidates to return (default 5)
  • •api_key: read from environment FRED_API_KEY only

Required Resources

  • •references/fred_categories_tree.json
  • •references/fred_categories_flat.json
  • •Optional: references/category_paths.json (precomputed)
  • •Optional: references/synonyms.json
  • •Helper script: scripts/fred_query.py
  • •Path builder: scripts/build_paths.py

Optional Resource Structure Notes

  • •references/category_paths.json format:
    • •{ "category_id": { "id": <int>, "name": "<str>", "path": "<str>" }, ... }
  • •references/synonyms.json format:
    • •{ "concept": ["alias1", "alias2", ...], ... }

Workflow

1. Category Exploration

  1. •Load fred_categories_tree.json for hierarchical browsing.
  2. •If user provides category_id, validate it exists.
  3. •If user provides category_name, fuzzy match against flat names and return candidates.

2. Series Discovery

  1. •Use search_by_category(category_id) to list available series.
  2. •Prefer scripts/fred_query.py category <id> for consistent output.
  3. •Return key columns:
    • •id, title, frequency, units, seasonal_adjustment, last_updated.

3. Series Retrieval

  1. •Use get_series(series_id) for time series.
  2. •Use get_series_info(series_id) for metadata.
  3. •Prefer scripts/fred_query.py series <id> and scripts/fred_query.py series-info <id>.
  4. •Provide:
    • •data head/tail
    • •missing counts
    • •latest value and date

4. Natural Language Query

4.1 Intent Identification (Top-K)

  1. •Use the IDE agent (Codex) to interpret the natural-language intent.
  2. •Select the single best-matching category.
  3. •If confidence is low, ask the user to confirm the category before proceeding.
  4. •Use references/category_paths.json and references/synonyms.json as supporting context if available.

4.2 Double Validation

Structural validation

  • •Candidate must exist in fred_categories_tree.json.
  • •Pass if at least one:
    • •children non-empty
    • •search_by_category(id) returns >= 1 series
    • •Prefer scripts/fred_query.py check-category <id> for a quick check

Semantic validation (agent)

  • •Compare query with candidate name/path.
  • •Return pass/fail or numeric relevance score.

4.3 Decision

  • •If structural + semantic validation both pass → accept category.
  • •Otherwise:
    • •return Top-5 candidates
    • •ask user to choose one explicitly

Failure Handling

  • •Always provide Top-5 candidates when uncertain.
  • •Never proceed to series retrieval if category validation fails.

Notes

  • •Do not hardcode API keys.
  • •Keep heavy reference data in references/, not in this file.
  • •When running Python functions for querying, execute them inside the sandbox environment.

Maintenance

  • •Update workflow or constraints: edit SKILL.md.
  • •Update category data: replace files in references/.
  • •Improve natural-language matching: add or edit references/synonyms.json (key → list of related terms).
  • •Regenerate precomputed paths (optional): run scripts/build_paths.py.
  • •Add helper scripts (optional): place in scripts/ and document usage here.