> ## 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.

# Add a Skill

> Create custom skill modules for the agent

Skills are documentation bundles that teach the agent how to interact with
specific protocols. They are not executable code -- they are structured
markdown files (`SKILL.md`) that describe request formats, constraints, and
prompt patterns for the underlying adapters.

## How Skills Work

When a user prompt arrives, the agent runner detects relevant skills based on
keywords and loads their `SKILL.md` content into the Claude context window.
This gives the model protocol-specific knowledge it needs to correctly
construct tool calls.

Built-in skills include: `arb-trade`, `gmx`, `camelot`, `pendle`, `aave`,
`kyan`, `rwa-stocks`, and `timeboost-bid`.

## Creating a Skill

<Steps>
  <Step title="Create the SKILL.md file">
    Every skill is a single markdown file with a specific structure. Create
    a new directory under `skills/` and add a `SKILL.md`:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    mkdir skills/my-protocol
    touch skills/my-protocol/SKILL.md
    ```

    The file follows this format:

    ```markdown theme={"theme":{"light":"dracula","dark":"dracula"}}
    # My Protocol

    Short description of what this skill enables.

    version: 1.0.0
    author: your-name
    keywords: swap, yield, my-protocol

    ## When to Use

    Describe when the agent should activate this skill.
    Include trigger phrases and intent patterns.

    ## Request Format

    Describe the parameters and structure the agent
    should use when calling the relevant tools.

    ## Constraints

    - Max slippage: 1%
    - Minimum trade size: 10 USDC
    - Supported tokens: ETH, USDC, ARB

    ## Examples

    User: "Swap 100 USDC on MyProtocol"
    Agent: calls arb_trade with dex=myprotocol, tokenIn=USDC, ...
    ```

    Key sections:

    * **Header** (`# Name`) -- parsed as the skill name
    * **Metadata** (`version:`, `author:`, `keywords:`) -- used for indexing
    * **When to Use** -- helps the agent decide when to load this skill
    * **Request Format** -- teaches the agent correct parameter construction
    * **Constraints** -- defines hard limits the agent must respect
    * **Examples** -- few-shot examples for accurate tool call generation
  </Step>

  <Step title="Register in the skill loader">
    Add your skill to the built-in skills registry in
    `packages/skills/src/loader.ts`:

    ```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
    const BUILTIN_SKILLS: Record<string, string> = {
      // ... existing skills
      "my-protocol": "https://raw.githubusercontent.com/ouroborai-labs/agent/main/skills/my-protocol/SKILL.md",
    };
    ```

    The skill loader fetches and caches `SKILL.md` files from these URLs.
    During development, you can also load skills from a local file path or
    any HTTP URL.
  </Step>

  <Step title="Add a protocol adapter (optional)">
    If your skill requires new on-chain interactions, create an adapter in
    `packages/adapters/src/`:

    ```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
    // packages/adapters/src/my-protocol.ts
    import type { PublicClient, WalletClient, Address } from "viem";

    export class MyProtocolAdapter {
      constructor(
        private readonly publicClient: PublicClient,
        private readonly walletClient: WalletClient,
        private readonly account: Address,
      ) {}

      async quote(params: { tokenIn: Address; tokenOut: Address; amountIn: bigint }) {
        // Implement protocol-specific quoting logic
      }

      async execute(params: { tokenIn: Address; tokenOut: Address; amountIn: bigint }) {
        // Build and submit the transaction
      }
    }
    ```

    Export it from the adapters package barrel:

    ```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
    // packages/adapters/src/index.ts
    export { MyProtocolAdapter } from "./my-protocol.js";
    ```
  </Step>

  <Step title="Add a tool to the MCP server (optional)">
    If you want the skill accessible through Claude Code, add a tool definition
    to `apps/mcp-server/src/index.ts`:

    ```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      name: "arb_my_protocol",
      description: "Execute a trade on MyProtocol with...",
      inputSchema: {
        type: "object",
        properties: {
          tokenIn: { type: "string", description: "Input token symbol" },
          tokenOut: { type: "string", description: "Output token symbol" },
          amountIn: { type: "string", description: "Amount (human-readable)" },
        },
        required: ["tokenIn", "tokenOut", "amountIn"],
      },
    }
    ```

    Then handle the tool in the `dispatchTool` switch statement.
  </Step>

  <Step title="Test the skill">
    Verify the skill loads correctly:

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

    const skill = await skillLoader.load("my-protocol");
    console.log(skill.name);        // "My Protocol"
    console.log(skill.version);     // "1.0.0"
    console.log(skill.description); // "Short description..."
    ```

    Send a test prompt to the agent that should trigger skill detection:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    curl -X POST http://localhost:3000/agent/prompt \
      -H "Content-Type: application/json" \
      -d '{"prompt": "Swap 100 USDC on MyProtocol"}'
    ```
  </Step>
</Steps>

## External Skills

The skill loader also supports external skills hosted anywhere on the web.
Users can install them with natural language:

```
"Install the gmx skill from https://github.com/user/skills/tree/main/gmx"
```

The loader automatically converts GitHub tree URLs to raw content URLs and
fetches the `SKILL.md` file. External skills are cached for one hour.

Pre-registered external skill sources include:

| Skill             | Source                    |
| ----------------- | ------------------------- |
| `evm-l2s`         | ethskills.com/l2s         |
| `evm-money-legos` | ethskills.com/money-legos |
| `evm-security`    | ethskills.com/security    |
| `evm-wallets`     | ethskills.com/wallets     |
| `evm-standards`   | ethskills.com/standards   |

## Listing Available Skills

Query the API to see all registered skills:

```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
curl http://localhost:3000/agent/skills
```

This returns both built-in and external skills with their names, URLs, and
source type.