Metadata-Version: 2.4
Name: npx-skills
Version: 1.4.8
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. 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

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

```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 is designed for PyPI trusted publishing. Configure the
[`npx-skills`](https://pypi.org/project/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/`:

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