npx-skills

npx-skills is a uv-installable Python wrapper around the upstream skills CLI.

This allows you to use skills.sh from within Python projects without a global dependency on Node/npm and impose versioning constraints on npx skills on a project-by-project basis.

It does this by shipping 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 add npx-skills
skills -h

OR use with uvx

uvx npx-skills

Versioning

The npx-skills package version tracks the upstream skills npm module version one-to-one. Installing npx-skills==1.4.8 gives you exactly skills@1.4.8 — the CLI payload is baked into the wheel at build time, so pinning npx-skills in your pyproject.toml or lockfile pins the underlying JavaScript CLI too. A new upstream skills release on npm has no effect on an already-installed npx-skills; you only move when you explicitly bump npx-skills. Packaging-only republishes of an existing upstream version use PEP 440 post-releases (e.g. 1.4.8.post1).

How it works

Refresh Vendored Artifacts

The repository includes a vendoring script that copies:

• the published skills package payload (package.json, bin/, dist/, README.md, ThirdPartyNoticeText.txt)
• 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 authenticates to PyPI using a project API token stored as the PYPI_API_TOKEN repository secret and consumed via UV_PUBLISH_TOKEN. The job runs in the pypi GitHub Actions environment, which can optionally be gated with required reviewers.

Upstream Sync Automation

A scheduled workflow at .github/workflows/auto-sync-upstream.yml runs daily (06:17 UTC) and keeps the vendored payload in lock-step with the upstream skills npm release. It is the mechanism that preserves the one-to-one version mapping described in the Versioning section above.

The job is implemented by the npx-skills-dev auto-sync-upstream command (packages/npx-skills-dev/src/npx_skills_dev/commands/auto_sync_upstream.py) and performs the following steps:

1. Reads the currently vendored version from src/npx_skills/vendor/manifest.json (upstream.version).
2. Fetches skills@latest from the npm registry.
3. If the versions match (and --force was not passed) the job exits as a no-op.
4. Otherwise it npm installs skills@<latest> into a temporary directory and runs scripts/vendor_upstream.py --source ... against it to refresh the vendored payload.
5. Rewrites the version in pyproject.toml and src/npx_skills/__init__.py to match the new upstream version.
6. Runs the unit test suite.
7. Commits src/npx_skills/vendor, src/npx_skills/__init__.py, and pyproject.toml with the message Auto-sync upstream skills@<version> and pushes to master.
8. Dispatches publish.yml against master, which builds wheels for every target platform and publishes them to PyPI.

The workflow can also be triggered manually via workflow_dispatch, with an optional force input that re-runs the full flow even when the upstream version is unchanged.

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/