Add a Skill

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

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:

mkdir skills/my-protocol
touch skills/my-protocol/SKILL.md

The file follows this format:

# 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

Add your skill to the built-in skills registry in packages/skills/src/loader.ts:

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.

Add a protocol adapter (optional)

If your skill requires new on-chain interactions, create an adapter in packages/adapters/src/:

// 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:

// packages/adapters/src/index.ts
export { MyProtocolAdapter } from "./my-protocol.js";

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:

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

Test the skill

Verify the skill loads correctly:

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:

curl -X POST http://localhost:3000/agent/prompt \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Swap 100 USDC on MyProtocol"}'

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:

curl http://localhost:3000/agent/skills

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

Getting Started

Agent API

Features

Contracts

Bots

Guides

How Skills Work

Creating a Skill

External Skills

Listing Available Skills

​How Skills Work

​Creating a Skill

​External Skills

​Listing Available Skills

How Skills Work

Creating a Skill

External Skills

Listing Available Skills