skillhub

the package manager for AI agent skills

Lint, scaffold, search, and install SKILL.md agent skills for Claude Code, Cursor, Codex, and Gemini CLI — from one tiny, zero-dependency CLI.

---

$ skillhub lint ./skills
[OK]    skills/hello-world/SKILL.md
[WARN ] skills/pitch-review/SKILL.md: 'name' ('pitch-reviewer') does not match parent directory ('pitch-review')
[ERROR] skills/draft/SKILL.md: missing required 'description' in frontmatter
[ERROR] skills/draft/SKILL.md: body is empty; a skill needs instructions

Summary: 3 file(s), 2 error(s), 1 warning(s).

$ skillhub search founder
Found 1 skill pack(s) for 'founder':

  founder-skills  (Hayatelin/founder-skills)
    A pack of agent skills for solo founders: fundraising memos, investor updates...
    tags: founder, startup, fundraising, business, finance
    install: skillhub install Hayatelin/founder-skills

What it is

skillhub is a single-file-feel, zero-dependency Python CLI for working with Agent Skills — the SKILL.md files that tools like Claude Code, Cursor, Codex, and Gemini CLI load to teach an agent a new capability.

A SKILL.md is just markdown with YAML frontmatter:

---
name: pdf-extractor
description: Extracts text and tables from PDF files for downstream analysis.
---

# PDF Extractor

## Instructions
1. ...

skillhub treats those files like packages: it lints them, scaffolds new ones, lists what you have installed, searches a curated registry, and installs skill packs straight from GitHub.

Why (the 2026 skills-pack trend)

In 2026 every serious agent runtime converged on the same idea: instead of stuffing one giant system prompt, you ship a folder of skills, and the agent loads the right one on demand. That turned skills into shareable artifacts — and suddenly people needed the boring-but-essential tooling that every package ecosystem grows: a linter, a scaffolder, a registry, an installer.

That's skillhub. It is to SKILL.md what npm is to package.json and pip is to pyproject.toml — except it has zero dependencies, runs anywhere Python 3.8 runs, and never phones home (except when you explicitly install).

Quickstart

# Run it without installing (clone the repo, then):
python -m skillhub --help

# Or install it:
pip install .
skillhub --help

# Validate skills in the current tree
skillhub lint .

# Scaffold a new skill
skillhub new my-first-skill

# Search the bundled registry
skillhub search security

# Install a skill pack from GitHub into .claude/skills
skillhub install Hayatelin/devsecops-skills --tool claude

No virtualenv, no requirements.txt, no wheels to fetch. The whole tool is the Python standard library.

Commands

skillhub lint [PATH ...]

Validate one or more SKILL.md files. PATH may be a file, a skill directory, or a tree to recurse (default: .). Checks:

• frontmatter is present and parseable
• name is present and kebab-case
• name matches the parent directory (warn on mismatch)
• description is present (error if missing) and not too long (warn if > 1024 chars)
• body is non-empty
• no leftover template placeholders (TODO, <describe ...>, etc.)

Exits non-zero if any errors are found. Add --json for machine-readable output.

$ skillhub lint examples/skills/hello-world
[OK]    examples/skills/hello-world/SKILL.md

Summary: 1 file(s), 0 error(s), 0 warning(s).

skillhub list [--tool claude|cursor|codex|gemini|all]

Discover installed skills in known locations (.claude/skills/*/SKILL.md, .cursor/skills/*/SKILL.md, .codex/skills, .gemini/skills, and the global ~/.skillhub/skills). Prints name, description, and path. --json supported.

skillhub new <name> [--dir .]

Scaffold <dir>/<name>/SKILL.md from a good template with valid frontmatter and Purpose / When to use / Instructions / Examples sections. Refuses to overwrite an existing skill.

$ skillhub new invoice-parser
Created invoice-parser/SKILL.md
Next: edit the description and Instructions, then run:
  skillhub lint invoice-parser

skillhub info <path-or-skill-dir>

Parse and pretty-print a skill's metadata plus the first lines of its body. --json supported.

skillhub search <query>

Search the bundled, offline registry (skillhub/registry.json) of known skill packs by name, description, or tags. Prints the exact install command for each match. Works with no network connection.

skillhub install <owner/repo> [--tool claude] [--dir .] [--force]

Download a repo's tarball from GitHub (main, falling back to master), then extract every **/SKILL.md (with its folder) into the target tool's skills directory. Network errors are reported clearly; nothing else touches the network.

$ skillhub install Hayatelin/founder-skills --tool cursor
Installing Hayatelin/founder-skills into ./.cursor/skills ...
Installed 3 skill(s):
  - ./.cursor/skills/fundraising-memo
  - ./.cursor/skills/investor-update
  - ./.cursor/skills/pitch-review

How it works & limits

• Frontmatter parser. skillhub ships a tiny hand-rolled YAML parser that supports exactly what SKILL.md needs: key: value scalars, quoted strings, block lists (- item), and inline flow lists ([a, b]). It is not a full YAML implementation — that is by design, to stay dependency-free.
• Registry is offline & curated. search reads a JSON file bundled in the package. It is intentionally small and hand-picked; it is not a live index.
• Install is best-effort. It fetches public GitHub tarballs over HTTPS and guards against path-traversal in the archive. Private repos, auth, and versioning/pinning are out of scope for now.
• Tool detection is convention-based. skillhub looks in the standard per-tool directories; it does not parse each tool's private config format.

Contributing

Issues and PRs welcome at github.com/Hayatelin/skillhub.

Run the test suite (standard-library unittest, fully offline):

python -m unittest discover -s tests

The CI workflow runs exactly that on Python 3.8 and 3.11. Please keep the tool dependency-free and ASCII-safe in code.

License

MIT © 2026 VictorLin. See LICENSE.