Trading Skills Library

The @liquidityio/skills package provides pre-built trading capabilities that compose on top of MCP tools. While MCP tools are atomic operations (get a quote, place an order), skills are higher-level workflows that chain multiple tool calls together with domain logic.

Skills are designed for use with Claude Code as slash commands. When you type /analyze BTC-USD or /rebalance, the AI agent loads the skill definition, executes the required tool calls, applies the embedded logic, and returns a structured result.

Installation

npm install -g @liquidityio/skills

Skills are registered automatically when the MCP server starts. They appear as slash commands in Claude Code.

Available Skills

Market Analysis (/analyze)

Produces a structured market report for any tradeable instrument. Combines orderbook depth, recent trades, price levels, and volume profile into an actionable summary.

Usage:

/analyze BTC-USD
/analyze AAPL --timeframe 1h
/analyze ETH-USD --depth full

What it does:

1. Calls get_quote for current bid/ask/last
2. Calls get_orderbook with full depth
3. Calls get_trades for the last 100 trades
4. Computes: spread (bps), VWAP, volume-weighted midpoint, support/resistance levels, trade flow imbalance
5. Returns a formatted analysis with actionable context

Example output:

BTC-USD Market Analysis
━━━━━━━━━━━━━━━━━━━━━━
Price:     $84,252.00 (ask) / $84,248.00 (bid)
Spread:    $4.00 (0.47 bps)
VWAP:      $84,190.35 (100 trades)
Volume:    142.5 BTC in last 100 trades

Orderbook Depth (5 levels):
  Bids: 8.2 BTC ($692,400)
  Asks: 6.8 BTC ($573,100)
  Imbalance: +17% bid-heavy

Support: $84,000 (2.1 BTC stacked)
Resistance: $84,500 (1.8 BTC offered)

Trade Flow: 58% buys / 42% sells (last 100)

Portfolio Rebalancing (/rebalance)

Calculates and optionally executes a rebalance to target allocations. Supports fixed-weight, risk-parity, and market-cap-weighted strategies.

Usage:

/rebalance --target '{"BTC": 0.4, "ETH": 0.3, "USD": 0.3}'
/rebalance --strategy risk-parity
/rebalance --dry-run

What it does:

1. Calls get_portfolio for current holdings
2. Calls get_quote for each asset to calculate current USD values
3. Computes target vs. actual allocation
4. Generates a trade list (buys and sells) to reach target weights
5. Applies minimum trade size filters and fee estimation
6. In --dry-run mode: shows the plan without executing
7. In live mode: executes trades sequentially via place_order

Example output (dry run):

Rebalance Plan (dry run)
━━━━━━━━━━━━━━━━━━━━━━━
Current portfolio value: $500,000.00

Asset   Current   Target    Delta        Action
BTC     45.2%     40.0%     -5.2%        SELL 0.031 BTC ($2,600)
ETH     22.1%     30.0%     +7.9%        BUY  12.4 ETH ($39,500)
USD     32.7%     30.0%     -2.7%        (deploy $36,900 to ETH)

Estimated fees: $78.40
Orders: 2

Risk Assessment (/risk)

Evaluates portfolio risk metrics and flags concentration, correlation, and drawdown exposure.

Usage:

/risk
/risk --var 0.95
/risk --asset BTC

What it does:

1. Calls get_portfolio for current positions
2. Calls get_quote for all held assets
3. Computes: position sizes as % of NAV, single-asset concentration, gross/net exposure
4. Calculates VaR and CVaR using historical returns (when available)
5. Flags positions that exceed configurable thresholds

Example output:

Portfolio Risk Assessment
━━━━━━━━━━━━━━━━━━━━━━━
NAV: $500,000.00
Positions: 4

Concentration:
  BTC     45.2%   ⚠ Exceeds 40% single-asset limit
  ETH     22.1%   OK
  AAPL    15.4%   OK
  USD     17.3%   Cash

Gross Exposure: $413,500 (82.7%)
Net Exposure:   $413,500 (82.7%, all long)

VaR (95%, 1-day): -$12,400 (-2.48%)
CVaR (95%, 1-day): -$18,900 (-3.78%)

Order Preview (/preview)

Simulates an order against the current orderbook to show expected fills, slippage, and fees before execution.

Usage:

/preview buy 1.0 BTC-USD
/preview sell 100 AAPL at 245.00

What it does:

1. Calls get_orderbook for the target symbol
2. Walks the book to simulate execution at current depth
3. Computes: average fill price, total cost, slippage vs. midpoint, estimated fees
4. Returns a fill simulation without touching the exchange

Trade History (/history)

Summarizes recent trading activity with PnL attribution.

Usage:

/history --last 7d
/history --symbol BTC-USD
/history --export csv

How Skills Compose with MCP Tools

Skills are not a separate runtime. They are structured prompts that instruct the AI agent which MCP tools to call and in what order. The execution flow:

User: /analyze BTC-USD
  |
  v
Claude loads skill definition (structured prompt)
  |
  v
Claude calls: get_quote("BTC-USD")
Claude calls: get_orderbook("BTC-USD", depth=20)
Claude calls: get_trades("BTC-USD", limit=100)
  |
  v
Claude applies analysis logic from skill definition
  |
  v
Claude returns formatted result to user

Skills can call any MCP tool. They can also call multiple tools in parallel when the calls are independent.

Custom Skill Development

You can create custom skills by adding Markdown files to ~/.liquidityio/skills/. Each file defines a slash command.

Skill File Format

---
name: spread-monitor
description: Monitor bid-ask spread and alert on widening
---

# /spread-monitor

When invoked with a symbol:

1. Call `get_orderbook` for the symbol every 10 seconds
2. Calculate the bid-ask spread in basis points
3. If spread exceeds 10 bps, alert the user
4. Display a running table of spread measurements

## Parameters

- `symbol` (required): The trading pair to monitor
- `--threshold`: Alert threshold in bps (default: 10)
- `--interval`: Check interval in seconds (default: 10)

Registering Custom Skills

Place the file in the skills directory:

mkdir -p ~/.liquidityio/skills
cp spread-monitor.md ~/.liquidityio/skills/

The skill appears as /spread-monitor in Claude Code on the next session.

Skill Best Practices

1. Keep skills focused. One skill, one job. If a skill needs more than 5 tool calls, consider splitting it.
2. Always include a dry-run mode for skills that place orders.
3. Document parameters explicitly. The AI agent reads the skill file to understand what arguments to expect.
4. Use the existing tool surface. Skills should compose MCP tools, not add new API endpoints.
5. Include example output in the skill definition so the agent formats results consistently.

Integration with Claude Code

After installing @liquidityio/mcp and @liquidityio/skills, start a Claude Code session:

claude

Available commands:

/analyze <symbol>         Market analysis
/rebalance [options]      Portfolio rebalancing
/risk [options]           Risk assessment
/preview <side> <qty> <symbol>  Order simulation
/history [options]        Trade history and PnL

These commands work alongside the raw MCP tools. You can also issue natural language requests:

"Buy 0.5 BTC if the spread is under 5 bps"
"Show me my largest positions sorted by unrealized PnL"
"What would happen if I sold all my AAPL?"

The agent uses the skill library and MCP tools together to answer these.