Shipping NanoClaw Skills as npm Packages

In why I chose NanoClaw and how I extend it, I covered isolation and the product surfaces I bolted on: hosthooks, webchat, agenttrace, adminapi. This post is the delivery story. How I add those capabilities without waiting on upstream core, and without treating my fork like a junk drawer of hand patches.

NanoClaw’s trunk stays small on purpose. I still need product-shaped features. Sitting in an upstream PR queue is the wrong loop for that.

Skills over features is policy, not vibes

NanoClaw is explicit about this. The README says it plainly: Don’t add features. Add skills. CONTRIBUTING backs that up. Source changes that get accepted are bug fixes, security fixes, and simplifications. New capabilities belong as skills. Trunk ships the registry and infrastructure. Channels, providers, and most everything else land as skill-installed code in the operator’s fork.

That is not a soft preference. Core PRs whose only job is to hardcode a product feature are discouraged by design. I agree with the design. I also need to ship.

The queue is real

Busy is not a complaint. It is the operating reality of a popular project. Snapshot for nanocoai/nanoclaw as of August 1, 2026:

• About 557 open pull requests, 470 merged all-time, and 1,305 closed without merge
• July saw on the order of 74 merges, while about 377 open PRs were already older than June 1
• Open PRs labeled as skills (Type: Skill, PR: Skill, or Type: Community Skill): about 38 unique, with a median age around 84 days. Plenty sit past 30 days; a chunk past 90

What does get merged often lands the same day. In a recent sample of 100 merged PRs, the median time open was roughly zero days. Maintainers are shipping priorities. Community skill PRs still wait.

So even when you do the “right” thing and open a skill PR against NanoClaw, review can take weeks or months. I needed a path that honors their skills-first rule and does not block my desk on that queue.

npm package that installs the skill

The pattern across the Artificer Innovations NanoClaw packages is the same: an npm package with a CLI that installs a skill into your fork. It does not silently mutate anything in postinstall. You opt in with verbs:

pnpm add nanoclaw-<name>
pnpm exec nanoclaw-<name> sync-skill
pnpm exec nanoclaw-<name> install
pnpm exec nanoclaw-<name> verify

sync-skill copies the bundled skill into .claude/skills/add-<name>/. install copies adapters, patches known call sites, and scaffolds any .env keys the feature needs. verify re-checks that the patches and peers still look right after a trunk upgrade. uninstall reverses the same work.

Important distinction: these packages do patch the operator’s fork. They do not change upstream NanoClaw core. That is the whole point. Your fork gets a recipe of skills. Upstream trunk stays thin.

I use this for hosthooks, webchat, agenttrace, adminapi, agenthosts, the local process runtime driver, and the Fly.io driver. Same CLI shape. Same skill directory layout. Conventions live in the package design notes we keep next to those repos; the NanoClaw packages page and Labs list what is published.

Idempotent install and uninstall

If the installer is not safe to re-run, it is not an installer. It is a one-shot script you will regret. The bar across these packages:

• Marker blocks. Patches land between // @nanoclaw-<pkg>:<name>:begin and :end. A full re-run is a no-op. A half-applied block fails closed instead of guessing.
• Unambiguous anchors. Transforms look for one clear call site. Missing or duplicated anchors throw. No silent “best effort” edits.
• Stage, then commit. Compute every file transform first. Write with atomic renames. Roll back if a commit fails. Hosthooks and agenthosts are the strictest examples.
• Env scaffolding skips what you already set. New keys default fail-closed (ENABLED=false and friends). Uninstall only removes keys it scaffolded.
• upgrade is install again. Re-apply is the upgrade path. After you pull trunk, run verify. If NanoClaw moved an anchor, fail loudly.
• Peer checks. Webchat and agenttrace require hosthooks. Process and Fly drivers require agenthosts. Install fails closed if the dependency registry is missing.
• Uninstall reverses the markers and copied files. Shared helpers stay when a sibling package still needs them.

I care about that last mile because I reinstall these things constantly while the agent team reviews and ships. An installer that lies on the second run wastes more time than writing the patch by hand.

What that bought me

I already wrote about the product stack in extending without forking: hosthooks as the shared extension points, webchat and agenttrace hanging off those hooks, adminapi as a thin boot insert for HTTP control. The same delivery model covers agenthosts and the process / Fly drivers listed on Labs. Different jobs, same install contract.

The agents that review those packages are named here. They only stay useful if I can add a capability, tear it out, and put it back without babysitting a 500-line hand merge.

The deal

NanoClaw’s deal is skills-first. I take that seriously. npm packages with explicit, idempotent skill installers are how I honor that deal without sitting in a 557-PR queue for every desk feature I need.

If you want help standing up an agent scaffold your team can actually operate, book a call. The packages are MIT, on npm, and linked from Labs.