Skip to main content

SKILL.md Format Reference

Every skill is a single SKILL.md file with two parts: a YAML frontmatter block at the top, and a markdown body with the instructions for the agent. Optionally, a sibling references/ folder can hold supporting docs.

This page describes the file format. The same format is used whether you're installing from GitHub, writing one manually in the Skills tab, or contributing to the public catalog.

File layout​

your-skill/
├── SKILL.md              # required
└── references/           # optional
    ├── workflow-a.md
    └── workflow-b.md

SKILL.md anatomy​

---
name: my-skill
description: What this skill does and when the agent should use it
tags: [trading, defi]
version: 1
visibility: private
metadata:
  clawdbot:
    emoji: "⚡"
    homepage: "https://example.com/my-skill"
    requires:
      bins: [git, curl]
      packages: [some-npm-package]
---

# My Skill

Markdown instructions the agent reads when this skill is loaded.

For detailed workflows, see references/workflow-a.md.

Frontmatter fields​

Required​

FieldTypeDescription
namestringShort, slug-friendly identifier. This is how the skill is referenced in install commands and the Skills list.
descriptionstringOne-sentence description of what the skill does and when it should be used. This is what the agent reads to decide whether to load the skill — write it clearly and concretely.

Optional​

FieldTypeDefaultDescription
tagsarray of strings[]Keywords used for search and filtering, e.g. [trading, defi, polymarket].
versionnumber1Bump when you make breaking changes so users notice updates.
visibilityprivate | publicprivateprivate keeps the skill scoped to your own agent; public makes it discoverable to other users (subject to review).

Metadata block​

The metadata.clawdbot block carries cross-framework hints — fields that some hosts use for richer display or pre-flight checks.

FieldTypeDescription
metadata.clawdbot.emojistringSingle emoji shown next to the skill in lists and UIs.
metadata.clawdbot.homepagestring (URL)Link to the skill's homepage, repo, or docs.
metadata.clawdbot.requires.binsarray of stringsCommand-line binaries the skill expects to be installed (e.g. [git, curl]). Hosts may warn the user if they're missing.
metadata.clawdbot.requires.packagesarray of stringsNPM (or similar) packages the skill expects to be available.

The body​

Everything after the closing --- is the skill's instruction body. It's plain markdown, written for the agent — describe what the skill does, when to use it, what tools or APIs to call, and any edge cases to watch for.

A few rules of thumb:

  • Be concrete. "When the user asks about X, do Y" works better than "this skill helps with X."
  • Keep it short. The body lives in the agent's context every time the skill is active. If it's long, move detail into references/ files and link to them from the body — the agent will fetch them on demand.
  • Reference your own files by relative path. see references/api-workflow.md is enough; the agent resolves the file at fetch time.

Reference files​

Files inside references/ are optional companion docs. They're not loaded into context automatically — the main SKILL.md should mention them, and your agent fetches the relevant one when the situation calls for it.

This is the right place for:

  • Step-by-step workflows that only apply to a subset of requests.
  • API specs, schema dumps, or long examples.
  • Edge-case handling notes.

Each file is plain markdown. There's no required structure beyond that.

Validation​

When a skill is installed, the file is validated against this format. The most common errors are:

  • Missing frontmatter. The file must start with --- on the first line.
  • Missing name or description. Both are required.
  • File too large. Each file (SKILL.md or any single reference) is capped at 100 KB.

Fix the file and re-install — the same install command will overwrite the previous version.

Portability​

A skill written in this format is portable across hosts: the same SKILL.md that runs in your Bankr agent will also run in any other framework that supports the format (Claude Code, OpenClaw, Cursor, …). That's the point — write once, install anywhere.

Next steps​