Metadata-Version: 2.4
Name: npx-skills
Version: 1.5.5
Summary: uv-installable wrapper for the vercel-labs/skills CLI with an embedded Node runtime
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# npx-skills

`npx-skills` is a `uv`-installable Python wrapper around the upstream
[`skills`](https://github.com/vercel-labs/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

```bash
uv add npx-skills
skills -h
```

OR use with uvx

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

```bash
uv run python scripts/vendor_upstream.py
```

Or point it at a specific built package root:

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

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

```bash
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`](.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`](.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:

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

Or via `make`:

```bash
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`](.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](#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 install`s `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/`:

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