npm package: @kampter/claude-skill
Description: Global liquidity quantitative analysis skill for Claude Code - generates trading signals for Gold, Nasdaq, BTC based on Fed liquidity indicators
Author: Kampter
Latest version: 1.2.0

# M2Quant

[![Version](https://img.shields.io/badge/version-1.2.0-blue.svg)](https://github.com/Kampter/M2Quant/releases)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-yellow.svg)](https://python.org)

A Claude Code Skill for Global Liquidity Quantitative Analysis.

## Overview

M2Quant is a quantitative analysis system that tracks global liquidity indicators and generates trading signals for core assets. It analyzes Federal Reserve balance sheet data, Treasury General Account (TGA), and Overnight Reverse Repo (RRP) to quantify money liquidity, then compares against Gold, Nasdaq, and Bitcoin using a "scissors factor" methodology.

## Features

- **Real-time Liquidity Analysis**: Fetches and processes Fed liquidity indicators from FRED
- **Multi-Asset Coverage**: Tracks Gold, Nasdaq, and Bitcoin against liquidity
- **Scissors Factor**: Proprietary metric comparing liquidity growth vs asset price growth
- **Trading Signals**: Generates Buy/Hold/Sell recommendations based on quadrant analysis
- **Professional Reports**: Clean, formatted output for analysis review
- **Standalone Runner**: Execute analysis without Claude Code CLI

## What's New in v1.2.0

- **npm Distribution**: Install via `npm install @m2quant/claude-skill`
- **skills.sh Integration**: One-click installation at [skills.sh](https://skills.sh)
- **Cross-Platform Support**: Auto-installs to Claude Code, Cursor, and Codex agents

See [CHANGELOG.md](CHANGELOG.md) for full details.

## Installation

### Option 1: One-Click Install (Recommended)

Visit [skills.sh](https://skills.sh) and search for `m2quant`.

### Option 2: npm Install

```bash
npm install @m2quant/claude-skill
```

The skill will be automatically installed to your AI agent's skill directory.

### Option 3: Manual Setup

**Prerequisites:**
- Python 3.10+
- [Claude Code](https://github.com/anthropics/claude-code) CLI (optional, for skill usage)
- FRED API key (free from [FRED](https://fred.stlouisfed.org/docs/api/api_key.html))

**Steps:**

1. Clone the repository:
```bash
git clone https://github.com/Kampter/M2Quant.git
cd M2Quant
```

2. Create and activate virtual environment:
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install dependencies:
```bash
pip install -r requirements.txt
```

4. Configure API key:
```bash
cp config/api_keys.example.json config/api_keys.json
# Edit config/api_keys.json with your FRED API key
```

## Usage

### Via Claude Code Skills

```bash
# Full analysis with detailed report
claude /m2quant

# View liquidity conditions only
claude /m2quant liquidity

# View trading signals only
claude /m2quant signal

# Generate complete report
claude /m2quant report
```

### Via Standalone Script

Run analysis directly without Claude Code:

```bash
# Full analysis (default)
python scripts/run_analysis.py

# Liquidity data only
python scripts/run_analysis.py liquidity

# Trading signals only
python scripts/run_analysis.py signal
```

## Data Sources

### Liquidity Indicators (FRED API)
| Series | Description | Frequency |
|--------|-------------|-----------|
| WALCL | Federal Reserve Total Assets | Weekly |
| WTREGEN | Treasury General Account | Weekly |
| RRPONTSYD | Overnight Reverse Repo | Daily |
| M2SL | M2 Money Supply | Monthly |

### Asset Prices (Yahoo Finance)
| Symbol | Description |
|--------|-------------|
| GC=F | Gold Futures |
| ^IXIC | Nasdaq Composite |
| BTC-USD | Bitcoin |

## Core Methodology

### Net Liquidity Formula
```
Net_Liquidity = WALCL - TGA - RRP
```

### Scissors Factor
```
Scissors = Liquidity_YoY% - Asset_Price_YoY%
```

The scissors factor measures the divergence between liquidity growth and asset price appreciation, helping identify over/undervalued conditions.

### Signal Generation

Signals are generated using a weighted composite:
- **Regime Signal (50%)**: Based on liquidity regime and scissors factor
- **Threshold Signal (30%)**: Based on deviation from liquidity-implied value
- **Momentum Signal (20%)**: Based on liquidity vs price momentum divergence

## Project Structure

```
M2Quant/
├── .claude/              # Claude Code configuration
├── skills/               # Claude Code Skills
│   ├── m2quant/          # Main orchestration skill
│   │   ├── SKILL.md      # Skill definition with frontmatter
│   │   ├── reference.md  # Methodology documentation
│   │   └── examples/     # Example outputs
│   ├── fetch-liquidity/  # FRED data fetching
│   ├── fetch-prices/     # Yahoo Finance fetching
│   ├── calculate-factors/
│   ├── generate-signals/
│   └── generate-report/
├── src/                  # Python modules
│   ├── __init__.py       # Version: 1.2.0
│   ├── data_fetcher.py
│   ├── factor_engine.py
│   ├── signal_generator.py
│   └── report_generator.py
├── scripts/              # Standalone scripts
│   └── run_analysis.py   # Direct execution runner
├── config/               # Configuration files
├── data/                 # Data cache (gitignored)
└── reports/              # Generated reports (gitignored)
```

## Configuration

### API Keys (`config/api_keys.json`)
```json
{
  "fred_api_key": "YOUR_FRED_API_KEY"
}
```

### Signal Thresholds (`config/thresholds.json`)
```json
{
  "buy_threshold": -1.5,
  "sell_threshold": 1.5,
  "strong_buy_threshold": -2.0,
  "strong_sell_threshold": 2.0,
  "zscore_window": 60,
  "momentum_window": 20
}
```

## Skill Context Costs

| Command | Context Cost | Use When |
|---------|--------------|----------|
| `/m2quant` | High | Full analysis needed |
| `/m2quant liquidity` | Low | Quick liquidity check |
| `/m2quant signal` | Medium | Just need trading signals |

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Disclaimer

This analysis is for informational purposes only. Not financial advice. Past performance does not guarantee future results.

## Author

Created as a Claude Code Skill for quantitative analysis.