@kheif/quiver 1.1.0 → 1.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +64 -26
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -20,6 +20,14 @@ curl -fsSL https://raw.githubusercontent.com/kheif/quiver/main/install.sh | sh
|
|
|
20
20
|
|
|
21
21
|
The script downloads the latest release for your system, checks its checksum and installs `quiver` into `~/.local/bin`. Set `QUIVER_VERSION=v1.0.0` for a given release, or `QUIVER_INSTALL_DIR` for another folder. Run it again to update.
|
|
22
22
|
|
|
23
|
+
**Windows (PowerShell):**
|
|
24
|
+
|
|
25
|
+
```powershell
|
|
26
|
+
irm https://raw.githubusercontent.com/kheif/quiver/main/install.ps1 | iex
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The same steps for Windows: it installs `quiver.exe` into `%LOCALAPPDATA%\Programs\quiver` and adds that folder to your user `PATH`, without admin rights; open a new terminal afterwards. `QUIVER_VERSION` and `QUIVER_INSTALL_DIR` work the same way, set with `$env:QUIVER_INSTALL_DIR = '...'` before the line.
|
|
30
|
+
|
|
23
31
|
**npm (macOS, Linux and Windows):**
|
|
24
32
|
|
|
25
33
|
```sh
|
|
@@ -36,25 +44,27 @@ go install github.com/kheif/quiver/cmd/quiver@latest
|
|
|
36
44
|
|
|
37
45
|
The archives for every platform are also on the [releases page](https://github.com/kheif/quiver/releases). To build from a clone: `make build`, which writes `bin/quiver`.
|
|
38
46
|
|
|
47
|
+
**New versions.** Once a day, a command run in a terminal asks GitHub for the latest release, while it runs, and remembers the answer in `~/.quiver/state/version-check.json`. When a newer version is out, the command ends with one line on stderr, with the install command that matches how you installed Quiver. Nothing is shown for `quiver mcp`, with `--json`, outside a terminal or for development builds, and a failed check is silent. `quiver doctor` shows the latest version. Set `QUIVER_NO_UPDATE_CHECK=1` to turn the check off.
|
|
48
|
+
|
|
39
49
|
## Quickstart
|
|
40
50
|
|
|
41
51
|
```sh
|
|
42
|
-
# 1. Create the library in ~/.quiver
|
|
52
|
+
# 1. Create the library in ~/.quiver, register the MCP server with your
|
|
53
|
+
# assistants and import the skills you already have
|
|
43
54
|
quiver init
|
|
44
55
|
|
|
45
|
-
# 2.
|
|
46
|
-
quiver mcp install
|
|
47
|
-
|
|
48
|
-
# 3. In a project folder, write a skill for that project
|
|
56
|
+
# 2. In a project folder, write a skill for that project
|
|
49
57
|
cd ~/code/app
|
|
50
58
|
quiver new release-notes
|
|
51
59
|
```
|
|
52
60
|
|
|
61
|
+
In a terminal, `quiver init` asks before each step: registering the MCP server (`quiver mcp install`), importing the skills in `~/.claude/skills` for every folder, and importing those in the current project's `.claude/skills`. Any step can be skipped and run later. `quiver init --yes`, or a run outside a terminal, only creates `~/.quiver`; any other command creates it too.
|
|
62
|
+
|
|
53
63
|
`quiver new` opens the new `SKILL.md` in `$VISUAL` or `$EDITOR`. Write one sentence in `description` on when the assistant should use the skill, and the instructions below the frontmatter. Quiver commits the skill in `~/.quiver/local` and creates `~/code/app/.quiver.json`. Commit that file, so the project keeps its ID in every clone.
|
|
54
64
|
|
|
55
65
|
Then start Claude Code in `~/code/app` and ask for the task, such as "write the release notes for this version". The assistant sees `release-notes` in Quiver's skill list and loads it. You can also run it yourself as `/quiver:release-notes`.
|
|
56
66
|
|
|
57
|
-
`quiver status` shows what the assistant gets in the current folder.
|
|
67
|
+
`quiver status` shows what the assistant gets in the current folder. `quiver` alone sums it up in three lines, with a next step, before the command list.
|
|
58
68
|
|
|
59
69
|
## Concepts
|
|
60
70
|
|
|
@@ -63,7 +73,8 @@ Then start Claude Code in `~/code/app` and ask for the task, such as "write the
|
|
|
63
73
|
- **Skill IDs.** A local skill's ID is its folder name, such as `release-notes`. A skill from a source is `<source>/<skill>`, such as `anthropic/pdf`.
|
|
64
74
|
- **Assignments.** `registry.json` stores which skills are global and which projects get which skills. A folder that is not a project gets only the global skills.
|
|
65
75
|
- **Assignments are yours.** They live in your `~/.quiver`, not in the project. A teammate who clones the project gets its `.quiver.json`, but not your skills or assignments. To share skills, put them in a git repository that everyone adds with `quiver source add`.
|
|
66
|
-
- **Projects.** A project is the folder with `.quiver.json`, found by walking up from the current folder. It is created the first time you assign a skill there. The ID survives moves and renames. Git worktrees of one repository share the committed `.quiver.json`, so they are one project with the same skills. If a folder is copied, both copies have the same ID; `quiver status` warns, and `quiver projects split` gives the copy its own.
|
|
76
|
+
- **Projects.** A project is the folder with `.quiver.json`, found by walking up from the current folder. It is created the first time you assign a skill there; in a terminal, `add`, `new` and `import` first ask `Register <folder> as a project?` (`--yes` skips the question). The ID survives moves and renames. Git worktrees of one repository share the committed `.quiver.json`, so they are one project with the same skills. If a folder is copied, both copies have the same ID; `quiver status` warns, and `quiver projects split` gives the copy its own.
|
|
77
|
+
- **One copy of each skill.** A skill that Quiver serves and that Claude Code also loads by itself, from `~/.claude/skills`, the project's `.claude/skills` or an enabled plugin, may be loaded twice. `quiver import` therefore deletes the originals it copied, except those committed in a project's git, which teammates may still need (`--keep` keeps every original). `quiver status` and `quiver doctor` report the copies they find, by name or by content, and `quiver doctor --fix` deletes those not committed in git and not in a plugin.
|
|
67
78
|
- **Always-on skills.** A skill added with `--always` is loaded before the assistant's first reply, for style or rules that apply to every answer. See the limits below.
|
|
68
79
|
|
|
69
80
|
## Commands
|
|
@@ -72,26 +83,33 @@ Run `quiver help <command>` for the details and examples of each.
|
|
|
72
83
|
|
|
73
84
|
| Command | What it does |
|
|
74
85
|
|---|---|
|
|
75
|
-
| `quiver
|
|
86
|
+
| `quiver` | Show the project here, how many skills it is served and a next step, then the command list. |
|
|
87
|
+
| `quiver init` | Create the Quiver home and anything missing in it; in a terminal, then offer to register the MCP server and import existing skills (`--yes`: only create the home). |
|
|
76
88
|
| `quiver new <name>` | Create a local skill and assign it to this project (`--global`: every folder, `--none`: nowhere). |
|
|
77
89
|
| `quiver edit <id>` | Open a local skill in your editor, then check and commit it. |
|
|
78
90
|
| `quiver delete <id>` | Delete a local skill from the library. An assigned skill needs `--force`. |
|
|
79
|
-
| `quiver
|
|
80
|
-
| `quiver import
|
|
81
|
-
| `quiver import <
|
|
91
|
+
| `quiver fork <source/skill>` | Copy a source skill into your own skills to change it; `--as` names the copy. The copy takes the original's place wherever it is assigned, and `quiver update` no longer changes it. |
|
|
92
|
+
| `quiver import` | Move the skills in this project's `.claude/skills` into the library (`--deep`: every folder of the project). Originals committed in git are kept; `--keep` keeps all. |
|
|
93
|
+
| `quiver import <folder>` | Move every skill in a folder and its subfolders into the library. Files that are not valid skills are listed at the end. |
|
|
94
|
+
| `quiver import <skill>` | Move one skill: its `SKILL.md`, its folder or a markdown file with frontmatter. `--name` renames it. |
|
|
82
95
|
| `quiver add <id>...` | Assign skills to this project, or to every folder with `--global`. `--always` makes them always-on. |
|
|
83
96
|
| `quiver remove <id>...` | Unassign skills. They stay in the library. |
|
|
84
97
|
| `quiver list` | List the library's skills and where each is assigned (`--source`, `--unassigned`, `--json`). |
|
|
85
|
-
| `quiver
|
|
86
|
-
| `quiver
|
|
98
|
+
| `quiver show <id>` | Show a skill: where it comes from, where it is assigned, its files and its `SKILL.md` (`--json`). |
|
|
99
|
+
| `quiver search <text>` | Search the IDs, names and descriptions of every library skill, also unassigned ones, and show whether each is served here (`--json`). |
|
|
100
|
+
| `quiver status` | Show the project in this folder and the skills served here, with a warning for each copy Claude Code also loads (`--json`). |
|
|
101
|
+
| `quiver where <id>` | Show where one skill is assigned (`--json`). |
|
|
87
102
|
| `quiver source add <repo>` | Clone a skill repository: `owner/repo` (GitHub), a git URL or a local path. |
|
|
88
103
|
| `quiver source list` | List sources with their skill count and commit. |
|
|
89
104
|
| `quiver source remove <name>` | Delete a source. Refuses while its skills are assigned, unless `--force`. |
|
|
90
|
-
| `quiver update [<name>...]` |
|
|
91
|
-
| `quiver
|
|
92
|
-
| `quiver
|
|
93
|
-
| `quiver
|
|
94
|
-
| `quiver
|
|
105
|
+
| `quiver update [<name>...]` | Download the latest skills of all or some sources and show what would change: the changed files of each assigned skill, with scripts marked "needs review". Asks before it applies changes to assigned skills (`--yes` does not ask, `--diff` shows the whole change). Pinned skills stay at their commit. |
|
|
106
|
+
| `quiver pin <source/skill> [<commit>]` | Keep a source skill at its current commit, or the one given, so `quiver update` leaves it alone. `quiver unpin` goes back to the source's current version. |
|
|
107
|
+
| `quiver sync init <git-remote>` | Keep the Quiver home in a git remote, so your other machines get the same skills, sources and assignments. Run it on each machine; then `quiver sync` commits, pulls and pushes, merges assignment changes from both machines and clones sources added elsewhere. |
|
|
108
|
+
| `quiver projects` | List projects (`--json`); `rename`, `forget` and `split` manage them. |
|
|
109
|
+
| `quiver doctor` | Check the library, the assignments, copies of served skills in Claude Code and its setup (`--fix` applies the safe fixes). |
|
|
110
|
+
| `quiver mcp install [assistant...]` | Register the MCP server with every supported assistant that is installed, or only with the assistants named. See [MCP server](#mcp-server). |
|
|
111
|
+
| `quiver mcp uninstall [assistant...]` | Remove it from them, or only from the assistants named. |
|
|
112
|
+
| `quiver mcp config` | Print the MCP config entry for any other assistant. |
|
|
95
113
|
| `quiver mcp` | Run the MCP server. Assistants start this. |
|
|
96
114
|
| `quiver completion <shell>` | Print the completion script for `bash`, `zsh`, `fish` or `powershell`. |
|
|
97
115
|
|
|
@@ -105,7 +123,21 @@ quiver completion zsh > "${fpath[1]}/_quiver"
|
|
|
105
123
|
|
|
106
124
|
## MCP server
|
|
107
125
|
|
|
108
|
-
`quiver mcp install`
|
|
126
|
+
`quiver mcp install` sets up every supported assistant that is installed. Name assistants to set up only those, such as `quiver mcp install codex cursor`. The supported assistants:
|
|
127
|
+
|
|
128
|
+
| Assistant | Name | What it changes |
|
|
129
|
+
|---|---|---|
|
|
130
|
+
| Claude Code | `claude-code` | Runs `claude mcp add --scope user quiver -- <path to quiver> mcp`. |
|
|
131
|
+
| Codex | `codex` | Runs `codex mcp add quiver -- <path to quiver> mcp`, which writes `~/.codex/config.toml` (or `$CODEX_HOME`). The Codex CLI and app share it. |
|
|
132
|
+
| Cursor | `cursor` | Adds `quiver` to `mcpServers` in `~/.cursor/mcp.json`. |
|
|
133
|
+
| Claude Desktop | `claude-desktop` | Adds `quiver` to `mcpServers` in `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). |
|
|
134
|
+
| Antigravity | `antigravity` | Adds `quiver` to `mcpServers` in `~/.gemini/config/mcp_config.json`, which the Antigravity CLI (`agy`) reads. |
|
|
135
|
+
|
|
136
|
+
An assistant counts as installed when its command (`claude`, `codex`) is on `PATH`, or when its config folder exists (`~/.gemini/antigravity-cli` for Antigravity). In the JSON files, every other key stays as it is, including an `env` of the `quiver` entry, and the old file is saved next to it as `<file>.quiver-backup`. A file that is not valid JSON is reported and never overwritten. When Codex already has a `quiver` entry, its `env` is kept too. Restart the assistant afterwards. `quiver doctor` checks the entry of each installed assistant. Every assistant but Claude Code gets the path of the binary itself, never the npm launcher, because desktop apps do not see your shell's `PATH` and so cannot find `node`. Cursor passes the skill list to the model and starts the server in the workspace folder, so project skills work there.
|
|
137
|
+
|
|
138
|
+
**Codex, Claude Desktop and Antigravity** use Quiver's skills only when you ask for them in the prompt, such as "check the quiver skills for this"; `quiver mcp install` says so. Codex loads an MCP server's tools, and with them its instructions, only when the model searches for them. Antigravity puts the instructions in a file the model rarely reads. Claude Desktop drops them. Once asked, Codex and Antigravity also follow the always-on skills; Claude Desktop does not. Codex and Antigravity start the server in the project folder, so project skills work there. See [docs/spike-mcp-clients.md](docs/spike-mcp-clients.md).
|
|
139
|
+
|
|
140
|
+
For any other assistant, `quiver mcp config` prints the entry:
|
|
109
141
|
|
|
110
142
|
```json
|
|
111
143
|
{ "mcpServers": { "quiver": { "command": "/path/to/quiver", "args": ["mcp"] } } }
|
|
@@ -113,7 +145,7 @@ quiver completion zsh > "${fpath[1]}/_quiver"
|
|
|
113
145
|
|
|
114
146
|
The server serves the project of the folder it is started in, or of `$QUIVER_PROJECT` when that is set. It logs to `~/.quiver/logs/`.
|
|
115
147
|
|
|
116
|
-
Claude Code starts the server in the project folder. Other assistants may start it somewhere else, such as your home folder; there it serves only the global skills. Set `QUIVER_PROJECT` in that assistant's MCP config to serve a project's skills.
|
|
148
|
+
Claude Code starts the server in the project folder. Other assistants may start it somewhere else, such as your home folder; there it serves only the global skills. Cursor starts it in the workspace folder. Claude Desktop never starts it in a project. Set `QUIVER_PROJECT` in that assistant's MCP config to serve a project's skills.
|
|
117
149
|
|
|
118
150
|
**Instructions.** When a session starts, the server tells the assistant which skills exist here: their IDs and descriptions, the always-on skills, and that new skills are saved with `create_skill`.
|
|
119
151
|
|
|
@@ -121,10 +153,12 @@ Claude Code starts the server in the project folder. Other assistants may start
|
|
|
121
153
|
|
|
122
154
|
| Tool | Input | Result |
|
|
123
155
|
|---|---|---|
|
|
124
|
-
| `list_skills` | — |
|
|
156
|
+
| `list_skills` | — | Every skill served here, project skills first: ID, name, whole description, `global` or `project`, and whether it is always-on. |
|
|
125
157
|
| `get_skill` | `id` | The skill's instructions, its extra files and its folder. |
|
|
126
158
|
| `get_skill_file` | `id`, `path` | One extra file of a skill, such as `references/checklist.md`. Large and binary files return their path instead. |
|
|
127
159
|
| `create_skill` | `name`, `description`, `body`, `scope` (`project` or `global`), optional `files` | Creates a local skill, commits it and assigns it. In a folder that is not a project yet, `project` scope registers it. |
|
|
160
|
+
| `update_skill` | `id`, any of `description`, `body`, `files` (an empty content deletes the file) | Changes a local skill and commits it as `update <name> (via MCP)`. Other frontmatter fields are kept. Source skills are read-only. |
|
|
161
|
+
| `search_skills` | `query` | Searches the whole library, also skills not assigned here, and marks each match as assigned here (`global` or `project`) or not. The assistant may suggest an unassigned skill, but asks before using it. |
|
|
128
162
|
|
|
129
163
|
**Prompts.** Every served skill is also an MCP prompt. In Claude Code it appears as `/quiver:<id>`; text after the command is passed to the skill as the task.
|
|
130
164
|
|
|
@@ -141,20 +175,24 @@ Claude Code starts the server in the project folder. Other assistants may start
|
|
|
141
175
|
Skills give instructions to your assistant, and a skill can include scripts the assistant may run. A skill from a source is code you run on your own machine.
|
|
142
176
|
|
|
143
177
|
- Add only sources you trust, and read their skills before you assign them.
|
|
144
|
-
- `quiver update`
|
|
145
|
-
- Source skills are read-only in Quiver. To change one,
|
|
146
|
-
- `create_skill`
|
|
178
|
+
- `quiver update` downloads new commits before it applies them, lists the changed files of every assigned skill, marks scripts and executable files "needs review", and asks before it applies the changes. Read them with `quiver update --diff`; answering no leaves the source as it was. To review changes to a skill before it reaches your sessions, pin it with `quiver pin` and move the pin when you have read them.
|
|
179
|
+
- Source skills are read-only in Quiver. To change one, fork it into your own skills with `quiver fork`.
|
|
180
|
+
- `create_skill` and `update_skill` let the assistant write skills into your library. A global skill's description reaches the assistant in every folder, so review new global skills with `quiver list` and `quiver edit`. Every change is a commit in `~/.quiver/local` (in `~/.quiver` once you use `quiver sync`), so `git -C ~/.quiver/local log -p` shows it and `git revert` undoes it.
|
|
181
|
+
|
|
182
|
+
To report a vulnerability in Quiver itself, see [SECURITY.md](SECURITY.md).
|
|
147
183
|
|
|
148
184
|
## Uninstall
|
|
149
185
|
|
|
150
186
|
The last command deletes your own skills too. To keep them, first push `~/.quiver/local` somewhere: it is a git repository.
|
|
151
187
|
|
|
152
188
|
```sh
|
|
153
|
-
quiver mcp uninstall # remove the MCP server from
|
|
189
|
+
quiver mcp uninstall # remove the MCP server from every assistant
|
|
154
190
|
rm "$(command -v quiver)" # remove the binary; with npm: npm uninstall -g @kheif/quiver
|
|
155
191
|
rm -rf ~/.quiver # delete the library
|
|
156
192
|
```
|
|
157
193
|
|
|
194
|
+
On Windows, after `quiver mcp uninstall`, delete `%LOCALAPPDATA%\Programs\quiver` and `%USERPROFILE%\.quiver`, and remove the folder from your user `PATH` in the environment variables settings.
|
|
195
|
+
|
|
158
196
|
Projects keep their `.quiver.json`; delete it there if you no longer need it.
|
|
159
197
|
|
|
160
198
|
## Development
|
|
@@ -165,7 +203,7 @@ make test # go test ./..., including the end-to-end suite in e2e/
|
|
|
165
203
|
make lint # golangci-lint
|
|
166
204
|
```
|
|
167
205
|
|
|
168
|
-
See [PROJECT.md](PROJECT.md) for the design and [tasks/](tasks/README.md) for the plan.
|
|
206
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md), [PROJECT.md](PROJECT.md) for the design and [tasks/](tasks/README.md) for the plan.
|
|
169
207
|
|
|
170
208
|
## License
|
|
171
209
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kheif/quiver",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.3.0",
|
|
4
4
|
"description": "Central skill manager for AI assistants, delivered as an MCP server.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"keywords": [
|
|
@@ -26,11 +26,11 @@
|
|
|
26
26
|
"node": ">=18"
|
|
27
27
|
},
|
|
28
28
|
"optionalDependencies": {
|
|
29
|
-
"@kheif/quiver-darwin-arm64": "1.
|
|
30
|
-
"@kheif/quiver-darwin-x64": "1.
|
|
31
|
-
"@kheif/quiver-linux-arm64": "1.
|
|
32
|
-
"@kheif/quiver-linux-x64": "1.
|
|
33
|
-
"@kheif/quiver-win32-arm64": "1.
|
|
34
|
-
"@kheif/quiver-win32-x64": "1.
|
|
29
|
+
"@kheif/quiver-darwin-arm64": "1.3.0",
|
|
30
|
+
"@kheif/quiver-darwin-x64": "1.3.0",
|
|
31
|
+
"@kheif/quiver-linux-arm64": "1.3.0",
|
|
32
|
+
"@kheif/quiver-linux-x64": "1.3.0",
|
|
33
|
+
"@kheif/quiver-win32-arm64": "1.3.0",
|
|
34
|
+
"@kheif/quiver-win32-x64": "1.3.0"
|
|
35
35
|
}
|
|
36
36
|
}
|