npx-skills 1.4.8

uv-installable wrapper for the vercel-labs/skills CLI with an embedded Node runtime

npx-skills

npx-skills is a uv-installable Python wrapper around the upstream skills CLI. It ships a vendored Node runtime and the published JavaScript CLI payload, then forwards execution to the embedded runtime so users do not need a separate Node install.

Install

uv tool install .
skills --help

The package installs the same command names as the npm package:

• skills
• add-skill

Refresh Vendored Artifacts

The repository includes a vendoring script that copies:

• the published skills package payload (bin, dist, package.json, docs)
• the package's runtime node_modules dependencies
• the current platform's node binary

By default it will use a built package root if you pass --source, or fall back to the newest cached ~/.npm/_npx/*/node_modules/skills install.

uv run python scripts/vendor_upstream.py

Or point it at a specific built package root:

uv run python scripts/vendor_upstream.py --source /path/to/node_modules/skills

If you point --source at the upstream git repo, it must already contain dist/cli.mjs.

To rebuild only the embedded Node runtime from the payload already committed in this repo, point --source at the vendored package root:

uv run python scripts/vendor_upstream.py --source src/npx_skills/vendor/skills

Build

The wheel is intentionally platform-specific because it includes a native node binary.

uv build

Release Automation

GitHub Actions builds one wheel per native runner target:

• Linux x64 via manylinux_2_28
• Linux arm64 via manylinux_2_28
• macOS x64
• macOS arm64
• Windows x64
• Windows arm64

The workflow lives at .github/workflows/wheels.yml. It reuses the committed skills payload, re-vendors the Node runtime for the current runner architecture, runs the test suite, builds wheels with uv (cibuildwheel via uvx on Linux), smoke-tests the built wheel, and uploads wheel artifacts for manual release use.

This project intentionally publishes wheels only. An sdist would not be portable without re-vendoring the embedded Node runtime for the target platform.

Publishing runs through a separate manual workflow at .github/workflows/publish.yml. It invokes the wheel builder in the same workflow run, then publishes from GitHub after all target wheels succeed. The intended entrypoint is the npx-skills-dev helper:

uv run --package npx-skills-dev npx-skills-dev publish-to-pypi

Or via make:

make publish

Use --ref <branch> to dispatch the workflow from a specific branch and --dry-run to build and validate without publishing.

The GitHub publish job is designed for PyPI trusted publishing. Configure the npx-skills project with a trusted publisher for the publish.yml workflow, and optionally gate the pypi environment with required reviewers.

Layout

The vendored runtime is kept under src/npx_skills/vendor/:

vendor/
  manifest.json
  node/<platform>/node
  skills/
    package.json
    bin/cli.mjs
    dist/
    node_modules/