Skill format

What is inside a pack, what a SKILL.md looks like, and how versions and checksums keep everything reproducible.

What a skill is

A skill is a folder of instructions for Claude. The one required file is SKILL.md: plain Markdown with a short header describing when the skill applies, followed by the instructions Claude should follow. A skill can also carry supporting files (templates, scripts, reference notes) that the instructions point to.

Inside a pack

SkilVault distributes each skill as a pack — a zip file laid out as a plugin:

commit-lint-1.0.0.zip
├── .claude-plugin/
│   └── plugin.json          name, version, description
└── skills/
    └── commit-lint/
        ├── SKILL.md         the instructions (required)
        ├── examples.json    10–20 example requests (optional; used to find the skill)
        └── …                any supporting files

examples.json lists requests a person would type when this skill is the right one, {"examples": ["…", "…"]}: 10–20 of them, one line of up to 200 characters each. They are part of the signed pack. The server turns each into a vector, and your client matches your requests against them on your machine (The skilvault client). SkilVault writes them for every skill it publishes; a pack you upload may leave them out.

skilvault read prints skills/<name>/SKILL.md. Local copies, when you turn them on, copy the whole skills/<name> folder into ~/.claude/skills.

The SKILL.md file

---
name: commit-lint
description: Check commit messages against Conventional Commits. Use when reviewing
  commits, writing a PR title, or generating a changelog.
---

# Commit lint

1. Read the commits in scope…

The header (called frontmatter) must include:

• name — lowercase words separated by single dashes, e.g. commit-lint. This is the name you use in every command.
• description — what the skill does and when to use it. This is what Claude reads to decide whether the skill fits, and what list and search show.

Optional fields — license, compatibility, metadata and allowed-tools — keep a skill portable across Claude Code, claude.ai and the API.

Versions

• Versions are numbered major.minor.patch (for example 1.2.0) and each new version must be higher than the last.
• A published version is immutable: its contents never change. Fixes ship as a new version.
• You always get the latest published version of a skill you have selected. Local copies refresh the first time you use SkilVault from a CLI that day (Skills in your CLI).

Checksums

Every version has a SHA-256 checksum, shown as sha256 in your manifest. Packs are built deterministically — sorted entries and fixed metadata — so identical content always produces an identical checksum. The client compares what it downloaded to the manifest and refuses a mismatch.

You can check by hand:

shasum -a 256 commit-lint.zip

Limits

Packs are validated on upload: at most 64 MiB, at most 500 files, no symbolic links, and no paths that escape the pack.

Licences

Each skill carries its own licence in its metadata. Your use of a skill follows that licence. The Legal page has the details.

Publishing your own

SkilVault is curated: skills are added by administrators after review. There is no self-serve upload for end users today.