Repository navigation
Publish the NodeSpace skill so users can actually install it: public import repo + automated release #2283
Description
Problem
A user cannot install the NodeSpace skill today. The app's auto-install path shells out via npx to @nodespaceai/skill, which has never existed on the npm registry:
GET https://registry.npmjs.org/@nodespaceai/skill → 404
#1184 ("Publish @nodespaceai/skill to npm") was closed as completed on 2026-05-19, but the publish step never ran — the issue was closed on the code landing, not on the artifact existing. The package itself is fully prepared: packages/skill/package.json declares the correct name at v0.2.0, with bin.nodespace-skill and a files allowlist covering dist, shims, and SKILL.md. Nothing is wrong with the code.
This blocks everything downstream. #2272 (skill instructions) and #1958 (graph as source of truth for the skill) are both unverifiable end-to-end until a user can actually install the thing in a real harness.
Scope
This issue covers distribution of the NodeSpace Agent Skill to user-launched external agents — the path where a user starts Claude Code, Codex, Gemini CLI, OpenCode, or Cursor themselves and wants NodeSpace available. Out of scope: the PTY path where NodeSpace launches the agent (ADR-032).
The ask: a public import repo
Publish the skill as a public repository users import into their agent, rather than (or in addition to) an npm package.
Under the Agent Skills standard (agentskills.io) a skill is just a folder — SKILL.md plus optional references/, scripts/, assets/. A public repo is the natural primitive for that: it's what the ~40 adopting harnesses and the emerging skill marketplaces consume, and it doesn't require an npm account, a scoped-package publish, or npx to be working on the user's machine.
Hard requirement: generated output, not hand-editable
The repo must be a publish target the release pipeline pushes to, never a place people edit directly. If it becomes hand-editable it is simply another representation of the same facts, which is the exact problem #1958 exists to eliminate.
There is a cautionary precedent in this org: the Homebrew tap was hand-maintained and went two months stale (v0.1.6 vs v0.2.0) before #2114. The same failure mode applies here, with the difference that a stale skill silently teaches agents wrong things rather than failing to install.
Requirements
-
@nodespaceai/skillis published and installable, or an explicit decision is recorded that the public repo replaces the npm path (and the app's auto-install is updated accordingly — it currently shells out tonpx) - If publishing to npm: confirm
--access public. A scoped package defaults to restricted, which 404s identically for unauthenticated users — it is possible to publish and observe no change. - A public repo exists containing a spec-compliant skill folder:
skills/nodespace/SKILL.mdwith requiredname+descriptionfrontmatter,namematching the directory name. - Frontmatter ships for all four installer targets, not Claude Code only —
packages/skill/src/agents.ts:31-54currently prepends frontmatter for Claude Code alone, leaving Codex/Gemini/OpenCode with spec-invalid folders (see NodeSpace skill instructions don't establish it as the source of truth for docs/specs — only teaches how to call functions #2272). - Publishing is automated in the release pipeline so the skill and the app that depends on it cannot drift apart. The current failure is exactly that drift.
- Installing from the published artifact is verified by hand in at least one real harness — the skill activates and can drive the
nodespaceCLI. - Closing criteria are the artifact existing and being installable, not the code landing. That distinction is what produced this issue.
Open questions
- Does the public repo replace npm, or complement it? The repo serves harness-native import; npm serves the app's programmatic auto-install. Both may be wanted, but then both need automating, and a single source must generate them.
- What is the repo's relationship to
nodespace-core? Presumably generated frompackages/skilland pushed on release, following thehomebrew-nodespacepattern (public distribution target, separate repo). - Versioning. How does a user know which NodeSpace version a given skill revision targets? The spec's optional
compatibilityfield (max 500 chars, for environment requirements) may be the right place. - Does the delivery-channel decision in Make the graph the source of truth for the NodeSpace skill, and decide how guidance reaches external agents #1958 change what gets published? If guidance is fetched from the graph rather than shipped in the body, the published artifact is much smaller — a stub plus frontmatter. Worth sequencing after that decision, or designing the pipeline so either outcome is publishable.
Related
- Skill auto-install fails: npx 404, @nodespaceai/skill not found on npm registry #2271 — skill auto-install fails with an npx 404. Same root cause; likely closes with this.
- Publish @nodespaceai/skill to npm: distributable skill package for PTY agent marketplaces #1184 — closed as completed 2026-05-19 without the package ever being published.
- Make the graph the source of truth for the NodeSpace skill, and decide how guidance reaches external agents #1958 — graph as source of truth for the skill; the delivery-channel decision affects what is published here.
- NodeSpace skill instructions don't establish it as the source of truth for docs/specs — only teaches how to call functions #2272 — skill description/instructions; unverifiable until the skill is installable.
- Homebrew tap is two months stale (v0.1.6 vs v0.2.0): cask is hand-maintained instead of generated on release #2114 — Homebrew tap went stale while hand-maintained. Same failure mode to avoid.
Activity
malibio commentedon Aug 24, 2026
Scope note: where an installed skill can actually be used.
The skill is self-bootstrapping — SKILL.md's Preflight Check (SKILL.md:50-67) already detects
command not found: nodespace, proposes the install (sh -c "$(curl -fsSL https://nodespace.ai/install.sh)" -- --no-gui) gated on explicit user confirmation, and handles the stale-$PATHcase. So "the CLI isn't there yet" is a handled condition, not a blocker, on any host where the skill can install and run it.The real constraint is data locality, not installability:
~/.claude/skills/; they load skills enabled for the claude.ai account, synced at session start. The install would succeed, but it runs on an ephemeral remote host with no access to the user's local graph, so the session gets an empty workspace. This is a property of local-first, not a distribution gap — worth documenting so it reads as intended behavior rather than a bug report waiting to happen.Distribution consequence: if the skill is ever published through the claude.ai account path (Customize in the Desktop sidebar / skills settings), that upload validates frontmatter strictly against the spec's six fields and hard-errors on unknown keys. Staying spec-minimal (
name,description,license,compatibility,metadata,allowed-tools) is what keeps that path open.Also worth carrying into #1958's delivery-channel decision: the preflight embeds a
curl | shinstall instruction. It is correctly gated on user confirmation today and ships in a reviewed file. If procedural guidance is fetched from the graph instead, an install command becomes something graph content can specify — a materially different trust proposition than one reviewed at publish time.malibio commentedon Aug 24, 2026
Handing this to @mstomar125. Recon notes so the stale parts of the description above don't cost a second investigation:
The npx premise is out of date. The description opens on the app shelling out to
npx @nodespaceai/skill. That was already fixed in #2143 —skill_setup.rsnow resolves the installer from a Tauri-bundledresources/skill/dist/install.js(staged byscripts/build-skill.ts) and runsbun <installer> installdirectly. There's even a regression test,installer_command_invokes_bun_directly_not_npx_or_npm, asserting npx/npm can't come back. So the app's auto-install needs nothing from npm, and #2271's root cause is already resolved.npm has no consumer left. Agent Skills are distributed as git repos, not npm packages — the spec defines a skill as a folder (
SKILL.md+ optionalreferences//scripts//assets/), and the harnesses that consume them read from a repo or local folder, not a registry. npm was only ever the right channel for thenpx-run installer binary, which #2143 removed. Recommend closing out the npm requirement with an explicit recorded decision (the description already allows for that) rather than publishing an artifact nothing reads.@nodespaceai/skillstill 404s as of today.No public skill repo exists yet. Confirmed against the org: the only public repos are
nodespace-coreandhomebrew-nodespace.packages/skillis the source inside the monorepo, not an importable target — a user can't import a monorepo subdirectory as a skill folder. SuggestNodeSpaceAI/nodespace-skillwithskills/nodespace/SKILL.mdinside, so thenamefrontmatter matches its directory as the spec requires.Real remaining work:
packages/skill/src/agents.ts:31-54prepends frontmatter for Claude Code only. Codex/Gemini/OpenCode get folders with noname/description, which are spec-invalid.Reusable precedent worth following:
scripts/homebrew-tap-push.tsalready implements clone → write → commit → push with token scrubbing on every path, and is shared byupdate-homebrew-cask.ts/update-homebrew-formula.ts. Those are driven byrelease.ymljobs and paired with ahomebrew-drift-check.yml— exactly the generated-target + drift-check shape this issue asks for, including the--push/ dry-run /drift-checkcommand convention.Sequencing vs #1958: agreed with the description's framing — build the pipeline to generate whatever
packages/skillcontains. #1958's delivery-channel decision changes the content (534-line body today vs. a thin stub later), not the pipeline, so this doesn't need to wait.Two things need @malibio: creating the public repo, and the push-token secret.
mstomar125 commentedon Aug 25, 2026
Frontend baseline: 227 test files passed, 4794 tests passed (79.17s).
mstomar125 commentedon Aug 25, 2026
PR #2296 implements this: #2296
Decision recorded:
@nodespaceai/skillwill not be published to npm; the publicNodeSpaceAI/nodespace-skillrepo is the sole distribution channel for external harness import. The desktop app's own install path has never depended on npm (it runs the built installer directly withbun, nevernpx/npm— seepackages/desktop-app/src-tauri/src/skill_setup.rs), so nothing currently blocks on the package landing on the registry.Live right now, not just code:
NodeSpaceAI/nodespace-skillcontainsREADME.mdand a spec-compliantskills/nodespace/SKILL.md+skills/nodespace/references/cli.md, pushed by actually running the newscripts/publish-skill-repo.ts --pushby hand as a one-time bootstrap (using my own credentials, not a CI secret) — the same code path the release pipeline will run, exercised for real rather than simulated. Verified against the live, freshly-cloned artifact with a validator built directly from the agentskills.io spec table: 16/16 checks pass.Publishing is automated:
release.ymlgets a newsync-skill-repojob, triggered the samerelease: [published]waysync-homebrew-caskis.Frontmatter for all four targets: already fixed in #2284 (merged just before this branch started) — verified still correct. Confirmed via the actual agentskills.io spec and Claude Code's own docs that
allowed-toolsis one of the spec's six universal frontmatter fields (not Claude-Code-specific, just "Experimental"), so sharing it across all four installer targets is spec-compliant.Open item:
SKILL_REPO_TOKEN(contents:write onNodeSpaceAI/nodespace-skill) needs to be provisioned as a repo secret before the automated pipeline can push on a real release — I can't create repo secrets myself. Until then,sync-skill-repowill fail loudly andnotify-failurewill open an issue, same asHOMEBREW_TAP_TOKENdid before it was set.Full details, verification method, and other open items are in the PR description.
mstomar125 commentedon Aug 25, 2026
Closing-requirement gap filled, for real: this was merged with the live-activation check honestly flagged as unverified (the implementing agent had no OAuth session / a non-writable keychain in its sandbox — confirmed independently by the coordinating session hitting the identical restriction). A real Claude Code session on a real machine has now run it:
This satisfies "verified by hand in at least one real harness — the skill activates and can drive the nodespace CLI" for real, not just by inspection. Remaining harness legs (Codex/Gemini/Cursor, and the daemon-down degradation case) are being tracked against #1958's own test matrix, not this issue.