The SKILL.md Specification (open standard)
A skill is a directory containing a SKILL.md file. The file has YAML
frontmatter (validated by forge and described by the published
skill.schema.json)
followed by the skill's instruction body in Markdown.
Frontmatter fields
Required
| Field | Rule |
|---|---|
name |
kebab-case, ^[a-z][a-z0-9-]{2,63}$, unique within a registry |
description |
20–300 chars. Describe when to use the skill (agents match on this) |
version |
SemVer, e.g. 1.0.0 |
license |
SPDX id (e.g. MIT) or the literal Proprietary |
Optional
| Field | Rule |
|---|---|
author |
string / handle |
homepage, repository |
URLs |
tags |
≤10, kebab-case; suggested vocabulary: security, testing, docs, refactor, git, db, i18n, frontend, backend, devops, agent, prompt, cli, ci, performance, api, ml, data |
compatible_clients |
subset of claude-code, cursor, codex, opencode, cline; omit for all |
min_forge_version |
minimum forge version |
dependencies |
names of other skills this one builds on |
model_hint |
small | medium | large |
entrypoint |
relative path to an executable script (smoke-tested with --help) |
examples |
example trigger prompts |
Body rules
- Non-empty Markdown, ≥200 characters.
- Contains at least one
##section heading. - Local relative links (with
--links) must resolve. - Keep the directory lean (≤50 KB excluding images).
Why a standard?
Because the spec is a portable JSON Schema, any client or editor can adopt
it — forge writes the same skill to every detected agent with zero copy
drift. That vendor-neutrality is the project's core differentiation.
Run forge schema --out skill.schema.json to drop the spec into your repo.