Skip to content
Back to search

agent-deck

Install and sync Claude Code and Cursor plugins, skills, agents and MCP servers into a project from a lockfile.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tilap--agent-deck/badge.svg)](/listings/tilap--agent-deck)

HTML

<a href="/listings/tilap--agent-deck"><img src="/api/listings/tilap--agent-deck/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Node.js 22.14 or later and `git`.

npm i -g @toolmesh/agent-deck
# or run it without installing
npx @toolmesh/agent-deck --help

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 434 lines
  1. # agent-deck
  2. [![npm](https://img.shields.io/npm/v/@toolmesh/agent-deck)](https://www.npmjs.com/package/@toolmesh/agent-deck)
  3. [![CI](https://github.com/tilap/agent-deck/actions/workflows/ci.yml/badge.svg)](https://github.com/tilap/agent-deck/actions/workflows/ci.yml)
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  5. A package manager for AI agent capabilities. It installs skills, agents, commands, rules,
  6. hooks and MCP servers into a project for **Claude Code** and **Cursor**, pins them in a
  7. lockfile, and reinstalls exactly the same thing later: on another machine, in CI, or for
  8. an agent runner.
  9. ## Why
  10. Skills, agent prompts and MCP configuration are usually copied by hand from project to
  11. project, or buried in the application code. They drift, nobody knows which version a
  12. project runs, and a fix in one place never reaches the others.
  13. agent-deck moves the agent side out of your code:
  14. - **Capabilities live in plugin marketplaces**, as ordinary git repositories, npm
  15. packages, archives or local folders, versioned and reviewed on their own.
  16. - **A project only states what it wants** in `ai-plugin.json`, the way `package.json`
  17. lists dependencies.
  18. - **A lockfile pins what it got**: commit, version, content digest. `--frozen` refuses
  19. anything that does not match, so CI and teammates run the same agents.
  20. - **Both hosts get the same plugins.** One request, installed natively in Claude Code and
  21. copied into `.cursor/` for Cursor.
  22. - **Roles are profiles.** A builder, a tester and a reviewer each get their own prompt and
  23. plugins on top of a shared base.
  24. ## Install
  25. Requires Node.js 22.14 or later and `git`.
  26. ```bash
  27. npm i -g @toolmesh/agent-deck
  28. # or run it without installing
  29. npx @toolmesh/agent-deck --help
  30. ```
  31. ## Quick start
  32. ```bash
  33. agent-deck init
  34. agent-deck add owner/marketplace-repo@plugin-name --ref v0.1.0
  35. agent-deck add anthropics/skills --skill pdf
  36. agent-deck add ./plugins/my-plugin
  37. ```
  38. `init` wires `.gitignore`, `AGENTS.md` and `CLAUDE.md`. `add` writes the request to
  39. `ai-plugin.json`, pins it in `ai-plugin.lock.json` and installs it for Claude Code and
  40. Cursor. Commit both files; `.ai/installed/` stays on the machine and comes back with
  41. `agent-deck install`.
  42. On another machine, or in CI:
  43. ```bash
  44. agent-deck install --frozen
  45. ```
  46. While editing a plugin in a local checkout, install that working tree and leave the
  47. committed request as it is:
  48. ```bash
  49. agent-deck link /path/to/marketplace@plugin-name
  50. ```
  51. Each profile is an agent role (builder, tester, reviewer) with its own prompt and plugins,
  52. installed on top of the base:
  53. ```bash
  54. agent-deck profile new builder
  55. agent-deck add anthropics/skills --skill pdf --profile builder
  56. agent-deck profile use builder
  57. ```
  58. `profile use` installs the base plus that profile, points Claude at the profile prompt and
  59. writes the Cursor rule from the same file. Open a new Claude session, or reload Cursor, to
  60. pick it up. See [Profiles](#profiles).
  61. ## How it maps to npm
  62. | npm | agent-deck | Commit |
  63. | ------------------- | ------------------------------------------------------------------- | ------ |
  64. | `package.json` | `ai-plugin.json` — what you ask for | yes |
  65. | `package-lock.json` | `ai-plugin.lock.json` — commits, versions, digests, contents | yes |
  66. | `node_modules/` | `.ai/installed/plugins/<id>/` — each plugin, normalized | no |
  67. | — | `.ai/installed/state.json` — what agent-deck wrote on this machine | no |
  68. | — | `.ai/profiles/<name>/` — agent profiles (see [Profiles](#profiles)) | yes |
  69. | — | `ai-plugin.local.json` — links to working trees | no |
  70. ## Commands
  71. ```
  72. agent-deck init [--commit-copies]
  73. agent-deck add <source> [--skill <name>]… [--ref <ref>] [--profile <name>]
  74. agent-deck remove <id> [--profile <name>]
  75. agent-deck install [--frozen]
  76. agent-deck update [<id>…] [--profile <name>]
  77. agent-deck status
  78. agent-deck outdated
  79. agent-deck link <folder>[@<plugin>] [--skill <name>]…
  80. agent-deck unlink <id>
  81. agent-deck profile new|use|off|list [<name>]
  82. agent-deck materialize --out <dir> [--profile <name>] [--json]
  83. ```
  84. | Command | Effect |
  85. | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  86. | `init` | Wire agent-deck into the project: see [Set up a project](#set-up-a-project) |
  87. | `add` | Resolve, install, and lock. The request is written only if that succeeds. Creates `ai-plugin.json` if needed |
  88. | `remove` | Drop the request, its normalized tree, its installed files, and its lock entry |
  89. | `install` | Make the project match the base and the active profile, pinned by the locks. `--frozen` for CI |
  90. | `update` | Resolve refs again (all, or the ids given) and rewrite the lock |
  91. | `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 |
  92. | `outdated` | Lock pins vs what each ref or range points to now, and newer release tags. Exit 1 when behind |
  93. | `link` | Install a local folder (a git checkout, uncommitted files included, or any folder of skills). Not locked |
  94. | `unlink` | Drop the link; reinstall the committed request if there is one |
  95. | `profile` | Agent profiles: see [Profiles](#profiles) |
  96. | `materialize` | Build the base and one profile into a folder, for a tool that launches agents: see [Materialize](#materialize) |
  97. Every command takes `-C <dir>` (`--project`), `--force` (let copy mode replace a file agent-deck
  98. did not write), and `--help`. An option a command does not take is refused.
  99. Advanced options: `add --id <id> --path <dir in source> --sha256 <hex> --no-install`,
  100. `remove --keep-files` and `unlink --keep-files`, `link --id <id> --path <dir> --no-install`.
  101. ## Set up a project
  102. ```bash
  103. agent-deck init # once per project; safe to run again
  104. agent-deck init --commit-copies # same, but commit the copies in .claude/ and .cursor/
  105. ```
  106. | File | `agent-deck init` | Afterwards |
  107. | ---------------- | -------------------------------------------------------- | --------------------------------------------------------------------- |
  108. | `ai-plugin.json` | Created when missing | `agent-deck add` / `remove` |
  109. | `.gitignore` | Created when missing; agent-deck's managed block written | `agent-deck install` rewrites the block |
  110. | `AGENTS.md` | Created when missing | `agent-deck install` rewrites its `## Skills` block |
  111. | `CLAUDE.md` | Created when missing, or given an `@AGENTS.md` line | `agent-deck profile use` / `off` add or drop `@.ai/current/prompt.md` |
  112. `CLAUDE.md` imports `AGENTS.md`, so Claude Code reads what Cursor reads: write project
  113. instructions once, in `AGENTS.md`.
  114. agent-deck's block in `.gitignore` sits between two markers and is rewritten whole; lines
  115. outside it are never touched:
  116. ```
  117. # >>> @toolmesh/agent-deck (managed: rewritten by agent-deck install)
  118. .ai/installed/
  119. .ai/current
  120. ai-plugin.local.json
  121. .cursor/rules/agent-deck-profile.mdc
  122. /.cursor/skills/commit
  123. …
  124. # <<< @toolmesh/agent-deck
  125. ```
  126. Besides the local files, it lists every path copy mode writes in `.claude/` and `.cursor/`
  127. for every plugin the base **or any profile** pins, read from the committed locks, for every
  128. host that is not `off`: like `node_modules`, they come back with `agent-deck install`, so the
  129. repository holds only the intent (`ai-plugin.json`, locks, profiles). The block does not
  130. depend on the active profile or on which CLIs a machine has: `agent-deck profile use` never
  131. changes `.gitignore`, and adding to or removing from a profile that is not active updates it. `agent-deck init --commit-copies` sets
  132. `"gitignoreCopies": false` in `ai-plugin.json`: the copies stay out of the block and get
  133. committed, so a fresh clone works in Cursor before `agent-deck install`. Shared files agent-deck edits
  134. (`.mcp.json`, `.cursor/mcp.json`, `AGENTS.md`, `CLAUDE.md`) are never ignored.
  135. `agent-deck install` never creates `.gitignore`; `agent-deck status` warns when the block is missing.
  136. ## Profiles
  137. A profile is an agent role — builder, tester, reviewer — with its own prompt and plugins,
  138. on top of the base every profile gets:
  139. ```
  140. ai-plugin.json, ai-plugin.lock.json the base (committed)
  141. .ai/profiles/builder/prompt.md the builder's prompt (committed)
  142. .ai/profiles/builder/ai-plugin.json, …lock.json the builder's plugins (committed)
  143. .ai/current → profiles/builder the active profile (local)
  144. .ai/installed/ installed plugins and state (local)
  145. ```
  146. ```bash
  147. agent-deck profile new builder # .ai/profiles/builder/ with prompt.md and an empty request
  148. agent-deck add anthropics/skills --skill pdf --profile builder
  149. agent-deck profile use builder # base + builder installed; then a new Claude session / reload Cursor
  150. agent-deck profile use tester # builder's plugins leave, tester's arrive, the base is untouched
  151. agent-deck profile off
  152. agent-deck profile list # * marks the active one
  153. ```
  154. `agent-deck add --profile x` on a profile that is not active resolves and locks the plugin in
  155. `.ai/profiles/x/` without installing it. A plugin id belongs to the base or to a profile, not both.
  156. The prompt follows `.ai/current`: `profile use` adds `@.ai/current/prompt.md` to
  157. `CLAUDE.md` once, and writes `.cursor/rules/agent-deck-profile.mdc` (`alwaysApply`) from the
  158. profile's `prompt.md`. `profile off` removes both. `.ai/current` and the Cursor rule are
  159. in agent-deck's `.gitignore` block.
  160. ## Materialize
  161. `agent-deck materialize` builds what an agent needs to run, without installing anything in the
  162. project: the base and one profile (or the base alone), as pinned by their locks, each
  163. plugin in `<out>/<id>/` with its Claude Code and Cursor manifests.
  164. ```bash
  165. agent-deck materialize --profile builder --out /tmp/agents/builder --json
  166. ```
  167. ```json
  168. {
  169. "profile": "builder",
  170. "prompt": "/path/to/project/.ai/profiles/builder/prompt.md",
  171. "out": "/tmp/agents/builder",
  172. "plugins": [
  173. {
  174. "id": "git-workflow",
  175. "path": "/tmp/agents/builder/git-workflow",
  176. "integrity": "sha256-…",
  177. "components": { "skills": ["commit", "…"], "…": [] }
  178. }
  179. ]
  180. }
  181. ```
  182. - Always frozen: a request a lock does not pin, or content that differs from its
  183. integrity, is refused.
  184. - `--profile` names the profile; `.ai/current` is not read, so several profiles can be
  185. built side by side. Local links are ignored: the output is what is committed.
  186. - Writes only in `--out`: nothing in `.claude/`, `.cursor/`, the locks, `.ai/installed/`,
  187. `.gitignore`, or `AGENTS.md`. A plugin already in `--out` with the locked integrity is
  188. kept; a folder of a plugin no longer requested is removed.
  189. Load the result with `claude --plugin-dir <out>` (Claude loads every plugin in the folder)
  190. or one `cursor-agent --plugin-dir <out>/<id>` per plugin, and pass `prompt` as the
  191. agent's instructions.
  192. ## Sources
  193. | You type | Request |
  194. | ----------------------------------- | ------------------------------------------------------------- |
  195. | `owner/repo@plugin` | `{ "source": "github:owner/repo", "plugin": "plugin" }` |
  196. | `owner/repo` | a single-plugin repository, or a repository of skills |
  197. | `owner/repo --skill a --skill b` | only those skills |
  198. | `https://github.com/owner/repo` | same as `owner/repo` |
  199. | `git+https://gitlab.com/t/r.git#v1` | `{ "source": "git:https://gitlab.com/t/r.git", "ref": "v1" }` |
  200. | `git@host:team/repo.git` | any git host over SSH |
  201. | `npm:@scope/pkg@^2` | `{ "source": "npm:@scope/pkg", "version": "^2" }` |
  202. | `https://…/kit.zip` (or `.tar.gz`) | `{ "source": "archive:https://…/kit.zip" }` |
  203. | `./plugins/name` | `{ "source": "path:plugins/name" }` |
  204. | `./plugins@name` | `{ "source": "path:plugins", "plugin": "name" }` |
  205. The id defaults to the plugin name (or the repository name); `--id` overrides it.
  206. Without `--ref`, agent-deck takes the default branch and locks the commit it found.
  207. `./path` is a directory inside the project. The request stores `path:<relative>` (no leading
  208. `./`) and the lock stores that path plus the integrity of the normalized tree. `agent-deck install`
  209. re-reads the directory; `--frozen` refuses when the files no longer match the lock. A path
  210. without `./` is a GitHub `owner/repo`. A folder outside the project is `agent-deck link`.
  211. Inside a fetched source, agent-deck finds the plugin the way Claude Code and Cursor do:
  212. - `.claude-plugin/marketplace.json` or `.cursor-plugin/marketplace.json`, with every
  213. Claude Code plugin source: relative path (and `metadata.pluginRoot` bare names),
  214. `github`, `url`, `git-subdir`, `npm`, and `archive`. A source object is fetched in turn
  215. and its own commit is locked as `nested`. `command` sources are refused.
  216. - `strict` semantics: an entry without `plugin.json` is the manifest (e.g. the skill
  217. lists of `anthropics/skills`); a `strict: false` entry that declares components next
  218. to a `plugin.json` is a conflict.
  219. - Custom component paths in `.claude-plugin/plugin.json` or `.cursor-plugin/plugin.json`
  220. (`skills`, `agents`, `commands`, `rules`, `hooks`, `mcpServers`).
  221. - No marketplace: `plugins/<name>/`, a plugin at the root, a `skills/*/SKILL.md`
  222. repository, or a single `SKILL.md` at the root.
  223. ## What gets installed
  224. Every plugin is first normalized under `.ai/installed/plugins/<id>/`: `skills/`, `agents/`,
  225. `commands/`, `rules/`, `hooks/hooks.json`, `mcp.json`, its support files, and generated
  226. `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, and root `plugin.json`. That
  227. tree loads as is with `claude --plugin-dir` and `cursor-agent --plugin-dir`.
  228. `.ai/installed/.claude-plugin/marketplace.json` lists every installed plugin as a local
  229. marketplace.
  230. Then each host is activated. `ai-plugin.json` can set a mode per host:
  231. ```json
  232. { "plugins": [], "hosts": { "claude": "native", "cursor": "copy" } }
  233. ```
  234. | Mode | Claude Code | Cursor |
  235. | -------- | ----------------------------------------------------------------------------------- | ----------------------------------- |
  236. | `native` | default — `.ai/installed/` is a local marketplace; each plugin is installed from it | not supported, falls back to `copy` |
  237. | `copy` | vendor components into `.claude/`, `.mcp.json` | default — vendor into `.cursor/` |
  238. | `off` | nothing for that host | nothing for that host |
  239. **Native (Claude Code).** agent-deck runs `claude plugin marketplace add <project>/.ai/installed --scope
  240. local`, then `claude plugin install <id>@agent-deck --scope local` for each plugin (and
  241. `plugin uninstall` when it goes). An installed plugin needs no further call: Claude reads
  242. its tree, so hooks, commands, agents, MCP servers, and `${CLAUDE_PLUGIN_ROOT}` work as the plugin
  243. author intended, and skills are namespaced (`impeccable:impeccable`). The registration is
  244. recorded in `.claude/settings.local.json` and in the user's plugin registry, so every
  245. machine runs `agent-deck install` once. Without the `claude` CLI on `PATH` (or
  246. `AGENT_DECK_CLAUDE_BIN`), agent-deck falls back to copy mode and says so. The `agent-deck` marketplace is
  247. removed when no plugin is installed from it.
  248. **Cursor.** `cursor-agent` ignores plugin paths returned by a `workspaceOpen` hook, so Cursor uses copy mode. Agent runners can still pass
  249. `.ai/installed/plugins/<id>` to `cursor-agent --plugin-dir`.
  250. Copy mode writes:
  251. | Component | Claude Code | Cursor |
  252. | --------------------------------------- | ------------------------ | ------------------------ |
  253. | Skills | `.claude/skills/<name>/` | `.cursor/skills/<name>/` |
  254. | Agents (nested folders kept) | `.claude/agents/` | `.cursor/agents/` |
  255. | Commands | `.claude/commands/<id>/` | `.cursor/commands/<id>/` |
  256. | Rules | — | `.cursor/rules/<id>/` |
  257. | Support files | `.claude/plugins/<id>/` | `.cursor/plugins/<id>/` |
  258. | MCP (keys `agent-deck__<id>__<server>`) | `.mcp.json` | `.cursor/mcp.json` |
  259. Relative links from a skill to a support file are rewritten to the per-plugin directory.
  260. `${CLAUDE_PLUGIN_ROOT}`, `${CURSOR_PLUGIN_ROOT}`, and `${PLUGIN_ROOT}` are replaced with
  261. that directory in skills and MCP servers. Hooks are not active in copy mode; agent-deck and
  262. `agent-deck status` say so. Copy mode refuses to write a path another plugin owns, or one agent-deck did not write
  263. (`--force` replaces the latter).
  264. Optional `skills/<name>/DEFAULT_USAGE.md` is not copied. Its body is stored in the lock
  265. as `agentsSnippets` and, when `AGENTS.md` exists and `writeAgentsMd` is true, written to
  266. a marked `## Skills` block. `agent-deck install` never creates `AGENTS.md`; `agent-deck init` does.
  267. ## ai-plugin.json
  268. Settings: `"hosts"` (see above), `"agentsMd": false` to leave `AGENTS.md` alone (the
  269. lock mirrors it as `writeAgentsMd`), and `"gitignoreCopies": false` to commit the copies
  270. (see [Set up a project](#set-up-a-project)).
  271. ```json
  272. {
  273. "plugins": [
  274. {
  275. "id": "impeccable",
  276. "source": "github:pbakaus/impeccable",
  277. "plugin": "impeccable",
  278. "ref": "v4.5.2"
  279. },
  280. {
  281. "id": "doc-skills",
  282. "source": "github:anthropics/skills",
  283. "plugin": "document-skills"
  284. },
  285. { "id": "fmt", "source": "npm:@acme/formatter", "version": "^2" }
  286. ]
  287. }
  288. ```
  289. ## ai-plugin.lock.json
  290. Format 1, committed. One entry per id: the request, what it resolved to, the integrity of
  291. the normalized tree, its components, and its `AGENTS.md` snippets. Nothing in it depends
  292. on the machine.
  293. ```json
  294. {
  295. "lockfileVersion": 3,
  296. "writeAgentsMd": true,
  297. "plugins": [
  298. {
  299. "id": "impeccable",
  300. "request": {
  301. "id": "impeccable",
  302. "source": "github:pbakaus/impeccable",
  303. "plugin": "impeccable"
  304. },
  305. "resolved": {
  306. "type": "git",
  307. "url": "https://github.com/pbakaus/impeccable.git",
  308. "sha": "c63b8dd7…"
  309. },
  310. "integrity": "sha256-…",
  311. "components": {
  312. "skills": ["impeccable"],
  313. "agents": ["…"],
  314. "commands": [],
  315. "rules": [],
  316. "hooks": true,
  317. "mcp": []
  318. },
  319. "agentsSnippets": []
  320. }
  321. ]
  322. }
  323. ```
  324. `install` keeps each pin while the request is unchanged; `update` moves it. A plugin
  325. whose pin, normalized tree, host modes, and installed files all match what is on disk is
  326. skipped (`up to date`): no fetch, no copy, no `claude` call. Fetches are cached under
  327. `~/.cache/agent-deck/` by commit, by exact npm version, and by archive digest, so a
  328. pinned source is downloaded once per machine.
  329. `install --frozen` refuses a request the lock does not pin, a lock entry nothing
  330. requests, and a normalized tree whose integrity differs — use it in CI.
  331. `.gitignore`: see [Set up a project](#set-up-a-project).
  332. ## Developing a plugin
  333. `link` installs a local folder — a git checkout (uncommitted files included, `.gitignore`
  334. 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
  335. committed request with the same id.
  336. ```bash
  337. agent-deck link /path/to/my-plugins@my-plugin --project /path/to/app
  338. # edit the skill, then pick up the working tree again:
  339. agent-deck install --project /path/to/app
  340. agent-deck unlink my-plugin --project /path/to/app
  341. ```
  342. Caches live under `~/.cache/agent-deck/` (override with `AGENT_DECK_CACHE`).
  343. `AGENT_DECK_LOCAL_<owner>__<repo>` points a GitHub source at a local checkout for scripts and
  344. integration tests: the current branch and `HEAD` use the working tree, any other ref is
  345. checked out from a local clone.
  346. ## Auth
  347. Uses the machine’s existing `git` access (SSH agent, `gh`, credential helper) and npm
  348. configuration. No tokens are stored by this CLI. npm packages are packed with
  349. `--ignore-scripts`.
  350. ## Contributing
  351. See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).
  352. ## License
  353. [MIT](LICENSE) © 2026 Julien La Vinh

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.