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

# Skills System

> Composable skill modules for the AI agent

## Overview

Skills are modular knowledge bundles that give the ouroborai agent context about specific protocols, strategies, and capabilities. Each skill is a `SKILL.md` markdown file containing structured information the agent uses to understand how to interact with a DeFi protocol or execute a trading strategy.

Skills are **not code**. They are documentation that gets injected into the agent's system prompt at runtime, guiding how it selects tools, formats parameters, and explains results to the user.

## Built-in skills

ouroborai ships with built-in skills covering the core Arbitrum DeFi ecosystem:

<CardGroup cols={2}>
  <Card title="arb-trade" icon="arrow-right-arrow-left">
    Spot trading on Uniswap V3 and Camelot. Covers quoting, slippage, fee tiers, and token resolution.
  </Card>

  <Card title="gmx" icon="chart-line">
    GMX V2 perpetual futures. Markets (ETH, BTC, ARB, LINK), leverage up to 100x, position management.
  </Card>

  <Card title="aave" icon="piggy-bank">
    Aave V3 lending and borrowing. Supply/withdraw, borrow/repay, health factor monitoring.
  </Card>

  <Card title="camelot" icon="chess-rook">
    Camelot DEX, Arbitrum's native AMM. Volatile and stable pools, custom fee structures.
  </Card>

  <Card title="pendle" icon="percent">
    Pendle Finance fixed and variable yield trading. PT/YT tokens, yield markets.
  </Card>

  <Card title="kyan" icon="layer-group">
    Kyan options protocol. Multi-leg strategies, portfolio margin, Greeks.
  </Card>

  <Card title="timeboost-bid" icon="bolt">
    TimeBoost express lane bidding. Priority sequencing, MEV estimation, round timing.
  </Card>

  <Card title="rwa-stocks" icon="building-columns">
    Robinhood tokenized stocks on Arbitrum Orbit. Contract scanning, symbol lookup.
  </Card>
</CardGroup>

External knowledge bases are also available for broader EVM context:

| Skill             | Source        | Description                                       |
| ----------------- | ------------- | ------------------------------------------------- |
| `evm-l2s`         | ethskills.com | Layer 2 network comparison and bridging           |
| `evm-money-legos` | ethskills.com | Composable DeFi building blocks                   |
| `evm-security`    | ethskills.com | Smart contract security patterns                  |
| `evm-wallets`     | ethskills.com | Wallet types, key management, account abstraction |
| `evm-standards`   | ethskills.com | ERC standards (ERC-20, ERC-721, ERC-4337, etc.)   |

## How skill detection works

When a user submits a prompt, the agent runner matches keywords in the prompt text against a keyword-to-skill mapping. Matched skills are loaded and their content is injected into the system prompt before Claude processes the request.

```
User prompt: "Open a 10x long on ETH/USDC"
                      |
              Keyword matching
         ("long" → gmx, "10x" → gmx)
                      |
            Load gmx SKILL.md content
                      |
         Inject into system prompt
                      |
       Claude selects arb_perp_open tool
```

The keyword map covers common terms for each protocol:

| Keywords                                                | Skill loaded  |
| ------------------------------------------------------- | ------------- |
| `swap`, `trade`, `buy`, `sell`, `uniswap`               | arb-trade     |
| `camelot`                                               | camelot       |
| `perp`, `perpetual`, `leverage`, `long`, `short`, `gmx` | gmx           |
| `lend`, `borrow`, `supply`, `aave`                      | aave          |
| `yield`, `pendle`                                       | pendle        |
| `options`, `kyan`                                       | kyan          |
| `timeboost`, `express lane`                             | timeboost-bid |
| `stock`, `robinhood`, `rwa`                             | rwa-stocks    |
| `alchemix`, `self-repaying`, `aleth`, `alusd`           | alchemix      |
| `nft`, `transfer nft`                                   | nft           |
| `prediction`, `polymarket`, `forecast`                  | polymarket    |
| `bridge`, `cross-chain`, `bungee`                       | bridge        |
| `launch`, `create token`, `deploy token`                | token-launch  |

The `arb-trade` skill is always loaded as a baseline, even if no keywords match.

<Info>
  Multiple skills can be loaded simultaneously. A prompt like "swap ETH for USDC and supply to Aave" would load both `arb-trade` and `aave` skills.
</Info>

## Skill anatomy

Each skill is a markdown file named `SKILL.md` with a defined structure. The loader parses metadata from the heading and frontmatter-style fields:

```markdown theme={"theme":{"light":"dracula","dark":"dracula"}}
# Uniswap V3 Trading

Trade tokens on Arbitrum using Uniswap V3 concentrated liquidity pools.

version: 1.2.0
author: ouroborai-labs

## Supported Tokens

- USDC (0xaf88d065e77c8cc2239327c5edb3a432268e5831)
- WETH (0x82aF49447D8a07e3bd95BD0d56f35241523fBab1)
- ARB (0x912CE59144191C1204E64559FE8253a0e49E6548)
- WBTC (0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f)

## Fee Tiers

| Tier | Fee | Best for |
|------|-----|----------|
| 100  | 0.01% | Stablecoin pairs |
| 500  | 0.05% | Correlated pairs |
| 3000 | 0.30% | Standard pairs |
| 10000| 1.00% | Exotic pairs |

## Constraints

- Always show a quote before executing a swap
- Default slippage tolerance: 50 bps (0.5%)
- Warn if price impact exceeds 100 bps (1%)

## Example Prompts

- "Swap 100 USDC for ETH"
- "Get a quote for 1 WBTC to USDC on 3000 fee tier"
- "Buy 500 ARB with USDC"
```

The loader extracts these fields:

| Field         | Source                        | Description                           |
| ------------- | ----------------------------- | ------------------------------------- |
| `name`        | First `#` heading             | Display name of the skill             |
| `description` | First paragraph after heading | Short description                     |
| `version`     | `version:` field              | Semantic version                      |
| `author`      | `author:` field               | Skill author (optional)               |
| `content`     | Full file content             | Injected into the agent system prompt |

## Loading and caching

Skills are fetched over HTTP and cached in memory for 1 hour. Built-in skills are served from the project's GitHub repository. External skills can be loaded from any URL.

The loader resolves skill references in this order:

1. Check if the input is a URL (starts with `http`) -- fetch directly
2. Check built-in skills map by name
3. Check external skills map by name
4. Throw an error if not found

GitHub tree URLs are automatically normalized to raw content URLs:

```
https://github.com/org/repo/tree/main/skills/gmx
  → https://raw.githubusercontent.com/org/repo/main/skills/gmx/SKILL.md
```

## Installing external skills

You can install skills from any GitHub repository at runtime using the agent's natural-language interface or the MCP `arb_install_skill` tool:

<CodeGroup>
  ```text Natural language theme={"theme":{"light":"dracula","dark":"dracula"}}
  Install the gmx skill from https://github.com/ouroborai-labs/arbitrum-agent/tree/main/skills/gmx
  ```

  ```json MCP tool theme={"theme":{"light":"dracula","dark":"dracula"}}
  {
    "tool": "arb_install_skill",
    "arguments": {
      "url": "https://github.com/ouroborai-labs/arbitrum-agent/tree/main/skills/gmx"
    }
  }
  ```

  ```typescript Programmatic theme={"theme":{"light":"dracula","dark":"dracula"}}
  import { skillLoader } from "@arb-agent/skills";

  const skill = await skillLoader.load(
    "https://github.com/ouroborai-labs/arbitrum-agent/tree/main/skills/gmx"
  );

  console.log(skill.name);        // "GMX V2 Perpetuals"
  console.log(skill.version);     // "1.0.0"
  console.log(skill.description); // "Trade perpetual futures..."
  ```
</CodeGroup>

## Creating a custom skill

To add a new skill to the platform:

<Steps>
  <Step title="Write the SKILL.md file">
    Create a markdown file following the anatomy described above. Include supported tokens, constraints, example prompts, and any protocol-specific details the agent needs to know.
  </Step>

  <Step title="Host it at a URL">
    Push the file to a GitHub repository or host it on any HTTP-accessible server. The loader fetches skills over plain HTTP.
  </Step>

  <Step title="Register in the built-in map (optional)">
    To make the skill discoverable by name without a URL, add an entry to the `BUILTIN_SKILLS` or `EXTERNAL_SKILLS` map in `packages/skills/src/loader.ts`.
  </Step>

  <Step title="Add keyword mappings (optional)">
    To enable automatic detection from user prompts, add keyword entries to the `keywords` map in `apps/api/src/agent/runner.ts`.
  </Step>

  <Step title="Add a protocol adapter (optional)">
    If the skill requires new on-chain interactions, implement an adapter in `packages/adapters/src/` and wire it into the agent runner's tool definitions.
  </Step>
</Steps>

<Note>
  Skills that only provide knowledge (no new tools) can be created and installed without any code changes. The agent will use the skill content to better formulate requests to existing tools.
</Note>

## Listing available skills

The `GET /agent/skills` endpoint returns all registered skills:

```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
curl -H "X-PAYMENT: <payment>" https://api.ouroborai.com/agent/skills
```

```json theme={"theme":{"light":"dracula","dark":"dracula"}}
{
  "skills": [
    { "name": "arb-trade", "url": "https://raw.githubusercontent.com/...", "external": false },
    { "name": "gmx", "url": "https://raw.githubusercontent.com/...", "external": false },
    { "name": "aave", "url": "https://raw.githubusercontent.com/...", "external": false },
    { "name": "evm-l2s", "url": "https://ethskills.com/l2s/SKILL.md", "external": true }
  ]
}
```

Skills with `"external": true` are sourced from third-party providers and are loaded on demand when triggered by prompt keywords or explicit installation.