SKILL.md6.4 KB
---
name: llmskillhub
description: >
How one can create llm skill and publish it to llmskillhub.com
license: MIT
metadata:
llmskillhub:
version: 0.1.0
categories: [documents]
keywords: []
capabilities:
network: false
filesystem: read
shell: false
secrets: []
---
# LLM Skill Hub
Guide to creating an LLM skill and publishing it to llmskillhub.com.
## When to reach for this
You want to package reusable AI agent instructions — a workflow, a tool
integration, a domain-specific process — so other people can install and
use them. Without a published skill, those instructions live in a single
conversation or a private CLAUDE.md and nobody else benefits.
## Process
### 1. Create the skill directory
Every skill is a folder with one required file (`SKILL.md`) and up to four
optional directories.
```
my-skill/
├── SKILL.md # required — manifest + agent instructions
├── scripts/ # optional — helper scripts the skill invokes
├── references/ # optional — reference docs, data files
├── assets/ # optional — images, templates, static files
└── examples/ # optional — usage examples
```
Only `SKILL.md` is required, and only those four directory names are recognized.
### 2. Write the SKILL.md frontmatter
The file starts with YAML frontmatter between `---` fences. Two fields are
required; the rest are optional but recommended.
```yaml
---
name: my-skill
description: >
One-line summary of what it does and when to use it.
Include phrases users would search for. 40–1024 characters.
license: MIT
compatibility: "Requires Python 3.11+"
metadata:
llmskillhub:
version: 0.1.0
categories: [code-generation]
keywords: [refactoring, python]
repository: https://github.com/you/my-skill
homepage: https://example.com
authors: ["Your Name"]
capabilities:
network: false
filesystem: read # none | read | read-write
shell: false
secrets: [] # named secrets the skill needs
---
```
**Field rules:**
| Field | Required | Notes |
|-------|----------|-------|
| `name` | yes | Lowercase letters, digits, single hyphens only. Must match the folder name. Max 64 chars. |
| `description` | yes | 40–1024 characters. No angle brackets. Explain what it does *and when to use it*. |
| `license` | no | License name or path to bundled LICENSE file. |
| `compatibility` | no | Environment requirements. Max 500 chars. |
| `metadata.llmskillhub.version` | no | Semver. Must match at publish time. |
| `metadata.llmskillhub.categories` | no | Array for discovery/filtering. |
| `metadata.llmskillhub.keywords` | no | Array for search indexing. |
| `metadata.llmskillhub.capabilities` | no | Declares what the skill accesses. Shown on the listing page. |
### 3. Write the SKILL.md body
After the frontmatter, write markdown that an AI agent will follow as
instructions. Structure it with these sections:
**`## When to reach for this`** — Describe the situation in the user's words.
An agent decides from this section whether the skill applies at all.
**`## Process`** — Numbered steps in execution order. One step per numbered
item. Start with inspection ("look before changing"), then the work, then
verification ("how to tell it worked" — not just "check it").
**`## What not to do`** — Failure modes you already know about. This section
is worth more than the happy path because the happy path is usually guessable.
Write for an agent, not a human reader. Be specific: include exact commands,
file paths, expected output. If a step has conditional branches, spell them
out. If a step invokes a tool, name the tool and its parameters.
### 4. Package as a .skill file
A `.skill` file is a ZIP archive. The skill folder must be the top-level
entry — `SKILL.md` should not sit at the archive root.
```bash
# From the parent directory of your skill folder:
cd /path/to/parent
zip -r my-skill.skill my-skill/
```
This produces `my-skill.skill` containing `my-skill/SKILL.md`,
`my-skill/scripts/`, etc.
**Size limits:**
| Constraint | Limit |
|------------|-------|
| Compressed archive | 5 MiB |
| Uncompressed total | 25 MiB |
| Compression ratio | 50:1 max |
| File count | 500 |
| Single file | 4 MiB |
| SKILL.md alone | 256 KiB |
| Path depth | 12 levels |
### 5. Publish to llmskillhub.com
1. Sign in at llmskillhub.com.
2. Go to the publish page (`/new`).
3. Drag your `.skill` file onto the page. Validation runs immediately — you
see the file tree, a diagnostic verdict, and your declared metadata.
4. If your `SKILL.md` has no frontmatter, the page offers to write it: fill
in name and description and it hands back a corrected `.skill` file.
5. Review everything, then press **Submit for review**.
Every submission is unpacked, scanned for credentials and prompt injection,
and read by a person before it goes live. Publishing never removes existing
live versions — new releases go through review while the current version
stays available.
### 6. Users install the skill
Users download the `.skill` file and unzip it into their agent's skills
directory:
```bash
# Project-level (only this project)
unzip my-skill.skill -d .claude/skills/
# Global (all projects for this user)
unzip my-skill.skill -d ~/.claude/skills/
```
Or via the CLI:
```bash
llmsh install yourname/my-skill
```
### 7. Update an existing skill
Bump the `version` in `metadata.llmskillhub`, repackage, and publish again.
The new version goes through review. The previous version stays live until
the update is approved.
## What not to do
- **Don't put SKILL.md at the ZIP root.** The folder itself must be the
top-level entry: `my-skill/SKILL.md`, not just `SKILL.md`.
- **Don't embed secrets or credentials.** The review scan catches these and
rejects the submission.
- **Don't use angle brackets in the description field.** They are not allowed.
- **Don't write vague process steps.** "Set up the environment" is useless to
an agent. "Run `pip install -r requirements.txt` in the project root" is
actionable.
- **Don't skip the capabilities declaration.** It tells installers what your
skill will access and is shown on the listing page. Omitting it erodes trust.
- **Don't exceed size limits.** Large assets belong in a separate download,
not in the skill archive.
- **Don't use a name that doesn't match your folder name.** The `name` field
and the top-level directory in the ZIP must be identical.