> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doomberg.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills Overview

> Skills are archive-backed data tools and computed analytics exposed to AI agents over MCP. Learn what they are, how they differ from direct tools, and how to discover them.

## What skills are

A **skill** is a named, self-describing data or analytics capability that an AI agent can invoke through the Ithaca MCP server. Skills come in two flavors:

* **Archive-backed skills** read from the Ithaca data archive — a curated, versioned store of market data, fundamentals, congressional trades, insider filings, sentiment, macro indicators, and more. Each result ships with a **provenance envelope** so the agent (and the human watching the trace) always knows where the data came from and how fresh it is.
* **Computed analytics skills** run trusted numpy/pandas code on archive closes or agent-supplied inputs. They produce derived metrics — volatility, options greeks, correlations, factor exposures, DCF valuations, Monte Carlo paths — without ever executing agent-authored code.

<Callout type="info">
  Skills are **read-only research tools**. They cannot place orders, modify strategies, or touch the money path. Anything that affects capital goes through the approval-gated tools documented in [MCP Tools](/tools/overview).
</Callout>

## Skills vs. direct MCP tools

Ithaca exposes two layers of tools to agents:

| Layer                | What it is                                                                           | Example                                               | Provenance envelope        | Runtime budget       |
| -------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------- | -------------------------- | -------------------- |
| **Direct MCP tools** | Core platform operations — sessions, strategy specs, backtests, approvals, artifacts | `session_context`, `propose_strategy`, `backtest_run` | No (operational, not data) | Varies by tool       |
| **Skills**           | Data retrieval + computed analytics over the archive                                 | `market.quote`, `vol.iv_rank`, `congress.trades`      | **Yes** — every result     | One of four profiles |

Direct tools drive the workflow. Skills feed it with trusted data and derived metrics. An agent typically opens a session with a direct tool, then calls dozens of skills to research a ticker, and finally hands the findings back to a direct tool (`propose_strategy`) to act.

<Tip>
  If a capability exists as a skill, prefer the skill over scraping the web or reasoning from memory. Skills are sourced, fresh, and traceable — agent memory is not.
</Tip>

## The provenance envelope

Every archive-backed skill returns its payload wrapped in a **provenance envelope**. This is what makes Ithaca data trustworthy inside an agent trace: the human can inspect exactly where each number came from.

```json theme={null}
{
  "skill_id": "market.quote",
  "data": { "symbol": "NVDA", "price": 128.42, "change_pct": 1.83 },
  "provenance": {
    "source": "ibkr",
    "freshness": { "as_of": "2025-06-27T20:00:00Z", "lag_seconds": 15 },
    "coverage": { "start": "2025-06-27T09:30:00Z", "end": "2025-06-27T16:00:00Z" },
    "cost": { "credits": 1, "tier": "free" },
    "warnings": []
  }
}
```

| Field                    | Type          | Description                                                                                                    |
| ------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------- |
| `source`                 | string        | Origin of the data — `archive-community`, `ibkr`, `sec`, `capitol-trades`, `quiver`, `fmp`, `fred`, `computed` |
| `freshness.as_of`        | ISO timestamp | When the underlying record was last refreshed                                                                  |
| `freshness.lag_seconds`  | int           | Wall-clock lag between `as_of` and the most recent source update                                               |
| `coverage.start` / `end` | ISO timestamp | Time range the result covers                                                                                   |
| `cost.credits`           | int           | Credit cost charged to the tenant for this call                                                                |
| `cost.tier`              | string        | `free`, `basic`, `pro`, `enterprise`                                                                           |
| `warnings`               | string\[]     | Non-fatal caveats — stale data, partial coverage, interpolated values, etc.                                    |

<Callout type="warn">
  Always check `warnings` before acting on a result. A non-empty array means the data is usable but imperfect — for example, a congressional trade filed 90 days late, or a volatility series computed from fewer than 30 closes.
</Callout>

## Runtime profiles

Every skill runs under one of four **runtime profiles** — a hard wall-clock budget that keeps agent sessions responsive and prevents runaway computations.

| Profile        | Budget   | Typical use                                           | Example skills                                           |
| -------------- | -------- | ----------------------------------------------------- | -------------------------------------------------------- |
| `interactive`  | 120 s    | Single-ticker lookups during a live research session  | `market.quote`, `congress.trades`, `vol.iv_rank`         |
| `scan`         | 900 s    | Universe-wide screens and multi-ticker pulls          | `market.screener`, `congress.screener`, `short.screener` |
| `backtest`     | 7,200 s  | Historical replay over years of closes                | `walkforward.run`, `seasonality.heatmap`                 |
| `optimization` | 14,400 s | Parameter sweeps, Monte Carlo, portfolio optimization | `portfolio.optimize`, `montecarlo.simulate`              |

If a skill exceeds its budget it returns a `timeout` warning in the provenance envelope and a partial result (where possible). The agent can then narrow its request or switch to a longer profile explicitly.

## How to discover skills

Agents discover skills the same way humans do — by asking the catalog.

```
search_skills(query: "volatility", limit: 10)
```

`search_skills` is a direct MCP tool (see [Tools overview](/tools/overview)) that returns matching skill descriptors:

```json theme={null}
{
  "query": "volatility",
  "matches": [
    {
      "skill_id": "vol.realized",
      "category": "volatility",
      "description": "Annualized realized volatility from archive closes",
      "runtime_profile": "interactive",
      "cost": { "credits": 1, "tier": "free" }
    },
    { "skill_id": "vol.iv_rank", "category": "volatility", "..." : "..." }
  ]
}
```

Each descriptor contains `skill_id`, `category`, `description`, `runtime_profile`, and `cost` — enough for the agent to pick the right skill and predict its budget without a full call.

## Skill catalog

Ithaca ships **50+ skills** across nine categories. Use the table below as a map; each category links to a dedicated reference page.

### Market data

| Skill ID          | Source            | Description                                                    |
| ----------------- | ----------------- | -------------------------------------------------------------- |
| `market.news`     | archive-community | News headlines + sentiment for a ticker or topic               |
| `market.screener` | archive-community | Multi-filter universe screen                                   |
| `market.movers`   | archive-community | Top gainers/losers/most-active by exchange                     |
| `market.quote`    | ibkr              | Real-time or delayed quote                                     |
| `market.tide`     | archive-community | Aggregate market breadth (advancers/decliners, new highs/lows) |

### Fundamentals

| Skill ID               | Source            | Description                                    |
| ---------------------- | ----------------- | ---------------------------------------------- |
| `fundamentals.get`     | fmp               | Full fundamentals snapshot for a ticker        |
| `fundamentals.compare` | fmp               | Side-by-side fundamentals for multiple tickers |
| `fundamentals.pit`     | sec               | Point-in-time fundamentals as of a date        |
| `analyst.ratings`      | archive-community | Analyst ratings + price targets                |

### Congress & insider

| Skill ID                | Source         | Description                                           |
| ----------------------- | -------------- | ----------------------------------------------------- |
| `congress.trades`       | capitol-trades | Individual congressional trade filings                |
| `congress.late_filings` | capitol-trades | Trades filed past the STOCK Act deadline              |
| `congress.screener`     | capitol-trades | Filter congressional trades by ticker/party/committee |
| `insider.activity`      | sec            | Form 4 insider buys/sells                             |
| `politician.portfolio`  | capitol-trades | Aggregated holdings for a single politician           |

### Institutional & ETF

| Skill ID                 | Source            | Description                                   |
| ------------------------ | ----------------- | --------------------------------------------- |
| `institutional.holdings` | sec               | 13F institutional holdings                    |
| `institutional.flows`    | archive-community | Net inflows/outflows by institution or ticker |
| `etf.holdings`           | archive-community | ETF constituent list with weights             |
| `etf.exposure`           | archive-community | Factor/sector exposure of an ETF              |

### Sentiment & macro

| Skill ID             | Source            | Description                                          |
| -------------------- | ----------------- | ---------------------------------------------------- |
| `sentiment.get`      | archive-community | News/social sentiment score for a ticker             |
| `macro.dashboard`    | fred              | Macro indicator dashboard (CPI, rates, unemployment) |
| `universe.list`      | archive-community | Predefined universes (S\&P 500, Russell 2000, etc.)  |
| `economic.calendar`  | archive-community | Upcoming economic releases                           |
| `fda.calendar`       | archive-community | FDA approval dates (biotech catalysts)               |
| `commodity.prices`   | archive-community | Spot + futures for commodities                       |
| `forex.rates`        | archive-community | FX spot rates                                        |
| `crypto.prices`      | archive-community | Crypto spot + 24h volume                             |
| `vix.term_structure` | archive-community | VIX futures curve by maturity                        |

### Volatility (computed)

| Skill ID             | Source   | Description                                 |
| -------------------- | -------- | ------------------------------------------- |
| `vol.realized`       | computed | Annualized realized vol from archive closes |
| `vol.term_structure` | computed | IV term structure by expiry                 |
| `vol.iv_rank`        | computed | IV rank and percentile                      |
| `vol.vrp`            | computed | Variance risk premium (IV − RV)             |
| `vol.anomaly_score`  | computed | Z-score of current vol vs. history          |
| `vol.character`      | computed | Vol regime classification                   |

### Options (computed)

| Skill ID              | Source   | Description                                      |
| --------------------- | -------- | ------------------------------------------------ |
| `options.greeks`      | computed | Black-Scholes price + delta/gamma/vega/theta/rho |
| `options.implied_vol` | computed | BS implied vol from observed option price        |

### Computed analytics

| Skill ID               | Source   | Description                                            |
| ---------------------- | -------- | ------------------------------------------------------ |
| `correlation.matrix`   | computed | Rolling correlation matrix for a ticker set            |
| `factor.exposures`     | computed | Style factor loadings (momentum, value, quality, etc.) |
| `dcf.value`            | computed | Discounted cash flow valuation                         |
| `portfolio.optimize`   | computed | Mean-variance / risk-parity optimization               |
| `montecarlo.simulate`  | computed | Path simulation for a portfolio or strategy            |
| `scenario.project`     | computed | Project returns under a named scenario                 |
| `risk.stress`          | computed | Stress-test P\&L under historical shocks               |
| `tearsheet`            | computed | Full performance tearsheet (returns, drawdown, ratios) |
| `walkforward.run`      | computed | Walk-forward optimization over a strategy spec         |
| `technical.indicators` | computed | RSI, MACD, ATR, Bollinger, etc. from closes            |
| `seasonality.monthly`  | computed | Average monthly returns over N years                   |
| `seasonality.heatmap`  | computed | Day/month return heatmap                               |

### Financials & earnings

| Skill ID              | Source            | Description                           |
| --------------------- | ----------------- | ------------------------------------- |
| `financials.income`   | fmp               | Income statement (annual + quarterly) |
| `financials.balance`  | fmp               | Balance sheet                         |
| `financials.cashflow` | fmp               | Cash flow statement                   |
| `earnings.transcript` | archive-community | Earnings call transcript              |
| `earnings.calendar`   | archive-community | Upcoming earnings dates               |
| `dividends`           | archive-community | Dividend history + yield              |
| `stock.splits`        | archive-community | Split history                         |

### Short interest

| Skill ID         | Source            | Description                              |
| ---------------- | ----------------- | ---------------------------------------- |
| `short.interest` | archive-community | Short interest + days to cover           |
| `short.volume`   | archive-community | Daily short volume ratio                 |
| `short.ftd`      | sec               | Failures to deliver (Reg SHO)            |
| `short.screener` | archive-community | Screen tickers by short interest metrics |

## Next steps

<Card title="Market Data Skills" icon="chart-line" href="/skills/market-data">
  Quotes, screeners, movers, news, and market breadth.
</Card>

<Card title="Volatility Skills" icon="wave-square" href="/skills/volatility">
  Realized vol, IV rank, variance risk premium, and regime classification — all computed from archive closes.
</Card>

<Card title="Computed Analytics Skills" icon="calculator" href="/skills/computed">
  Correlations, factor exposures, DCF, portfolio optimization, Monte Carlo, tearsheets, and walk-forward.
</Card>

<Card title="MCP Tools" icon="wrench" href="/tools/overview">
  The direct tools that drive sessions, strategies, backtests, and approvals.
</Card>