# Plugins and Skills

> The [`gmx-io/gmx-ai`](https://github.com/gmx-io/gmx-ai) repository provides pre-built agent skills that give AI coding agents the ability to trade perpetuals, provide liquidity, and swap tokens on GMX V2. Skills use a filesystem-based format compatible with a wide range of agents — see [Installation](#installation) for supported clients.

# Plugins and Skills

The [`gmx-io/gmx-ai`](https://github.com/gmx-io/gmx-ai) repository provides pre-built agent skills that give AI coding agents the ability to trade perpetuals, provide liquidity, and swap tokens on GMX V2. Skills use a filesystem-based format compatible with a wide range of agents — see [Installation](#installation) for supported clients.

:::note
Skills currently use [SDK v1](../sdk/v1/readme.mdx) and direct contract calls for write operations, and the [GMX API and Oracle API](../api/overview.md) for data access. As the GMX API and SDK v2 mature, skills will migrate to fully leverage them — expanding capabilities to cover virtually any protocol action.
:::

## Available skills

The repository ships two skills that cover the main protocol operations.

### gmx-trading

Bundles everything an AI agent needs to trade on GMX:

- **Trading operations** — Open long/short positions with up to 100x leverage, swap tokens at oracle prices, and place market, limit, stop-loss, and take-profit orders.
- **Position management** — Query open positions, pending orders, and trade history.
- **Market data** — Fetch markets, token prices, pool sizes, and utilization rates.
- **Reference material** — SDK method signatures, GMX API, Oracle API, and GraphQL endpoint documentation, contract addresses for all supported chains, and order type behavior specifications.

### gmx-liquidity

Covers liquidity provision across GM pools and GLV vaults:

- **GM pool operations** — Deposit into single-market pools (balanced or single-sided), withdraw, and shift liquidity between pools atomically.
- **GLV vault operations** — Deposit raw tokens or existing GM tokens into multi-market auto-rebalancing vaults, and withdraw.
- **Pool data** — Query pool TVL, composition, utilization, capacity, and GM/GLV token balances.
- **Reference material** — Contract struct definitions, execution flows, gas estimation formulas, GLV vault addresses, and viem multicall examples.

### Supported chains

| Chain | Chain ID | Native token | Status |
|-------|----------|--------------|--------|
| Arbitrum | 42161 | ETH | Active |
| Avalanche | 43114 | AVAX | Active |
| MegaETH | 4326 | ETH | Active |

## Installation

### Claude Code

Install the GMX plugin from the Claude Code marketplace:

```
/plugin marketplace add gmx-io/gmx-ai
/plugin install gmx-io@gmx-ai
```

Once installed, Claude Code can execute trades, provide liquidity, query positions, and interact with GMX markets using natural language instructions.

### Skills CLI (Codex, Cursor, Copilot, Windsurf, and others)

Add the skill using the [Skills CLI](https://github.com/vercel-labs/skills):

```bash
npx skills add gmx-io/gmx-ai
```

This installs both the `gmx-trading` and `gmx-liquidity` skills as filesystem-based context files that any compatible coding agent can read. Supported agents include:

- OpenAI Codex
- Cursor
- GitHub Copilot
- Windsurf
- Gemini CLI
- Amp (Sourcegraph)
- Roo Code
- Goose
- Cline
- Continue

Any agent that reads project-level instruction files from the filesystem can use the skill.

## Reference files

Both skills expose capabilities through shared and skill-specific reference files:

| Reference | Skill | Contents |
|-----------|-------|----------|
| **SDK reference** | Shared | `GmxSdk` and `GmxApiSdk` class APIs, module methods, type definitions, and initialization patterns |
| **API endpoints** | Shared | Oracle API endpoints, GMX API OpenAPI endpoints, GraphQL queries, and fallback URLs per chain |
| **Contract addresses** | Shared | Deployed contract addresses for ExchangeRouter, Reader, GlvReader, vaults, and relay routers on every supported chain |
| **Order types** | Trading | Order type enum values, trigger conditions for longs and shorts, auto-cancel limits, and TWAP specifications |
| **Liquidity operations** | Liquidity | Contract struct definitions, execution flows, gas estimation formulas, GLV vault addresses, and viem multicall examples |

## How agents use the skills

When an AI agent has the skills installed, it can:

1. **Fetch market data** — Discover available markets, current prices, and pool conditions.
2. **Calculate fees** — Estimate execution fees, position fees, and price impact before placing orders.
3. **Open positions** — Create long or short positions with specified leverage and collateral.
4. **Set conditional orders** — Place limit entries, stop-losses, and take-profit orders.
5. **Monitor positions** — Check open positions, unrealized PnL, and pending orders.
6. **Close positions** — Compute decrease amounts and submit close orders.
7. **Swap tokens** — Execute token swaps at oracle-determined prices.
8. **Deposit liquidity** — Deposit into GM pools (balanced or single-sided) and GLV vaults.
9. **Withdraw liquidity** — Withdraw from GM pools and GLV vaults.
10. **Shift liquidity** — Move GM tokens between pools atomically without withdrawing first.

## Repository structure

```
gmx-io/gmx-ai/
  .well-known/skills/          # Vercel Skills protocol
    index.json                 # Skill registry
    gmx-trading/
      SKILL.md                 # Trading skill definition
      references/
        sdk-reference.md       # SDK API reference (shared)
        api-endpoints.md       # GMX API, Oracle API, and GraphQL endpoints (shared)
        contract-addresses.md  # Deployed contracts per chain (shared)
        order-types.md         # Order type specifications
    gmx-liquidity/
      SKILL.md                 # Liquidity skill definition
      references/
        liquidity-operations.md  # Contract structs, flows, gas formulas
  plugins/gmx-io/              # Claude Code plugin
    .claude-plugin/
      plugin.json              # Plugin manifest
    skills/
      gmx-trading/             # Trading skill files (mirrored)
      gmx-liquidity/           # Liquidity skill files (mirrored)
```

## Links

- **Repository:** [github.com/gmx-io/gmx-ai](https://github.com/gmx-io/gmx-ai)
- **SDK package:** [`@gmx-io/sdk` on npm](https://www.npmjs.com/package/@gmx-io/sdk)
- **SDK documentation:** [SDK overview](../sdk/overview.md)
- **API documentation:** [API overview](../api/overview.md)
- **GMX app:** [app.gmx.io](https://app.gmx.io)
