Skill Wiki v0.1.0
EN GitHub ↗

文档 / usage / publish-install

本页目录

发布与安装

分发只走 HTTP。任何实现了 registry 契约的服务都算 registry，参考实现只有一个文件。

跑起一个 registry

# Run the reference registry on port 4000 (SQLite-backed pack 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

写 Skill manifest

在 Skill 根目录加一份 pack.yaml：

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"

一行命令发布到 marketplace

想把自己的 Skill 挂到公开的 skill-wiki.github.io marketplace 上，不需要手动 fork、也不用改 YAML： 

# 在你的 corpus 仓库根目录执行（需要有 pack.yaml + compiled/）
prime publish-marketplace \
  --description "X 领域的 typed atom 集合" \
  --tags "x,y,z"

# 只想看一眼会写出什么 YAML、不真的 fork 和 push：
prime publish-marketplace --dry-run --description "..." --tags "..."

它做的事：

  1. 读 pack.yaml，拿到 name / version / compiled 子目录。
  2. 从 git remote get-url origin 推断 GitHub 仓库地址。
  3. 用 gh repo fork 幂等 fork skill-wiki/skill-wiki.github.io。
  4. 克隆 fork、往 data/skills.yaml 追加一条记录、切分支、commit、push。
  5. 调 gh pr create 开 PR，并把 PR URL 打回终端。

前置条件：装好 GitHub CLI（gh）并完成 gh auth login。如果中途出错，分支已经推到你的 fork 上，可以手动开 PR 收尾。

发布到 registry 服务

# 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 pack (excluding node_modules, .git, .l2-cache.json)
# 2. Compute sha256
# 3. POST /publish with manifest + tarball
# 4. Print the assigned URL

安装

# 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

版本管理

  • Skill 层 semver：patch 表示改原子内容，minor 表示新增原子，major 表示删原子或删 verb。
  • 原子层 semver：每个原子用自己的 version: "x.y.z" 字段单独管理版本。
  • 版本解析：取匹配范围内的最新版本，锁文件落在 .primes/lock.yaml。

验证安装结果

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

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

闭环测试

完整流程封装在 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

鉴权

参考 registry 对 POST /publish 走 bearer token 鉴权，读操作完全公开。 用 registry CLI 即可签发 token： 

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_...

托管方式

  • 自托管：参考 registry 可以直接跑在任何支持 Node 的虚机上，内存占用约 50 MB。
  • Cloudflare Workers：参考实现可以平滑迁移过去，Skill 存储改用 R2 即可。
  • 静态文件 + CDN：只读分发场景下，一个公开的 S3 桶外加一份 manifest 索引就够用。