The skillet skill format & registry spec

skillet deliberately does not invent a new skill format. A skill is a folder containing a SKILL.md with YAML frontmatter — the same shape the agent-skills ecosystem already uses. skillet adds discovery, install, and versioning around it.

A skill

my-skill/
├── SKILL.md          # required — metadata + instructions
├── scripts/          # optional — supporting files, installed together
└── reference.md      # optional

SKILL.md frontmatter

field	required	notes
name	✅	kebab-case [a-z0-9-]; this is the install folder name
description	✅	one sentence — what it does and when to use it (shown in search)
version	➖	semver recommended for reproducible installs
license	➖	SPDX id (e.g. MIT)
keywords	➖	array, improves search
homepage	➖	URL

Everything after the frontmatter is the instruction body the agent reads.

Validate yours:

npx @jnmetacode/skillet validate ./my-skill

The registry

The registry is a single JSON file in a Git repo, served over raw.githubusercontent.com. There is no server. To add your skill, open a PR that appends one entry to registry/index.json:

{
  "name": "web-scraper",
  "description": "Scrape pages and extract structured data; use for web content.",
  "repo": "your-org/your-repo",
  "path": "skills/web-scraper",
  "ref": "main",
  "keywords": ["scrape", "http"],
  "license": "MIT"
}

field	meaning
name	unique registry id (usually matches the skill's name)
repo	owner/repo on GitHub
path	subdirectory holding the SKILL.md (omit if repo root)
ref	branch or tag to install from

Private / alternate registries

Point skillet at any index URL or local file:

skillet add my-skill --registry https://example.com/my-registry.json
skillet add my-skill --registry ./local-registry.json
# or persist it:
skillet init   # then edit skillet.json -> "registry"

Lockfile

skillet.lock.json records, per installed skill: the original ref, the source repo/path/gitRef, the resolved commit resolved (SHA), the version, and installedAt. Commit it, then anyone can reproduce the exact set with skillet install (no args), which reinstalls every entry at its pinned resolved SHA — the npm ci of skills. skillet add owner/repo#<sha> pins a single install; branches/tags track their latest until you skillet update.

Config

skillet.json (optional, created by skillet init):

{
  "skillsDir": ".claude/skills",
  "registry": "https://raw.githubusercontent.com/jnMetaCode/skillet/main/registry/index.json"
}