Skip to main content
A skill is a directory containing at minimum a SKILL.md file. That file tells an AI agent what the skill does, when to use it, and how to invoke it.

​
Anatomy of a skill

​
SKILL.md

The only required file. Written in plain markdown. Contains:
  • What the skill does (a short description)
  • When to use it (trigger phrases or conditions)
  • How to invoke it (commands, arguments, examples)
The agent reads this file and decides whether and how to use the skill based on the current conversation.

​
Scripts (optional)

If a skill needs to run code, it includes an executable. Any language works — shell, Python, Node, Go binary. The contract is simple:
  • Input: command-line arguments and/or stdin
  • Output: stdout (text the agent reads back)
  • Errors: stderr and non-zero exit codes
No HTTP. No JSON-RPC. No WebSockets.

​
Skills vs MCP servers

​
Design principles

  1. Files over protocols — A skill is data the agent reads, not a service it connects to.
  2. CLI over RPC — When code needs to run, use standard Unix conventions.
  3. Markdown over schemas — Natural language descriptions are what LLMs understand best.
  4. Simple over complete — Cover the 90% case. Don’t build abstractions for edge cases.