skillpkg 🔧

Search, validate and install agent skills across agent runtimes. One CLI for the agent-skills ecosystem.

The agent-skills wave is here — OpenClaw, Claude, Codex, Cursor, Windsurf, Gemini CLI and DSH all read some flavor of SKILL.md — but the tooling layer around them is thin. skillpkg closes the gap with five commands:

pip install skillpkg-cli        # or: curl the single file, it's stdlib-only

skillpkg search pdf         # find skills on GitHub (sorted by stars, SKILL.md verified)
skillpkg check ./my-skill   # validate against the spec (frontmatter, size, layout)
skillpkg scan ./my-skill    # secrets + prompt-injection pre-check
skillpkg install OWNER/REPO # install into your agent's skills dir (auto-detects runtime)
skillpkg install anthropics/skills --skill pdf   # monorepos: install a sub-skill
skillpkg agents             # list supported runtimes and where they live
skillpkg list               # inventory installed skills across runtimes
skillpkg uninstall pdf      # remove an installed skill (asks for --yes)
skillpkg --version

Why

• Discovery is broken. Awesome-lists have 50-74K stars purely for listing skills. There's no npm search for skills — no way to check "does this repo actually contain a valid SKILL.md?" without opening 10 tabs.
• Quality is unverified. Agents truncate giant skill files, descriptions drive matching, missing frontmatter silently breaks loading. check catches all of it in one command.
• Trust is the real risk. Skills are arbitrary markdown + scripts executed with your agent's permissions. scan catches leaked credentials (GitHub/AWS/Slack tokens, private keys, JWTs) and prompt-injection patterns before you install.

Highlights

• Zero dependencies — pure Python stdlib, single file, python3 skillpkg.py just works
• Cross-agent — installs into whichever runtime it detects, or --agent <name> to pick
• Validation with teeth — required fields, name/description length limits, oversized-file warnings (agents truncate ~100KB), script-size sanity
• Security pre-check — 8 secret patterns, 6 injection patterns, runs inline after every install
• Search that verifies — GitHub search + live probe of each repo for an actual SKILL.md
• Hardened installer — path-traversal guards, symlink/never-extracted, tar-bomb size caps, hostile frontmatter names sanitized
• Monorepo aware — no root SKILL.md? skillpkg lists installable sub-skills and installs any of them via --skill

Example

$ skillpkg search pdf --limit 5
  STARS  SKILL                                        SKILL.MD  DESCRIPTION
----------------------------------------------------------------------------------------------------
  27898  virgiliojr94/book-to-skill                   ok        Turn any technical book PDF into a skill
   1126  bevibing/tutor-skills                        none      A Claude Code skill that turns PDFs...

$ skillpkg install anthropics/skills --skill pdf
  ✓ anthropics/skills → ~/.openclaw/skills/pdf (12 files)
  agent: openclaw · skill: pdf
  ✓ clean — no secrets or injection patterns found

Root install of a monorepo auto-lists what's available:

$ skillpkg install anthropics/skills
error: no SKILL.md at anthropics/skills root — looks like a monorepo.
  installable sub-skills:
    · skills/pdf
    · skills/docx
    · skills/mcp-builder
    ...
  → skillpkg install anthropics/skills --skill <name>

GitHub API rate limits

Unauthenticated GitHub API calls are capped at 60/hour — enough for a few searches, not for heavy use. skillpkg picks up GITHUB_TOKEN (or GH_TOKEN) automatically and lifts the cap to 5,000/hour:

export GITHUB_TOKEN=ghp_…   # read-only classic token is plenty

Supported runtimes

Missing your runtime? It's one line in AGENTS — PRs welcome.

The spec

skillpkg check validates against the agent skills spec:

• SKILL.md with YAML frontmatter: name (kebab-case, 2-64 chars) and description (≤1024 chars) required
• Keep SKILL.md focused; large detail belongs in bundled references/, scripts in scripts/

Install

# single file, stdlib only — copy it anywhere on PATH
curl -LO https://raw.githubusercontent.com/Exaggarate/skillpkg/main/skillpkg.py
chmod +x skillpkg.py && ./skillpkg.py --help

# or from PyPI (package name: skillpkg-cli — `skillpkg` is an abandoned name-squat)
pip install skillpkg-cli
pip install skillpkg-cli==0.2.2   # pin a version

# CN mirror note: default pip mirrors (mirrors.tencentyun.com etc.) can lag fresh
# uploads by ~an hour — if pip says "no versions", use the official index:
# pip install -i https://pypi.org/simple skillpkg-cli

Status

v0.2.2 — full package-manager surface (list, uninstall, --version), GITHUB_TOKEN support, 27 unit tests green, live-tested against real skills and the anthropics/skills monorepo (173K ⭐), published to PyPI via OIDC trusted publishing. Parser handles BOM files, folded YAML block scalars, empty fields; installer refuses traversal paths, symlinks/hardlinks, and archive bombs (20MB/file, 300MB/total caps).

Roadmap: lockfiles (skillpkg freeze), skill updates (skillpkg upgrade), registry index with auto-generated trust scores.

MIT © 2026