EODHD Claude Skills

Overview

Plugin enabling AI agents (Claude Code, Codex) to work with the EODHD financial data API. Distributed as a Claude Code plugin (EodHistoricalData/eodhd-claude-skills). Version: 0.5.2.

Includes MCP Server connector (OAuth), 13 skills (1 core + 7 workflow + 5 user-facing commands), financial analyst agent, 64 endpoint docs, 28 general guides, and a stdlib-only Python client. As of v0.5.2 the user commands (eodhd-analyze etc.) live under skills/ as standard skills and are invoked namespaced (e.g. /eodhd-api:eodhd-analyze) — the legacy commands/ directory was removed because its flat files did not load as usable commands in a live session on newer Claude Code (verified live on 2.1.158 and 2.1.161: all 13 skills load).

File Structure

.claude-plugin/
  marketplace.json              # Plugin manifest (name, version, skills list)
  plugin.json                   # Extended plugin metadata (keywords, author, license)
.mcp.json                       # MCP Server connector → mcp.eodhd.com/v2/mcp
agents/
  financial-analyst.md          # Financial analyst agent definition
skills/                         # All skills incl. user commands (auto-discovered)
  eodhd-analyze/SKILL.md        # /eodhd-api:eodhd-analyze <ticker>
  eodhd-compare/SKILL.md        # /eodhd-api:eodhd-compare <ticker1> <ticker2>
  eodhd-market/SKILL.md         # /eodhd-market
  eodhd-screen/SKILL.md         # /eodhd-screen <criteria>
  eodhd-macro/SKILL.md          # /eodhd-macro
  eodhd-api/                    # Core skill — full API access (30+ client endpoints)
    SKILL.md
    references/
      general/                  # 28 general guides
      endpoints/                # 64 endpoint docs
      subscriptions/            # 7 subscription plans
      workflows.md              # 4 analysis patterns
    scripts/
      eodhd_client.py           # Python client (stdlib-only, ~495 lines)
      market_cap_series.py
      test_investverte_*.py
    templates/
      analysis_report.md
  company-brief/SKILL.md        # Company snapshot workflow
  earnings-monitor/SKILL.md     # Earnings tracking workflow
  market-overview/SKILL.md      # Market summary workflow
  portfolio-risk/SKILL.md       # Risk analysis workflow
  stock-screener/SKILL.md       # Stock screening workflow
  macro-dashboard/SKILL.md      # Macro-economic dashboard
  options-analyzer/SKILL.md     # Options analysis workflow
adapters/
  claude/eodhd-api.md
  codex/eodhd-api.md
registry/
  capabilities.json             # Single source of truth for all endpoints (67 entries)
  build.py                      # Generates support-matrix.md; --check for CI freshness
  README.md                     # Registry schema + workflow

Key Components

Development Setup

1. Clone: git clone https://github.com/EodHistoricalData/eodhd-claude-skills.git
2. Set token: export EODHD_API_TOKEN="your_token_here"
3. Test client: python skills/eodhd-api/scripts/eodhd_client.py --endpoint exchanges-list

Or install as Claude Code plugin:

/plugin marketplace add EodHistoricalData/eodhd-claude-skills
/plugin install eodhd-api@eodhd-claude-skills

Testing

python skills/eodhd-api/scripts/eodhd_client.py --endpoint exchanges-list
python skills/eodhd-api/scripts/eodhd_client.py --endpoint eod --symbol AAPL.US --from-date 2025-01-01 --to-date 2025-01-31

Automated tests live in tests/ (stdlib-only, no pytest dependency):

• tests/test_python_client.py — 30 e2e cases hitting every endpoint in SUPPORTED_ENDPOINTS against the live API. Requires EODHD_API_TOKEN.
• tests/test_mcp_v1.py — MCP protocol e2e: v2 OAuth challenge, v1 initialize/tools-list/tools-call.
• tests/test_skill_references.py — static cross-reference validation (SKILL.md frontmatter, endpoint docs, slash commands, agent frontmatter, manifest tool count vs MCP).
• tests/test_registry.py — static parity: registry ↔ client SUPPORTED_ENDPOINTS, registry ↔ endpoint docs, validated-tier ↔ e2e cases, and support-matrix freshness. Stdlib-only, runs in CI.

CI (.github/workflows/validate.yml) runs the static suite on every push/PR. The two e2e suites run automatically when EODHD_API_TOKEN is configured as a GitHub Actions secret; otherwise the e2e job emits a skip warning and the CI passes (no false negatives).

Deployment

No runtime deployment. Distributed via GitHub releases.

• Version bumps: edit version in .claude-plugin/marketplace.json and .claude-plugin/plugin.json
• Auto-release: .github/workflows/release.yml triggers on version bump
• Users install/update via Claude Code plugin system

Conventions

Documentation

• Endpoint docs follow standard template: Purpose, Parameters, Response, Examples, Notes
• exchanges.md = source of truth for exchange codes
• symbol-format.md = source of truth for ticker formatting

Python Client

• eodhd_client.py is stdlib-only — no external packages
• Token from EODHD_API_TOKEN env var
• JSON stdout, exit codes: 0=success, 1=API error, 2=client error

Skills

• Each workflow skill has YAML frontmatter (name, description, version)
• Skills reference endpoints from ../eodhd-api/references/endpoints/
• Skills include output structure templates and endpoint cost tables

Git

• Main branch: main
• Commit style: imperative, descriptive
• Version in marketplace.json and plugin.json must stay in sync

Related

• GitHub: https://github.com/EodHistoricalData/eodhd-claude-skills
• EODHD API: https://eodhd.com/financial-apis/
• MCP Server: https://mcp.eodhd.com/v2/mcp