What is SKILL.md? How AI Agents Learn New Tools

When you give an AI agent a new tool, it needs to learn what the tool does. Today, most people solve this with custom tool definitions, function calling schemas, or carefully engineered system prompts.

There's a simpler way: a file.

The pattern

SKILL.md is a markdown file that ships with a CLI tool. It describes every command, flag, workflow, and example in a format that AI coding agents read naturally — because they already know how to read documentation.

When an agent encounters a SKILL.md file in its working directory, it reads it like a developer reads a README. It learns:

• What commands are available
• What flags and options each command accepts
• What the expected inputs and outputs look like
• Common workflows and patterns
• Error handling and edge cases

No API registration. No JSON schema. No custom integration code.

Why file-based discovery works

AI coding agents like Codex, Claude Code, and OpenClaw interact with the world through files and shell commands. That's their native interface. When you give an agent a tool, the most natural way to teach it is through the same interface:

1. Files — the agent reads documentation
2. Commands — the agent runs shell commands
3. Output — the agent reads stdout/stderr

SKILL.md fits this model perfectly. The agent reads the file (step 1), learns the commands (step 2), and interprets results (step 3). No middleware, no adapters, no glue code.

Compare this to the alternatives:

How broker-cli implements it

broker-cli is the reference implementation of this pattern. Its SKILL.md describes the complete trading interface:

# broker-cli

## Commands

### broker snapshot
Fetch a one-call account snapshot for agent loops.

Flags:
- `--symbols SYMBOLS` — Optional comma-separated quote symbols
- `--exposure-by symbol|sector|asset_class|currency` — Exposure grouping

Example:
$ broker snapshot --symbols AAPL,NVDA
{"ok":true,"data":{"symbols":["AAPL","NVDA"],"quotes":[...],"positions":[...],"balance":{...},"pnl":{...}},"error":null,"meta":{"schema_version":"v1","command":"portfolio.snapshot","request_id":"...","timestamp":"..."}}

When an agent reads this, it immediately knows:

• There's a broker snapshot command
• It accepts optional symbol and exposure controls
• Responses are always in a predictable envelope
• It can parse data while preserving meta.request_id for audit tracing

Multiply this across every command — quotes, orders, options, portfolio management — and the agent has complete knowledge of the trading interface from a single file.

Writing a SKILL.md for your own tool

If you build CLI tools, you can adopt this pattern today. Here's the structure:

# your-tool

Brief description of what the tool does.

## Setup
How to install and configure.

## Commands

### your-tool command-name
What this command does.

Flags:
- `--flag-name` — Description (default: value)

Example:
$ your-tool command-name --flag-name value
Expected output here

## Workflows

### Common task name
Step-by-step for accomplishing a common goal.

## Errors
Common errors and how to handle them.

Tips for good SKILL.md files:

• Be explicit about flags and defaults — agents need to know what's optional vs required
• Include realistic examples — show actual command invocations and their output
• Document error cases — agents need to handle failures gracefully
• Keep it focused — only include what an agent needs to use the tool, not implementation details
• Use JSON output examples — agents parse structured data more reliably than text tables

The bigger picture

SKILL.md is a bet on a simple idea: the best way to teach an AI agent a new capability is the same way you'd teach a developer — with good documentation.

As AI agents become more capable and autonomous, the tools they use need discoverable, self-documenting interfaces. SKILL.md is one approach to that future.

broker-cli ships with SKILL.md because we believe agents should be able to pick up any tool and start using it immediately — the way a developer picks up a well-documented CLI.

Try it

Install broker-cli and look at the SKILL.md file:

curl -fsSL https://brokercli.com/install | bash
broker setup
cat $(which broker | xargs dirname)/../SKILL.md

Or check out the GitHub repo and the full reference.