zalpha / llmskillhub

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.

---
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:

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.

# 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:

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:

# 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:

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.