Maia Skill

<a id="top"></a>

<p align="center"> <img src="docs/images/hero.png" alt="MAIA — five AI research agents converging into a market analysis dashboard" width="100%"> </p> <h1 align="center">MAIA System</h1> <p align="center"> <strong>M</strong>ulti-<strong>A</strong>gent <strong>I</strong>nvestment <strong>A</strong>nalysis — for Claude Code<br> Five specialized AI agents research crypto, stocks, forex &amp; commodities in parallel, adapt to your risk profile, and render an interactive, bilingual dashboard — <em>educational analysis, not financial advice.</em> </p> <p align="center"> <img alt="version 2.1.0" src="https://img.shields.io/badge/version-2.1.0-3a8c1a"> <img alt="Claude Code skill" src="https://img.shields.io/badge/Claude%20Code-skill-3a8c1a"> <img alt="Next.js 16" src="https://img.shields.io/badge/Next.js-16-111111"> <img alt="TypeScript strict" src="https://img.shields.io/badge/TypeScript-strict-111111"> <img alt="license MIT" src="https://img.shields.io/badge/license-MIT-3a8c1a"> <img alt="EN / ES bilingual" src="https://img.shields.io/badge/EN%20%2F%20ES-bilingual-111111"> </p> <p align="center"><strong><a href="#espanol">Leer en Español ↓</a></strong> · by tododeia · <a href="https://github.com/Hainrixz">@soyenriquerocha</a></p>

---

What's new in v2.1 — hybrid keyless market-data APIs (CoinGecko · Yahoo Finance · Frankfurter) with optional premium keys, an educational acknowledgment gate, a security-hardened dashboard (CSP + XSS-safe HTML fallback), full accessibility (ARIA, keyboard nav, reduced-motion), a numeric data contract validated in CI, and portable runs from any directory. See the CHANGELOG.

---

What Is This?

MAIA is a Claude Code skill — a reusable prompt-and-tooling package that extends what Claude can do. When installed, Claude gains the ability to run a full multi-agent investment research workflow: 4 sector analysts research in parallel, a strategy agent synthesizes everything, and the result is served as an interactive dashboard in your browser.

How It Works

                         ┌──────────────┐
                    ┌────┤  You trigger  ├────┐
                    │    │  "analyze     │    │
                    │    │   markets"    │    │
                    │    └──────────────┘    │
                    ▼                        ▼
            ┌──────────────┐        ┌──────────────┐
            │ Risk Profile │        │ Load History  │
            │   Question   │        │  (if exists)  │
            └──────┬───────┘        └──────┬───────┘
                   │                       │
                   ▼                       │
    ┌──────────────────────────────┐       │
    │     4 Sector Agents          │       │
    │  (parallel web research)     │       │
    │                              │       │
    │  ┌───────┐  ┌───────┐       │       │
    │  │Crypto │  │Stocks │       │       │
    │  └───────┘  └───────┘       │       │
    │  ┌───────┐  ┌──────────┐   │       │
    │  │ Forex │  │Materials │   │       │
    │  └───────┘  └──────────┘   │       │
    └──────────────┬───────────────┘       │
                   │                       │
                   ▼                       ▼
          ┌────────────────────────────────────┐
          │        Strategy Agent               │
          │  (cross-sector analysis,            │
          │   risk-adjusted ranking,            │
          │   portfolio allocation,             │
          │   historical accuracy check)        │
          └────────────────┬───────────────────┘
                           │
                    ┌──────┴──────┐
                    ▼             ▼
            ┌────────────┐ ┌────────────┐
            │ report.json│ │report-es   │
            │ (English)  │ │  .json     │
            └──────┬─────┘ └──────┬─────┘
                   │              │
                   ▼              ▼
              ┌──────────────────────┐
              │   Next.js Dashboard  │
              │   localhost:3420     │
              │   EN / ES toggle    │
              └──────────────────────┘

Features

<p align="center"> <img src="docs/images/dashboard.png" alt="The MAIA dashboard: allocation donut, recommendation cards, performance and risk-analysis charts" width="100%"> </p>

• 5 AI agents — 4 sector researchers + 1 strategy synthesizer, running in parallel
• Hybrid market data — authoritative prices from free keyless APIs (CoinGecko, Yahoo Finance, Frankfurter) with a deterministic fallback ladder; WebSearch adds news & sentiment. Optional FINNHUB_API_KEY / POLYGON_API_KEY for premium stock data
• Dynamic asset discovery — agents find the most relevant assets for current conditions instead of a fixed list
• Risk profiles — conservative / moderate / aggressive reshape scoring, illustrative position sizes, and allocation
• Cross-sector strategy — a synthesis agent surfaces correlations and divergences individual agents can't see
• Historical accuracy tracking — compares prior signals to outcomes over time (a local heuristic, not an audited record)
• Interactive dashboard — allocation donut, risk-vs-confidence and social-buzz charts, expandable per-asset tables, top-picks grid
• Fully bilingual (EN/ES) — UI and report data translate on toggle; numbers, tickers and prices stay intact
• Educational-first compliance — a one-time "not financial advice" gate before the report; analytical Consider / Hold / Avoid language instead of buy/sell
• Accessible — ARIA-labeled charts, keyboard-navigable cards & sortable tables, focus-visible rings, prefers-reduced-motion
• Secure & private — Content-Security-Policy + security headers; XSS-hardened HTML fallback; runs locally with data kept in ~/.claude/cache/tododeia
• Portable — resolves its own install directory and writes to a writable cache, so it works from any folder
• Scheduling — optional daily or weekly recurring reports

Sectors Covered

| Sector | Always Includes | Dynamically Discovers | |--------|----------------|----------------------| | Crypto | BTC, ETH | Trending altcoins, DeFi tokens, AI tokens | | Stocks | S&P 500, NASDAQ | Top movers, catalyst-driven stocks across sectors | | Forex | DXY, USD/MXN | Pairs affected by current events | | Commodities | Gold, Oil WTI | Agricultural, energy, metals based on market conditions |

Requirements

• Claude Code (CLI)
• Node.js 18+ for the interactive dashboard — optional; without it the skill renders a standalone HTML report (served with python3)
• An internet connection (agents fetch live prices and do web research)
• Optional: FINNHUB_API_KEY or POLYGON_API_KEY for premium stock data — free keyless sources are used by default

Installation

Option A: One-liner (fastest)

curl -sL https://raw.githubusercontent.com/Hainrixz/maia-skill/main/install.sh | bash

This clones the repo, symlinks the skill into Claude Code, and installs dashboard dependencies automatically.

Option B: Claude Code plugin

claude plugin install Hainrixz/maia-skill

Option C: Manual setup

# 1. Clone the repo
git clone https://github.com/Hainrixz/maia-skill.git

# 2. Symlink skill into Claude Code
mkdir -p ~/.claude/skills
ln -s "$(pwd)/maia-skill/.claude/skills/investment-analysis" ~/.claude/skills/investment-analysis

# 3. Install dashboard dependencies
npm install --prefix maia-skill/dashboard

The skill auto-activates when you mention investment-related topics in Claude Code.

Usage

In any Claude Code conversation:

• "Run an investment analysis"
• "What are the best investment opportunities today?"
• "Analyze the markets"
• "Give me a market report"
• "Run tododeia"

You'll be asked your risk profile (conservative, moderate, or aggressive), then the 5 agents go to work. The report opens at http://localhost:3420. On first open you'll acknowledge a short educational, not advice notice and pick a language. Generated reports are written to ~/.claude/cache/tododeia — not your current project folder.

Language Toggle

<p align="center"> <img src="docs/images/bilingual.png" alt="Full English / Spanish bilingual support" width="46%"> </p>

When you first open the dashboard, you'll be asked to pick English or Spanish. All report content — summaries, reasoning, news headlines, insights, warnings — translates to your chosen language. Numbers, prices, tickers, and percentages stay as-is. If a Spanish report isn't available yet, the dashboard shows English with a small notice instead of failing.

You can switch languages anytime from the toolbar.

Scheduling (Optional)

After your first report, you can set up recurring analysis:

/loop 24h /investment-analysis    # Daily reports
/loop 168h /investment-analysis   # Weekly reports

Project Structure

.claude/skills/investment-analysis/
  SKILL.md              # Skill definition (orchestrator instructions)
  assets/
    template.html       # Fallback HTML report (no Node.js)
  references/
    agent-prompts.md    # Prompts for all 5 agents
  dashboard/            # Next.js interactive dashboard
    src/
      app/              # App router pages
      components/       # Report UI components
      hooks/            # Language + data hooks
      lib/              # Translations, constants
      types/            # TypeScript types
    public/data/        # Sample report JSON (demo fixtures; live runs write to ~/.claude/cache/tododeia)
    schema/             # JSON Schema for the report data contract (CI-validated)

Customization

Assets & Agent Behavior

Edit references/agent-prompts.md to change which assets each agent researches, how they search, or what data they prioritize.

Risk Profiles

The Strategy Agent prompt in references/agent-prompts.md defines how each risk profile affects scorin