Documentation

Introduction

Most AI coding agents — Claude Code, Cursor, Gemini CLI, GitHub Copilot — read from a shared global skill registry at ~/.agents/.skill-lock.json. When you set up skills on one machine, they live in that file. Move to another machine and you're starting from scratch.

Quiver fixes that. It writes your lock file to a private GitHub Gist and replays the installs on any other machine you sign in on. There is no Quiver server, no new account, and no proprietary backend — the Gist on your own GitHub account is the source of truth.

Install

Quiver is distributed via npm and requires Node.js 18 or newer.

$ npm install -g usequiver

Verify the install:

$ quiver --version
quiver/0.2.4 darwin-arm64 node-v20.11.1

Prefer not to install globally? You can also run it with npx: npx usequiver sync. The CLI behaves identically; only the invocation differs.

Quick Start

From a machine that already has the skills you want to back up:

$ quiver login
→ opens browser to github.com/login/device
✓ authenticated as nublson

$ quiver push
reading ~/.agents/.skill-lock.json … 7 skills
writing gist://nublson/quiver-skill-lock.json
✓ pushed rev #23

Then, on every other machine you log into:

$ quiver login
✓ authenticated as nublson

$ quiver sync
✔ anthropics/skills        (2 skills, 6.4s)
✔ vercel-labs/agent-skills (1 skill,  7.8s)
✔ prisma/skills            (1 skill,  7.5s)
3 skills added, 4 already up to date

That's the whole loop. Run quiver push when you add new skills, quiver sync on machines that need to catch up.

Authentication

Quiver authenticates through GitHub's device flow — the same OAuth dance the official gh CLI uses. You'll be given a short code and a URL to paste it into. Quiver never sees your password, and the token never leaves your machine.

Required scopes

Quiver requests the minimum scopes needed to read and write a private Gist:

• gist — to create and update the quiver-skill-lock.json Gist on your account.
• read:user — to display your username in quiver whoami.

Commands

Quiver exposes six commands. None of them take more than one or two flags. The signatures below use <required> for positional arguments and [--optional] for flags.

login

push

sync

What happens

1. Fetches the remote lock from your private Gist
2. Computes the diff: skills present remotely but missing locally
3. Groups missing skills by sourceUrl — one npx skills add invocation per repo
4. Runs all groups in parallel with a live progress line per source
5. Re-reads the local lock file and upserts only the skills that succeeded
6. Prints a summary: N skills added, M already up to date

If one source group fails, the others still complete and their skills are written to the lock file. The command exits with an error listing which sources failed.

Example output

$ quiver sync
✔ anthropics/skills          (4 skills, 9.1s)
✔ vercel-labs/agent-skills   (2 skills, 7.8s)
✔ supabase/agent-skills      (2 skills, 7.1s)
✔ prisma/skills              (4 skills, 7.5s)
✔ better-auth/skills         (2 skills, 6.7s)
25 skills added, 0 already up to date

status

$ quiver status
local  rev #19 · 4 skills
remote rev #23 · 7 skills
────────────────────────────────
+ frontend-design       v1.2.0
+ pdf-reading           v0.4.1
+ react-best-practices  v2.0.0
  test-coverage         v1.1.0
  commit-style          v0.3.0

remove

whoami

$ quiver whoami
user      nublson
gist      8f3a921e4b · quiver-skill-lock.json
device    work-imac (darwin-arm64)
last sync 2026-05-18 14:22:09 +00:00 · rev #23

Lock file

Quiver does not invent a new file format. It reads and writes the same ~/.agents/.skill-lock.json that npx skills already produces. A typical entry looks like this:

{
  "version": 2,
  "updated": "2026-05-18T14:22:09Z",
  "skills": {
    "frontend-design": {
      "source":  "github:anthropics/skills",
      "version": "1.2.0",
      "sha":     "4f1b…"
    }
  }
}

Quiver only writes to the skills object and the updated timestamp. It never touches keys it doesn't recognize, so it's safe to use alongside future skill-lock extensions.

Gist as storage

On first push, Quiver creates a single private Gist named quiver-skill-lock.json on your account. Every push is a new Gist revision, which gives you a free audit log: visit the Gist on github.com and you can browse every change.

There is exactly one Gist per user. Quiver finds it by listing your Gists and matching the filename — so renaming it on GitHub will break sync until you rename it back.

Conflicts

Quiver is intentionally simple: last push wins. If two machines push within the same minute, the later revision overwrites the earlier one in the Gist. The earlier revision is still visible in the Gist's history and can be recovered manually.

Sync is the safer direction. It never deletes local skills unless you pass --prune, so pulling stale data can only add — never lose — skills.

Config

Quiver reads optional configuration from ~/.config/quiver/config.json:

{
  "deviceName":    "work-imac",
  "lockFilePath":  "~/.agents/.skill-lock.json",
  "gistFilename":  "quiver-skill-lock.json",
  "autoPushOnAdd": false
}

Environment variables

Exit codes

FAQ

Can I share a lock file with my team?

Not yet. Quiver is built around your Gist on your GitHub account. Team-shared skill sets are tracked in issue #14 — open to design feedback.

Is my data private?

Yes. The Gist is created private. Quiver requests the gist scope (which covers both public and private), but only ever writes private Gists. You can verify this in gist.github.com/mine.

Does it work on Windows?

Yes — Quiver runs on macOS, Linux, and Windows (PowerShell and WSL). Paths are normalized internally, so a lock file pushed from macOS replays cleanly on Windows.

What happens if I'm offline?

quiver sync and quiver push exit with code 5 and a clear error message. Your local lock file is never touched on network failure.