@toolmesh/agent-deck 0.0.0-stage → 0.1.1
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/LICENSE +21 -0
- package/README.md +433 -2
- package/bin/agent-deck.js +2 -0
- package/package.json +42 -4
- package/src/agents.mjs +87 -0
- package/src/cli.mjs +484 -0
- package/src/gitignore.mjs +109 -0
- package/src/hosts/claude-native.mjs +113 -0
- package/src/hosts/copy.mjs +279 -0
- package/src/init.mjs +65 -0
- package/src/install.mjs +395 -0
- package/src/lockfile.mjs +133 -0
- package/src/materialize.mjs +184 -0
- package/src/outdated.mjs +91 -0
- package/src/paths.mjs +63 -0
- package/src/plugins.mjs +158 -0
- package/src/profiles.mjs +80 -0
- package/src/project.mjs +110 -0
- package/src/sources/fetch.mjs +250 -0
- package/src/sources/locate.mjs +396 -0
- package/src/sources/spec.mjs +254 -0
- package/src/state.mjs +41 -0
- package/src/status.mjs +137 -0
- package/src/worktree.mjs +52 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Julien La Vinh
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,434 @@
|
|
|
1
|
-
#
|
|
1
|
+
# agent-deck
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@toolmesh/agent-deck)
|
|
4
|
+
[](https://github.com/tilap/agent-deck/actions/workflows/ci.yml)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+
A package manager for AI agent capabilities. It installs skills, agents, commands, rules,
|
|
8
|
+
hooks and MCP servers into a project for **Claude Code** and **Cursor**, pins them in a
|
|
9
|
+
lockfile, and reinstalls exactly the same thing later: on another machine, in CI, or for
|
|
10
|
+
an agent runner.
|
|
11
|
+
|
|
12
|
+
## Why
|
|
13
|
+
|
|
14
|
+
Skills, agent prompts and MCP configuration are usually copied by hand from project to
|
|
15
|
+
project, or buried in the application code. They drift, nobody knows which version a
|
|
16
|
+
project runs, and a fix in one place never reaches the others.
|
|
17
|
+
|
|
18
|
+
agent-deck moves the agent side out of your code:
|
|
19
|
+
|
|
20
|
+
- **Capabilities live in plugin marketplaces**, as ordinary git repositories, npm
|
|
21
|
+
packages, archives or local folders, versioned and reviewed on their own.
|
|
22
|
+
- **A project only states what it wants** in `ai-plugin.json`, the way `package.json`
|
|
23
|
+
lists dependencies.
|
|
24
|
+
- **A lockfile pins what it got**: commit, version, content digest. `--frozen` refuses
|
|
25
|
+
anything that does not match, so CI and teammates run the same agents.
|
|
26
|
+
- **Both hosts get the same plugins.** One request, installed natively in Claude Code and
|
|
27
|
+
copied into `.cursor/` for Cursor.
|
|
28
|
+
- **Roles are profiles.** A builder, a tester and a reviewer each get their own prompt and
|
|
29
|
+
plugins on top of a shared base.
|
|
30
|
+
|
|
31
|
+
## Install
|
|
32
|
+
|
|
33
|
+
Requires Node.js 22.14 or later and `git`.
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
npm i -g @toolmesh/agent-deck
|
|
37
|
+
# or run it without installing
|
|
38
|
+
npx @toolmesh/agent-deck --help
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Quick start
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
agent-deck init
|
|
45
|
+
agent-deck add owner/marketplace-repo@plugin-name --ref v0.1.0
|
|
46
|
+
agent-deck add anthropics/skills --skill pdf
|
|
47
|
+
agent-deck add ./plugins/my-plugin
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`init` wires `.gitignore`, `AGENTS.md` and `CLAUDE.md`. `add` writes the request to
|
|
51
|
+
`ai-plugin.json`, pins it in `ai-plugin.lock.json` and installs it for Claude Code and
|
|
52
|
+
Cursor. Commit both files; `.ai/installed/` stays on the machine and comes back with
|
|
53
|
+
`agent-deck install`.
|
|
54
|
+
|
|
55
|
+
On another machine, or in CI:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
agent-deck install --frozen
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
While editing a plugin in a local checkout, install that working tree and leave the
|
|
62
|
+
committed request as it is:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
agent-deck link /path/to/marketplace@plugin-name
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Each profile is an agent role (builder, tester, reviewer) with its own prompt and plugins,
|
|
69
|
+
installed on top of the base:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
agent-deck profile new builder
|
|
73
|
+
agent-deck add anthropics/skills --skill pdf --profile builder
|
|
74
|
+
agent-deck profile use builder
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`profile use` installs the base plus that profile, points Claude at the profile prompt and
|
|
78
|
+
writes the Cursor rule from the same file. Open a new Claude session, or reload Cursor, to
|
|
79
|
+
pick it up. See [Profiles](#profiles).
|
|
80
|
+
|
|
81
|
+
## How it maps to npm
|
|
82
|
+
|
|
83
|
+
| npm | agent-deck | Commit |
|
|
84
|
+
| ------------------- | ------------------------------------------------------------------- | ------ |
|
|
85
|
+
| `package.json` | `ai-plugin.json` — what you ask for | yes |
|
|
86
|
+
| `package-lock.json` | `ai-plugin.lock.json` — commits, versions, digests, contents | yes |
|
|
87
|
+
| `node_modules/` | `.ai/installed/plugins/<id>/` — each plugin, normalized | no |
|
|
88
|
+
| — | `.ai/installed/state.json` — what agent-deck wrote on this machine | no |
|
|
89
|
+
| — | `.ai/profiles/<name>/` — agent profiles (see [Profiles](#profiles)) | yes |
|
|
90
|
+
| — | `ai-plugin.local.json` — links to working trees | no |
|
|
91
|
+
|
|
92
|
+
## Commands
|
|
93
|
+
|
|
94
|
+
```
|
|
95
|
+
agent-deck init [--commit-copies]
|
|
96
|
+
agent-deck add <source> [--skill <name>]… [--ref <ref>] [--profile <name>]
|
|
97
|
+
agent-deck remove <id> [--profile <name>]
|
|
98
|
+
agent-deck install [--frozen]
|
|
99
|
+
agent-deck update [<id>…] [--profile <name>]
|
|
100
|
+
agent-deck status
|
|
101
|
+
agent-deck outdated
|
|
102
|
+
agent-deck link <folder>[@<plugin>] [--skill <name>]…
|
|
103
|
+
agent-deck unlink <id>
|
|
104
|
+
agent-deck profile new|use|off|list [<name>]
|
|
105
|
+
agent-deck materialize --out <dir> [--profile <name>] [--json]
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
| Command | Effect |
|
|
109
|
+
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
110
|
+
| `init` | Wire agent-deck into the project: see [Set up a project](#set-up-a-project) |
|
|
111
|
+
| `add` | Resolve, install, and lock. The request is written only if that succeeds. Creates `ai-plugin.json` if needed |
|
|
112
|
+
| `remove` | Drop the request, its normalized tree, its installed files, and its lock entry |
|
|
113
|
+
| `install` | Make the project match the base and the active profile, pinned by the locks. `--frozen` for CI |
|
|
114
|
+
| `update` | Resolve refs again (all, or the ids given) and rewrite the lock |
|
|
115
|
+
| `status` | Active profile, every request (`[base]`, `[profile x]`, `[link]`) and its lock pin, and every mismatch between request, lock, `.ai/installed/`, hosts, and `.gitignore`. Never touches the network. Exit 1 on errors |
|
|
116
|
+
| `outdated` | Lock pins vs what each ref or range points to now, and newer release tags. Exit 1 when behind |
|
|
117
|
+
| `link` | Install a local folder (a git checkout, uncommitted files included, or any folder of skills). Not locked |
|
|
118
|
+
| `unlink` | Drop the link; reinstall the committed request if there is one |
|
|
119
|
+
| `profile` | Agent profiles: see [Profiles](#profiles) |
|
|
120
|
+
| `materialize` | Build the base and one profile into a folder, for a tool that launches agents: see [Materialize](#materialize) |
|
|
121
|
+
|
|
122
|
+
Every command takes `-C <dir>` (`--project`), `--force` (let copy mode replace a file agent-deck
|
|
123
|
+
did not write), and `--help`. An option a command does not take is refused.
|
|
124
|
+
|
|
125
|
+
Advanced options: `add --id <id> --path <dir in source> --sha256 <hex> --no-install`,
|
|
126
|
+
`remove --keep-files` and `unlink --keep-files`, `link --id <id> --path <dir> --no-install`.
|
|
127
|
+
|
|
128
|
+
## Set up a project
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
agent-deck init # once per project; safe to run again
|
|
132
|
+
agent-deck init --commit-copies # same, but commit the copies in .claude/ and .cursor/
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
| File | `agent-deck init` | Afterwards |
|
|
136
|
+
| ---------------- | -------------------------------------------------------- | --------------------------------------------------------------------- |
|
|
137
|
+
| `ai-plugin.json` | Created when missing | `agent-deck add` / `remove` |
|
|
138
|
+
| `.gitignore` | Created when missing; agent-deck's managed block written | `agent-deck install` rewrites the block |
|
|
139
|
+
| `AGENTS.md` | Created when missing | `agent-deck install` rewrites its `## Skills` block |
|
|
140
|
+
| `CLAUDE.md` | Created when missing, or given an `@AGENTS.md` line | `agent-deck profile use` / `off` add or drop `@.ai/current/prompt.md` |
|
|
141
|
+
|
|
142
|
+
`CLAUDE.md` imports `AGENTS.md`, so Claude Code reads what Cursor reads: write project
|
|
143
|
+
instructions once, in `AGENTS.md`.
|
|
144
|
+
|
|
145
|
+
agent-deck's block in `.gitignore` sits between two markers and is rewritten whole; lines
|
|
146
|
+
outside it are never touched:
|
|
147
|
+
|
|
148
|
+
```
|
|
149
|
+
# >>> @toolmesh/agent-deck (managed: rewritten by agent-deck install)
|
|
150
|
+
.ai/installed/
|
|
151
|
+
.ai/current
|
|
152
|
+
ai-plugin.local.json
|
|
153
|
+
.cursor/rules/agent-deck-profile.mdc
|
|
154
|
+
/.cursor/skills/commit
|
|
155
|
+
…
|
|
156
|
+
# <<< @toolmesh/agent-deck
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Besides the local files, it lists every path copy mode writes in `.claude/` and `.cursor/`
|
|
160
|
+
for every plugin the base **or any profile** pins, read from the committed locks, for every
|
|
161
|
+
host that is not `off`: like `node_modules`, they come back with `agent-deck install`, so the
|
|
162
|
+
repository holds only the intent (`ai-plugin.json`, locks, profiles). The block does not
|
|
163
|
+
depend on the active profile or on which CLIs a machine has: `agent-deck profile use` never
|
|
164
|
+
changes `.gitignore`, and adding to or removing from a profile that is not active updates it. `agent-deck init --commit-copies` sets
|
|
165
|
+
`"gitignoreCopies": false` in `ai-plugin.json`: the copies stay out of the block and get
|
|
166
|
+
committed, so a fresh clone works in Cursor before `agent-deck install`. Shared files agent-deck edits
|
|
167
|
+
(`.mcp.json`, `.cursor/mcp.json`, `AGENTS.md`, `CLAUDE.md`) are never ignored.
|
|
168
|
+
|
|
169
|
+
`agent-deck install` never creates `.gitignore`; `agent-deck status` warns when the block is missing.
|
|
170
|
+
|
|
171
|
+
## Profiles
|
|
172
|
+
|
|
173
|
+
A profile is an agent role — builder, tester, reviewer — with its own prompt and plugins,
|
|
174
|
+
on top of the base every profile gets:
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
ai-plugin.json, ai-plugin.lock.json the base (committed)
|
|
178
|
+
.ai/profiles/builder/prompt.md the builder's prompt (committed)
|
|
179
|
+
.ai/profiles/builder/ai-plugin.json, …lock.json the builder's plugins (committed)
|
|
180
|
+
.ai/current → profiles/builder the active profile (local)
|
|
181
|
+
.ai/installed/ installed plugins and state (local)
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
agent-deck profile new builder # .ai/profiles/builder/ with prompt.md and an empty request
|
|
186
|
+
agent-deck add anthropics/skills --skill pdf --profile builder
|
|
187
|
+
agent-deck profile use builder # base + builder installed; then a new Claude session / reload Cursor
|
|
188
|
+
agent-deck profile use tester # builder's plugins leave, tester's arrive, the base is untouched
|
|
189
|
+
agent-deck profile off
|
|
190
|
+
agent-deck profile list # * marks the active one
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
`agent-deck add --profile x` on a profile that is not active resolves and locks the plugin in
|
|
194
|
+
`.ai/profiles/x/` without installing it. A plugin id belongs to the base or to a profile, not both.
|
|
195
|
+
|
|
196
|
+
The prompt follows `.ai/current`: `profile use` adds `@.ai/current/prompt.md` to
|
|
197
|
+
`CLAUDE.md` once, and writes `.cursor/rules/agent-deck-profile.mdc` (`alwaysApply`) from the
|
|
198
|
+
profile's `prompt.md`. `profile off` removes both. `.ai/current` and the Cursor rule are
|
|
199
|
+
in agent-deck's `.gitignore` block.
|
|
200
|
+
|
|
201
|
+
## Materialize
|
|
202
|
+
|
|
203
|
+
`agent-deck materialize` builds what an agent needs to run, without installing anything in the
|
|
204
|
+
project: the base and one profile (or the base alone), as pinned by their locks, each
|
|
205
|
+
plugin in `<out>/<id>/` with its Claude Code and Cursor manifests.
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
agent-deck materialize --profile builder --out /tmp/agents/builder --json
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
```json
|
|
212
|
+
{
|
|
213
|
+
"profile": "builder",
|
|
214
|
+
"prompt": "/path/to/project/.ai/profiles/builder/prompt.md",
|
|
215
|
+
"out": "/tmp/agents/builder",
|
|
216
|
+
"plugins": [
|
|
217
|
+
{
|
|
218
|
+
"id": "git-workflow",
|
|
219
|
+
"path": "/tmp/agents/builder/git-workflow",
|
|
220
|
+
"integrity": "sha256-…",
|
|
221
|
+
"components": { "skills": ["commit", "…"], "…": [] }
|
|
222
|
+
}
|
|
223
|
+
]
|
|
224
|
+
}
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
- Always frozen: a request a lock does not pin, or content that differs from its
|
|
228
|
+
integrity, is refused.
|
|
229
|
+
- `--profile` names the profile; `.ai/current` is not read, so several profiles can be
|
|
230
|
+
built side by side. Local links are ignored: the output is what is committed.
|
|
231
|
+
- Writes only in `--out`: nothing in `.claude/`, `.cursor/`, the locks, `.ai/installed/`,
|
|
232
|
+
`.gitignore`, or `AGENTS.md`. A plugin already in `--out` with the locked integrity is
|
|
233
|
+
kept; a folder of a plugin no longer requested is removed.
|
|
234
|
+
|
|
235
|
+
Load the result with `claude --plugin-dir <out>` (Claude loads every plugin in the folder)
|
|
236
|
+
or one `cursor-agent --plugin-dir <out>/<id>` per plugin, and pass `prompt` as the
|
|
237
|
+
agent's instructions.
|
|
238
|
+
|
|
239
|
+
## Sources
|
|
240
|
+
|
|
241
|
+
| You type | Request |
|
|
242
|
+
| ----------------------------------- | ------------------------------------------------------------- |
|
|
243
|
+
| `owner/repo@plugin` | `{ "source": "github:owner/repo", "plugin": "plugin" }` |
|
|
244
|
+
| `owner/repo` | a single-plugin repository, or a repository of skills |
|
|
245
|
+
| `owner/repo --skill a --skill b` | only those skills |
|
|
246
|
+
| `https://github.com/owner/repo` | same as `owner/repo` |
|
|
247
|
+
| `git+https://gitlab.com/t/r.git#v1` | `{ "source": "git:https://gitlab.com/t/r.git", "ref": "v1" }` |
|
|
248
|
+
| `git@host:team/repo.git` | any git host over SSH |
|
|
249
|
+
| `npm:@scope/pkg@^2` | `{ "source": "npm:@scope/pkg", "version": "^2" }` |
|
|
250
|
+
| `https://…/kit.zip` (or `.tar.gz`) | `{ "source": "archive:https://…/kit.zip" }` |
|
|
251
|
+
| `./plugins/name` | `{ "source": "path:plugins/name" }` |
|
|
252
|
+
| `./plugins@name` | `{ "source": "path:plugins", "plugin": "name" }` |
|
|
253
|
+
|
|
254
|
+
The id defaults to the plugin name (or the repository name); `--id` overrides it.
|
|
255
|
+
Without `--ref`, agent-deck takes the default branch and locks the commit it found.
|
|
256
|
+
|
|
257
|
+
`./path` is a directory inside the project. The request stores `path:<relative>` (no leading
|
|
258
|
+
`./`) and the lock stores that path plus the integrity of the normalized tree. `agent-deck install`
|
|
259
|
+
re-reads the directory; `--frozen` refuses when the files no longer match the lock. A path
|
|
260
|
+
without `./` is a GitHub `owner/repo`. A folder outside the project is `agent-deck link`.
|
|
261
|
+
|
|
262
|
+
Inside a fetched source, agent-deck finds the plugin the way Claude Code and Cursor do:
|
|
263
|
+
|
|
264
|
+
- `.claude-plugin/marketplace.json` or `.cursor-plugin/marketplace.json`, with every
|
|
265
|
+
Claude Code plugin source: relative path (and `metadata.pluginRoot` bare names),
|
|
266
|
+
`github`, `url`, `git-subdir`, `npm`, and `archive`. A source object is fetched in turn
|
|
267
|
+
and its own commit is locked as `nested`. `command` sources are refused.
|
|
268
|
+
- `strict` semantics: an entry without `plugin.json` is the manifest (e.g. the skill
|
|
269
|
+
lists of `anthropics/skills`); a `strict: false` entry that declares components next
|
|
270
|
+
to a `plugin.json` is a conflict.
|
|
271
|
+
- Custom component paths in `.claude-plugin/plugin.json` or `.cursor-plugin/plugin.json`
|
|
272
|
+
(`skills`, `agents`, `commands`, `rules`, `hooks`, `mcpServers`).
|
|
273
|
+
- No marketplace: `plugins/<name>/`, a plugin at the root, a `skills/*/SKILL.md`
|
|
274
|
+
repository, or a single `SKILL.md` at the root.
|
|
275
|
+
|
|
276
|
+
## What gets installed
|
|
277
|
+
|
|
278
|
+
Every plugin is first normalized under `.ai/installed/plugins/<id>/`: `skills/`, `agents/`,
|
|
279
|
+
`commands/`, `rules/`, `hooks/hooks.json`, `mcp.json`, its support files, and generated
|
|
280
|
+
`.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, and root `plugin.json`. That
|
|
281
|
+
tree loads as is with `claude --plugin-dir` and `cursor-agent --plugin-dir`.
|
|
282
|
+
`.ai/installed/.claude-plugin/marketplace.json` lists every installed plugin as a local
|
|
283
|
+
marketplace.
|
|
284
|
+
|
|
285
|
+
Then each host is activated. `ai-plugin.json` can set a mode per host:
|
|
286
|
+
|
|
287
|
+
```json
|
|
288
|
+
{ "plugins": [], "hosts": { "claude": "native", "cursor": "copy" } }
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
| Mode | Claude Code | Cursor |
|
|
292
|
+
| -------- | ----------------------------------------------------------------------------------- | ----------------------------------- |
|
|
293
|
+
| `native` | default — `.ai/installed/` is a local marketplace; each plugin is installed from it | not supported, falls back to `copy` |
|
|
294
|
+
| `copy` | vendor components into `.claude/`, `.mcp.json` | default — vendor into `.cursor/` |
|
|
295
|
+
| `off` | nothing for that host | nothing for that host |
|
|
296
|
+
|
|
297
|
+
**Native (Claude Code).** agent-deck runs `claude plugin marketplace add <project>/.ai/installed --scope
|
|
298
|
+
local`, then `claude plugin install <id>@agent-deck --scope local` for each plugin (and
|
|
299
|
+
`plugin uninstall` when it goes). An installed plugin needs no further call: Claude reads
|
|
300
|
+
its tree, so hooks, commands, agents, MCP servers, and `${CLAUDE_PLUGIN_ROOT}` work as the plugin
|
|
301
|
+
author intended, and skills are namespaced (`impeccable:impeccable`). The registration is
|
|
302
|
+
recorded in `.claude/settings.local.json` and in the user's plugin registry, so every
|
|
303
|
+
machine runs `agent-deck install` once. Without the `claude` CLI on `PATH` (or
|
|
304
|
+
`AGENT_DECK_CLAUDE_BIN`), agent-deck falls back to copy mode and says so. The `agent-deck` marketplace is
|
|
305
|
+
removed when no plugin is installed from it.
|
|
306
|
+
|
|
307
|
+
**Cursor.** `cursor-agent` ignores plugin paths returned by a `workspaceOpen` hook, so Cursor uses copy mode. Agent runners can still pass
|
|
308
|
+
`.ai/installed/plugins/<id>` to `cursor-agent --plugin-dir`.
|
|
309
|
+
|
|
310
|
+
Copy mode writes:
|
|
311
|
+
|
|
312
|
+
| Component | Claude Code | Cursor |
|
|
313
|
+
| --------------------------------------- | ------------------------ | ------------------------ |
|
|
314
|
+
| Skills | `.claude/skills/<name>/` | `.cursor/skills/<name>/` |
|
|
315
|
+
| Agents (nested folders kept) | `.claude/agents/` | `.cursor/agents/` |
|
|
316
|
+
| Commands | `.claude/commands/<id>/` | `.cursor/commands/<id>/` |
|
|
317
|
+
| Rules | — | `.cursor/rules/<id>/` |
|
|
318
|
+
| Support files | `.claude/plugins/<id>/` | `.cursor/plugins/<id>/` |
|
|
319
|
+
| MCP (keys `agent-deck__<id>__<server>`) | `.mcp.json` | `.cursor/mcp.json` |
|
|
320
|
+
|
|
321
|
+
Relative links from a skill to a support file are rewritten to the per-plugin directory.
|
|
322
|
+
`${CLAUDE_PLUGIN_ROOT}`, `${CURSOR_PLUGIN_ROOT}`, and `${PLUGIN_ROOT}` are replaced with
|
|
323
|
+
that directory in skills and MCP servers. Hooks are not active in copy mode; agent-deck and
|
|
324
|
+
`agent-deck status` say so. Copy mode refuses to write a path another plugin owns, or one agent-deck did not write
|
|
325
|
+
(`--force` replaces the latter).
|
|
326
|
+
|
|
327
|
+
Optional `skills/<name>/DEFAULT_USAGE.md` is not copied. Its body is stored in the lock
|
|
328
|
+
as `agentsSnippets` and, when `AGENTS.md` exists and `writeAgentsMd` is true, written to
|
|
329
|
+
a marked `## Skills` block. `agent-deck install` never creates `AGENTS.md`; `agent-deck init` does.
|
|
330
|
+
|
|
331
|
+
## ai-plugin.json
|
|
332
|
+
|
|
333
|
+
Settings: `"hosts"` (see above), `"agentsMd": false` to leave `AGENTS.md` alone (the
|
|
334
|
+
lock mirrors it as `writeAgentsMd`), and `"gitignoreCopies": false` to commit the copies
|
|
335
|
+
(see [Set up a project](#set-up-a-project)).
|
|
336
|
+
|
|
337
|
+
```json
|
|
338
|
+
{
|
|
339
|
+
"plugins": [
|
|
340
|
+
{
|
|
341
|
+
"id": "impeccable",
|
|
342
|
+
"source": "github:pbakaus/impeccable",
|
|
343
|
+
"plugin": "impeccable",
|
|
344
|
+
"ref": "v4.5.2"
|
|
345
|
+
},
|
|
346
|
+
{
|
|
347
|
+
"id": "doc-skills",
|
|
348
|
+
"source": "github:anthropics/skills",
|
|
349
|
+
"plugin": "document-skills"
|
|
350
|
+
},
|
|
351
|
+
{ "id": "fmt", "source": "npm:@acme/formatter", "version": "^2" }
|
|
352
|
+
]
|
|
353
|
+
}
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
## ai-plugin.lock.json
|
|
357
|
+
|
|
358
|
+
Format 1, committed. One entry per id: the request, what it resolved to, the integrity of
|
|
359
|
+
the normalized tree, its components, and its `AGENTS.md` snippets. Nothing in it depends
|
|
360
|
+
on the machine.
|
|
361
|
+
|
|
362
|
+
```json
|
|
363
|
+
{
|
|
364
|
+
"lockfileVersion": 3,
|
|
365
|
+
"writeAgentsMd": true,
|
|
366
|
+
"plugins": [
|
|
367
|
+
{
|
|
368
|
+
"id": "impeccable",
|
|
369
|
+
"request": {
|
|
370
|
+
"id": "impeccable",
|
|
371
|
+
"source": "github:pbakaus/impeccable",
|
|
372
|
+
"plugin": "impeccable"
|
|
373
|
+
},
|
|
374
|
+
"resolved": {
|
|
375
|
+
"type": "git",
|
|
376
|
+
"url": "https://github.com/pbakaus/impeccable.git",
|
|
377
|
+
"sha": "c63b8dd7…"
|
|
378
|
+
},
|
|
379
|
+
"integrity": "sha256-…",
|
|
380
|
+
"components": {
|
|
381
|
+
"skills": ["impeccable"],
|
|
382
|
+
"agents": ["…"],
|
|
383
|
+
"commands": [],
|
|
384
|
+
"rules": [],
|
|
385
|
+
"hooks": true,
|
|
386
|
+
"mcp": []
|
|
387
|
+
},
|
|
388
|
+
"agentsSnippets": []
|
|
389
|
+
}
|
|
390
|
+
]
|
|
391
|
+
}
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
`install` keeps each pin while the request is unchanged; `update` moves it. A plugin
|
|
395
|
+
whose pin, normalized tree, host modes, and installed files all match what is on disk is
|
|
396
|
+
skipped (`up to date`): no fetch, no copy, no `claude` call. Fetches are cached under
|
|
397
|
+
`~/.cache/agent-deck/` by commit, by exact npm version, and by archive digest, so a
|
|
398
|
+
pinned source is downloaded once per machine.
|
|
399
|
+
`install --frozen` refuses a request the lock does not pin, a lock entry nothing
|
|
400
|
+
requests, and a normalized tree whose integrity differs — use it in CI.
|
|
401
|
+
|
|
402
|
+
`.gitignore`: see [Set up a project](#set-up-a-project).
|
|
403
|
+
|
|
404
|
+
## Developing a plugin
|
|
405
|
+
|
|
406
|
+
`link` installs a local folder — a git checkout (uncommitted files included, `.gitignore`
|
|
407
|
+
respected) or any directory of skills — without touching `ai-plugin.json` or the lock. The link lives in `ai-plugin.local.json` and replaces a
|
|
408
|
+
committed request with the same id.
|
|
409
|
+
|
|
410
|
+
```bash
|
|
411
|
+
agent-deck link /path/to/my-plugins@my-plugin --project /path/to/app
|
|
412
|
+
# edit the skill, then pick up the working tree again:
|
|
413
|
+
agent-deck install --project /path/to/app
|
|
414
|
+
agent-deck unlink my-plugin --project /path/to/app
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
Caches live under `~/.cache/agent-deck/` (override with `AGENT_DECK_CACHE`).
|
|
418
|
+
`AGENT_DECK_LOCAL_<owner>__<repo>` points a GitHub source at a local checkout for scripts and
|
|
419
|
+
integration tests: the current branch and `HEAD` use the working tree, any other ref is
|
|
420
|
+
checked out from a local clone.
|
|
421
|
+
|
|
422
|
+
## Auth
|
|
423
|
+
|
|
424
|
+
Uses the machine’s existing `git` access (SSH agent, `gh`, credential helper) and npm
|
|
425
|
+
configuration. No tokens are stored by this CLI. npm packages are packed with
|
|
426
|
+
`--ignore-scripts`.
|
|
427
|
+
|
|
428
|
+
## Contributing
|
|
429
|
+
|
|
430
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).
|
|
431
|
+
|
|
432
|
+
## License
|
|
433
|
+
|
|
434
|
+
[MIT](LICENSE) © 2026 Julien La Vinh
|
package/package.json
CHANGED
|
@@ -1,6 +1,44 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@toolmesh/agent-deck",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "Install and sync Claude Code and Cursor plugins, skills, agents and MCP servers into a project from a lockfile.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"author": "Julien La Vinh",
|
|
7
|
+
"license": "MIT",
|
|
8
|
+
"engines": {
|
|
9
|
+
"node": ">=22.14"
|
|
10
|
+
},
|
|
11
|
+
"bin": {
|
|
12
|
+
"agent-deck": "bin/agent-deck.js"
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"bin/**",
|
|
16
|
+
"src/**/*.mjs",
|
|
17
|
+
"!src/**/*.test.mjs",
|
|
18
|
+
"!src/testkit.mjs"
|
|
19
|
+
],
|
|
20
|
+
"scripts": {
|
|
21
|
+
"test": "node --test src/*.test.mjs"
|
|
22
|
+
},
|
|
23
|
+
"publishConfig": {
|
|
24
|
+
"access": "public"
|
|
25
|
+
},
|
|
26
|
+
"repository": {
|
|
27
|
+
"type": "git",
|
|
28
|
+
"url": "git+https://github.com/tilap/agent-deck.git"
|
|
29
|
+
},
|
|
30
|
+
"bugs": {
|
|
31
|
+
"url": "https://github.com/tilap/agent-deck/issues"
|
|
32
|
+
},
|
|
33
|
+
"homepage": "https://github.com/tilap/agent-deck#readme",
|
|
34
|
+
"keywords": [
|
|
35
|
+
"claude-code",
|
|
36
|
+
"cursor",
|
|
37
|
+
"agents",
|
|
38
|
+
"skills",
|
|
39
|
+
"plugins",
|
|
40
|
+
"mcp",
|
|
41
|
+
"marketplace",
|
|
42
|
+
"lockfile"
|
|
43
|
+
]
|
|
44
|
+
}
|
package/src/agents.mjs
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
|
|
4
|
+
export const AGENTS_FILE = "AGENTS.md";
|
|
5
|
+
export const SKILLS_START = "<!-- agent-deck:skills:start -->";
|
|
6
|
+
export const SKILLS_END = "<!-- agent-deck:skills:end -->";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Collect DEFAULT_USAGE.md bodies from locked plugins, in lock order then skill name.
|
|
10
|
+
* @param {{ plugins?: Array<{ agentsSnippets?: Array<{ skill: string, body: string }> }> }} lock
|
|
11
|
+
*/
|
|
12
|
+
export function collectAgentsSnippets(lock) {
|
|
13
|
+
const snippets = [];
|
|
14
|
+
for (const record of lock?.plugins || []) {
|
|
15
|
+
const items = [...(record.agentsSnippets || [])].sort((a, b) =>
|
|
16
|
+
a.skill.localeCompare(b.skill),
|
|
17
|
+
);
|
|
18
|
+
for (const item of items) {
|
|
19
|
+
if (!item?.body?.trim()) continue;
|
|
20
|
+
snippets.push(item.body.trimEnd());
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
return snippets;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
function buildSkillsBlock(snippets) {
|
|
27
|
+
return [
|
|
28
|
+
SKILLS_START,
|
|
29
|
+
"## Skills",
|
|
30
|
+
"",
|
|
31
|
+
...snippets,
|
|
32
|
+
"",
|
|
33
|
+
SKILLS_END,
|
|
34
|
+
].join("\n");
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Rewrite the agent-deck skills block in AGENTS.md from the lock.
|
|
39
|
+
* Does nothing when AGENTS.md is missing.
|
|
40
|
+
* When writeAgentsMd is false or there are no snippets, removes an existing marked block.
|
|
41
|
+
*/
|
|
42
|
+
export function rewriteAgentsMd(projectRoot, lock) {
|
|
43
|
+
const file = path.join(projectRoot, AGENTS_FILE);
|
|
44
|
+
if (!fs.existsSync(file)) return { wrote: false, reason: "missing" };
|
|
45
|
+
|
|
46
|
+
const enabled = lock?.writeAgentsMd !== false;
|
|
47
|
+
const snippets = enabled ? collectAgentsSnippets(lock) : [];
|
|
48
|
+
const original = fs.readFileSync(file, "utf8");
|
|
49
|
+
const start = original.indexOf(SKILLS_START);
|
|
50
|
+
const end = original.indexOf(SKILLS_END);
|
|
51
|
+
|
|
52
|
+
let next;
|
|
53
|
+
if (snippets.length === 0) {
|
|
54
|
+
if (start === -1 || end === -1 || end < start) {
|
|
55
|
+
return {
|
|
56
|
+
wrote: false,
|
|
57
|
+
reason: enabled ? "no-snippets" : "disabled",
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
const before = original.slice(0, start).replace(/\n+$/, "");
|
|
61
|
+
const after = original.slice(end + SKILLS_END.length).replace(/^\n+/, "\n");
|
|
62
|
+
next = `${before}${after === "\n" || after === "" ? "\n" : after}`;
|
|
63
|
+
if (!next.endsWith("\n")) next += "\n";
|
|
64
|
+
} else {
|
|
65
|
+
const block = buildSkillsBlock(snippets);
|
|
66
|
+
if (start !== -1 && end !== -1 && end > start) {
|
|
67
|
+
const before = original.slice(0, start).replace(/\n+$/, "\n\n");
|
|
68
|
+
const after = original.slice(end + SKILLS_END.length).replace(/^\n*/, "\n");
|
|
69
|
+
next = `${before}${block}${after.startsWith("\n") ? after : `\n${after}`}`;
|
|
70
|
+
} else {
|
|
71
|
+
const body = original.replace(/\n*$/, "\n\n");
|
|
72
|
+
next = `${body}${block}\n`;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
if (next === original) return { wrote: false, reason: "unchanged" };
|
|
77
|
+
fs.writeFileSync(file, next, "utf8");
|
|
78
|
+
return { wrote: true, snippets: snippets.length, enabled };
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** Read optional DEFAULT_USAGE.md next to a skill; empty or missing → null. */
|
|
82
|
+
export function readDefaultUsage(pluginDir, skillName) {
|
|
83
|
+
const file = path.join(pluginDir, "skills", skillName, "DEFAULT_USAGE.md");
|
|
84
|
+
if (!fs.existsSync(file)) return null;
|
|
85
|
+
const body = fs.readFileSync(file, "utf8").trimEnd();
|
|
86
|
+
return body ? { skill: skillName, body } : null;
|
|
87
|
+
}
|