Developer guide

How to find, install, write and publish a skill — in the browser, from a terminal, or from inside an agent. Everything here works against the live catalogue.

What this is

A skill is a folder an AI agent loads: instructions in SKILL.md, plus any scripts, references and assets it needs. The format is the Agent Skills specification, not ours — a skill that works here works anywhere that implements it.

Nothing on this page needs anything installed. If you would rather work from a terminal, the Command line tab above does the same things with one command each.

Find a skill

Explore lists everything published, newest first, and filters by category. The search box in the header looks at names, descriptions and keywords — press / from anywhere to jump to it.

A skill's page shows its description, the whole file tree, and any file you click, so you can read exactly what an agent would load before you install it.

Install a skill

Open the skill and pick a version from the dropdown, or take the latest.
Press Download. You get a .skill file, which is a zip.
Unzip it into your agent's skills directory. For Claude that is .claude/skills/ in the project, or ~/.claude/skills/ for every project.

~/.claude/skills/
└── mcp-builder/
    ├── SKILL.md
    └── ...

The archive contains one top-level folder named after the skill, so unzipping it there gives you exactly that layout.

Anatomy of a skill

my-skill/
├── SKILL.md          # required: the manifest and the instructions
├── scripts/          # optional: code the agent can run
├── references/       # optional: documentation it can read on demand
├── assets/           # optional: templates, images, data
└── examples/         # optional

Only SKILL.md is required, and only those four directory names are recognised. Anything else is allowed — you will see a note at publish, but nothing is refused for its layout.

The manifest

YAML frontmatter at the top of SKILL.md. Two fields are required.

---
name: pdf-form-filler
description: Fills PDF forms from structured data and extracts values back out. Use when the user mentions PDF forms, filling a PDF, or pulling fields out of one.
license: Apache-2.0
compatibility: Requires Python 3.11+
metadata:
  llmskillhub:
    version: 1.2.0
    categories: [documents]
    keywords: [pdf, forms, extraction]
    repository: https://github.com/you/pdf-form-filler
    capabilities:
      network: false
      filesystem: read-write
      shell: false
---

# PDF form filler

Instructions for the agent go here...

Fields the spec defines

name required: Lowercase letters, digits and single hyphens. Must match the directory name, and it is the skill's global address — names are not scoped by owner.
description required: What it does and when to use it. This is the field an agent routes on, so name the phrases someone would actually type. No angle brackets — descriptions are embedded in prompt scaffolding, where they are reserved.
license: A licence name, or a pointer to a bundled file.
compatibility: Environment requirements, if there are any. Most skills need none.
allowed-tools: Space-separated tools pre-approved to run. Experimental in the spec.
metadata: Anything else. Ours lives under metadata.llmskillhub.

`metadata.llmskillhub`

version: Semver. Without it you pass --version at publish; with it, the publish is refused if the two disagree rather than quietly relabelled.
categories, keywords: How it is found. Both feed search and the category browser.
repository, homepage, authors: Where it came from and who wrote it.
capabilities: What it touches: network, shell, filesystem (none, read, read-write) and named secrets. Worth filling in — it is what tells someone installing your skill what it will do, and it is shown on the page beside it.

Limits

Limit	Maximum
Archive on the wire	5 MiB	the .skill zip itself
Uncompressed total	25 MiB	every entry inflated, summed
Compression ratio	50:1	uncompressed over compressed
Files	500
Single file	4 MiB
SKILL.md	256 KiB
Path length / depth	255 / 12
name	64 chars	lowercase, digits and single hyphens
description	1024 chars	40 minimum; 500 is the comfortable length
compatibility	500 chars

A package well inside these is the normal case — most skills are a few tens of kilobytes. Exceeding one is a refusal rather than a warning, so it is worth knowing before you publish.

Publish a skill

Zip your skill folder. The archive has to contain the folder itself — so my-skill/SKILL.md inside, not SKILL.md at the root.
Drag it onto the page. It is checked immediately and nothing is stored yet: you get the file tree on the left, the verdict in the middle, and what the package declares on the right.
Read the report. Anything wrong is listed with the file and line it came from.
Press Submit for review.

If your SKILL.md has no frontmatter, the page offers to write it: fill in the name and description and it hands you back a corrected .skill file. Download that — it is the package that gets published, so the next one you make should start from it.

Every version is reviewed before it is listed, including updates to a skill that is already public. The live version keeps serving while the new one waits, so publishing never takes your skill down. Your account shows where each one has got to.