Metadata-Version: 2.4
Name: skillpkg-cli
Version: 0.2.2
Summary: Search, validate and install agent skills across agent runtimes (OpenClaw, Claude, Codex, Cursor, Windsurf, Gemini CLI, DSH)
Home-page: https://github.com/Exaggarate/skillpkg
Author: Exaggarate
License: MIT
Project-URL: Source, https://github.com/Exaggarate/skillpkg
Project-URL: Issues, https://github.com/Exaggarate/skillpkg/issues
Keywords: agent-skills skills cli openclaw claude codex cursor windsurf gemini dsh linter security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

# skillpkg 🔧
[![CI](https://github.com/Exaggarate/skillpkg/actions/workflows/ci.yml/badge.svg)](https://github.com/Exaggarate/skillpkg/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/skillpkg-cli)](https://pypi.org/project/skillpkg-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```bash
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

```console
$ 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:

```console
$ 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:

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

## Supported runtimes

| Agent | Skills dir |
|---|---|
| OpenClaw | `~/.openclaw/skills` |
| Claude | `~/.claude/skills` |
| Codex | `~/.codex/skills` |
| Cursor | `~/.cursor/skills` |
| Windsurf | `~/.codeium/windsurf/skills` |
| Gemini CLI | `~/.gemini/skills` |
| DSH | `~/.dsh/plugins` |

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

## The spec

`skillpkg check` validates against the [agent skills spec](https://agentskills.io):

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

```bash
# 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
