Skill Wiki v0.1.0
中 GitHub ↗

Docs / usage / publish-install

On this page

Publish & install

Distribution is HTTP-only — anything that implements the registry contract is a registry. The reference server is one file.

Stand up a registry

# Run the reference registry on port 4000 (SQLite-backed Skill store).
bun run packages/registry/src/index.ts --port 4000

# Or use Docker if you prefer:
docker run -p 4000:4000 \
  -v $(pwd)/registry-data:/data \
  ghcr.io/skill-wiki/registry:0.1.0

Author a Skill manifest

Add pack.yaml to the root of your Skill:

name: "@my/cooking"
version: "1.0.0"
description: "Cooking knowledge — methods, terms, and rules."
license: Apache-2.0

prime-version: "1.0"
sources: "primes/sources"
compiled: "primes/compiled"

Publishing via CLI (one-command flow)

To list your Skill on the public marketplace at skill-wiki.github.io, you don't need to fork or hand-edit YAML. The CLI does it for you: 

# From the root of your corpus repo (must contain pack.yaml + compiled/)
prime publish-marketplace \
  --description "Typed atoms for X domain" \
  --tags "x,y,z"

# Preview the YAML entry without forking / pushing:
prime publish-marketplace --dry-run --description "..." --tags "..."

What it does:

  1. Reads pack.yaml for name / version / compiled subdir.
  2. Detects the GitHub repo from git remote get-url origin.
  3. Forks skill-wiki/skill-wiki.github.io via gh repo fork (idempotent).
  4. Clones the fork, appends an entry to data/skills.yaml, branches, commits, pushes.
  5. Opens a PR via gh pr create and prints the URL.

Requires the GitHub CLI (gh) to be installed and authenticated (gh auth login). If anything goes wrong mid-flow, your branch is pushed to your fork — open the PR by hand from there.

Publish (registry server)

# Compile first (publish bundles compiled/)
bun scripts/build-atom-dirs.ts \
  --src primes/sources \
  --out primes/compiled

# Publish
prime publish --remote http://localhost:4000

# What it does:
# 1. Tarball the Skill (excluding node_modules, .git, .l2-cache.json)
# 2. Compute sha256
# 3. POST /publish with manifest + tarball
# 4. Print the assigned URL

Install

# Install into ./.primes/
prime install @my/cooking --remote http://localhost:4000

# With a version range
prime install '@my/cooking@^1.0' --remote http://localhost:4000

# Install everything declared in SKILL.md frontmatter
prime install --remote http://localhost:4000

Versioning

  • Skill semver: patch = atom edits, minor = added atoms, major = removed atoms or removed verbs.
  • Atom semver: internal versioning per-atom via version: "x.y.z" field.
  • Resolution: latest matching range; lockfile is .primes/lock.yaml.

Verify the install

prime ls --dir .primes
# → @my/cooking @ 1.0.0

prime list --dir .primes/@my/cooking/primes/compiled
# → ... atoms ...

Round-trip test

The full round-trip is in scripts/test-registry-roundtrip.sh:

bash scripts/test-registry-roundtrip.sh
# 1. Boot a clean registry
# 2. Publish examples/recipes
# 3. Install in a fresh dir
# 4. Diff compiled artifacts
# 5. Tear down

Authentication

The reference registry uses bearer tokens for POST /publish; reads are public. Issue tokens via the registry CLI: 

bun run packages/registry/src/cli.ts token create --org skill-wiki
# → token: pri_token_...

# Use it
prime publish --remote http://localhost:4000 --token pri_token_...

Hosting options

  • Self-host: run the reference registry on any Node-capable VM. ~50 MB RAM.
  • Cloudflare Workers: the reference impl ports cleanly with R2 for Skill storage.
  • Static + CDN: for read-only distribution, a public S3 bucket + manifest index works.