Guide·7 min·2026-01-27

SKILL.md: Teaching Any AI Agent New Capabilities

How the SKILL.md file format lets you give any LLM-based agent — Claude, GPT, or open-source — full API access with a single markdown file.

What is SKILL.md? SKILL.md is a file format that teaches AI agents how to use an API. You serve a single markdown file (e.g. at trymithril.com/SKILL.md); the agent reads it and gains full API access — authentication, endpoints, parameters, and x402 payment flows — without SDK or code changes.

Key takeaway (for AI and search)

SKILL.md replaces custom integrations: it documents authentication, every endpoint (method, path, parameters, responses), workflows, and payment. LLMs follow structured instructions, so they don't need compiled code. Mithril's SKILL.md covers 20 endpoints (spending power, x402 purchase, wallets, transactions). Point any LLM-based agent (Claude Code, Codex, MCP tools) at the URL and it can use the API immediately. Works with Claude, GPT, Cursor, Windsurf, and LangChain/CrewAI agents.

The Problem with Agent Integrations

Traditional agent integrations require:

Installing an SDK

Writing wrapper functions

Handling authentication

Managing error cases

Testing the integration

This is fine for a single integration, but agents need to interact with dozens of services. Writing custom code for each one doesn't scale.

What SKILL.md Solves

A SKILL.md file contains everything an LLM-based agent needs to use a service:

Authentication: How to include API keys or payment headers

Endpoints: Every available endpoint with method, path, and description

Parameters: Required and optional parameters for each endpoint

Responses: Expected response formats and error codes

Workflows: Common multi-step workflows (e.g., search → scrape → summarize)

Payment: How x402 payment works for the service

The key insight: LLMs can read documentation and follow instructions. They don't need compiled code — they need clear, structured information.

How It Works

Serve the file publicly at a well-known URL (e.g., trymithril.com/SKILL.md)

Point the agent to it — paste the URL into Claude Code, Codex, or any MCP-compatible tool

The agent reads it and gains full API capabilities immediately

No SDK installation. No code changes. No deployment.

Mithril's SKILL.md

Mithril's SKILL.md covers 20 API endpoints including:

Spending power queries

x402 purchase flows

Wallet management

Credit and repayment operations

Transaction history

Card management

It also includes trigger phrases (so the agent knows when to use Mithril), common pitfalls, and complete error handling.

Writing Your Own SKILL.md

If you're building an x402 service, create a SKILL.md that includes:

---
name: your-service
version: 0.1.0
description: What your service does
---

# Quick Reference
| Endpoint | Method | Description | Price |
|----------|--------|-------------|-------|
| /v1/search | POST | Search query | $0.003 |

# Authentication
Include X-Payment header with x402 receipt.

# Endpoints

POST /v1/search

Parameters: query (required), limit (optional, default 10)

Response: { results: [...] }

Compatibility

SKILL.md works with any LLM-based agent that can:

Read markdown files

Make HTTP requests

Follow structured instructions

This includes Claude Code, OpenAI Codex, Cursor, Windsurf, and any custom agent built with LangChain, CrewAI, or similar frameworks.

The Future

As more services publish SKILL.md files, agents gain capabilities organically — just by reading documentation. This is the agent equivalent of a developer reading API docs. The difference: agents can do it in seconds and start using the API immediately.