Named, versioned sets of agent skills

A skill-set is a single JSON manifest that names a group of agent skills and where they come from. The skill-set CLI installs the members, records exactly what was installed in a deterministic lock, and verifies the installed bytes later — locally or in CI.

npx @skill-set/cli init my-tools vercel-labs/agent-skills@find-skills

CLI reference · Format specification · Source on GitHub

The manifest

One file per set, <name>.skill-set.json, validated by a published JSON Schema. Members are the same source locators the skills CLI accepts — GitHub shorthands, git URLs, local paths, well-known HTTPS domains — optionally pinned with #tag-or-commit.

{
  "$schema": "https://skill-set.md/schema/draft/skill-set.schema.json",
  "name": "frontend",
  "version": "1.0.0",
  "description": "Skills for authoring and reviewing frontend-facing work.",
  "author": { "name": "Harry Martin", "url": "https://github.com/hcjmartin" },
  "skills": [
    "hcjmartin/skills-repo@skill-creator",
    "vercel-labs/agent-skills@web-design-guidelines#v2.1.0",
    "https://github.com/hcjmartin/agent-skills@review-code#8f7e6d5",
    "https://flocker.md/skills@research-notes"
  ]
}

Quickstart

Define a set and install its skills. init writes the manifest and offers to install immediately:

npx @skill-set/cli init frontend \
  hcjmartin/skills-repo@skill-creator \
  "vercel-labs/agent-skills@web-design-guidelines#v2.1.0"

The manifest lands at .agents/skills/skill-sets/frontend/frontend.skill-set.json; each member installs as an ordinary skill at .agents/skills/<skill-name>/. Install (or re-install) any time — members whose locked content is already on disk are skipped:

npx @skill-set/cli install frontend

Record the resolved content of every member — a SHA-256 per skill folder plus a rollup hash:

npx @skill-set/cli lock frontend

Then verify byte-exactly. Drift exits with code 3 and names every drifted member with its expected and actual hash:

npx @skill-set/cli verify frontend --frozen

Sharing a set

A skill-set is shareable as a URL to its manifest — any HTTPS location serving the JSON file works; no registry required. add fetches, validates, shows the member and source summary, then installs:

npx @skill-set/cli add https://example.com/frontend.skill-set.json

How it works

• The manifest is authored intent. It carries names, versions, and locators — never hashes. The generated <name>.skill-set.lock.json carries resolved reality: content hashes and resolved refs.
• Resolution is delegated. The CLI shells out to the pinned upstream npx skills@1.5 to fetch and install members; it adds sets, locks, and verification on top. Arguments after -- pass through to the skills CLI verbatim.
• Everything generated is deterministic. Identical inputs produce identical bytes — no timestamps, sorted keys — so locks are merge-friendly and diffs stay readable.
• The format is an open spec. Manifests, locks, and both hashes are fully defined by the specification, with published schemas and conformance fixtures. An independent implementation needs nothing from this CLI.

Read more

• CLI reference — every command, global flags, exit codes, JSON output.
• Specification — the normative format: manifest, lock, hashing, conformance.
• FAQ — where files live, cross-set conflicts, verifying in CI.