agkit 0.7.0 → 0.9.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/LICENSE +21 -0
- package/README.md +231 -43
- package/dist/index.js +656 -170
- package/package.json +19 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 fair3n
|
|
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,42 +1,107 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# **AG**ent marketplace **KIT**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**One canonical catalog → every AI coding agent → any Git forge.**
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Scaffold and manage **plugin marketplaces for Claude Code · GitHub Copilot · OpenAI Codex · Cursor**,
|
|
8
|
+
distributed through **any Git host** — GitHub, GitLab, Bitbucket, Gitea, or a self‑hosted forge.
|
|
8
9
|
|
|
10
|
+
[](https://www.npmjs.com/package/agkit)
|
|
11
|
+
[](https://www.npmjs.com/package/agkit)
|
|
12
|
+
[](https://github.com/Fairen/agkit/actions/workflows/ci.yml)
|
|
13
|
+
[](https://nodejs.org)
|
|
14
|
+
[](LICENSE)
|
|
15
|
+
|
|
16
|
+
*`init` · `add` · `build` · `sync` · `bump` · `validate` · `list`*
|
|
17
|
+
|
|
18
|
+
</div>
|
|
19
|
+
|
|
20
|
+
> [!NOTE]
|
|
9
21
|
> Unofficial community tool, not affiliated with Anthropic, GitHub, OpenAI, or Cursor.
|
|
10
22
|
|
|
11
|
-
|
|
23
|
+
Think **`ng` for Angular, but for agent plugin marketplaces**: `init` gives you a push‑ready repository, and `add` / `build` / `sync` / `bump` / `validate` cover the whole life of the project afterwards.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## ✨ Why agkit
|
|
12
28
|
|
|
13
|
-
|
|
29
|
+
- 🧩 **Multi‑agent** — one repository serves Claude Code, GitHub Copilot, OpenAI Codex, and Cursor.
|
|
30
|
+
- 🌐 **Forge‑agnostic** — distribute via GitHub, GitLab, Bitbucket, Gitea, or self‑hosted, with a plain `git push`.
|
|
31
|
+
- 📁 **One source of truth** — a single canonical `.claude-plugin/marketplace.json`; generated registries derive from it and never drift.
|
|
32
|
+
- 🔁 **Full lifecycle** — `init`, `add`, `build`, `sync`, `bump`, `validate`, `list`.
|
|
33
|
+
- 🔗 **Reference, vendor, or scaffold** — catalog a remote plugin **by reference** (no clone, the default), **vendor** a remote template into your repo with `--vendor`, or **scaffold** from a built-in / local template. Create a standalone plugin (no marketplace) with `init --plugin`.
|
|
34
|
+
- ✅ **CI‑ready** — generated GitHub Actions / GitLab CI, with `validate` + `build --check` gates.
|
|
14
35
|
|
|
15
|
-
|
|
16
|
-
- **Generated registry (`agkit build`)** — **Codex** and **Cursor** install from their own committed registry, which `agkit build` derives from the same canonical catalog. You run `agkit build` once to enable a target; after that `add`/`bump`/`sync` keep it fresh automatically.
|
|
36
|
+
---
|
|
17
37
|
|
|
18
|
-
|
|
38
|
+
## 📦 Installation
|
|
19
39
|
|
|
20
|
-
|
|
40
|
+
Requires **Node.js ≥ 22**. Run it on demand with `npx` (nothing to install), or install the CLI globally:
|
|
21
41
|
|
|
22
42
|
```bash
|
|
23
|
-
npx agkit
|
|
43
|
+
npx agkit --help # run without installing
|
|
44
|
+
npm install -g agkit # or install the `agkit` command globally
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## 🚀 Quick start
|
|
50
|
+
|
|
51
|
+
Create and distribute your first marketplace in **four steps**:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
npx agkit init my-marketplace # 1. scaffold a push-ready repository
|
|
24
55
|
cd my-marketplace
|
|
25
|
-
agkit add skill tdd-coach
|
|
26
|
-
agkit validate
|
|
56
|
+
agkit add skill tdd-coach # 2. add a plugin from a built-in template
|
|
57
|
+
agkit validate # 3. check the catalog is valid
|
|
27
58
|
git remote add origin <your-git-url>
|
|
28
|
-
git add -A && git commit -m "feat: initial marketplace" && git push -u origin main
|
|
59
|
+
git add -A && git commit -m "feat: initial marketplace" && git push -u origin main # 4. distribute via git
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
That's the whole loop — once pushed, anyone can install your plugins straight from the repo (the per‑agent install command is in the **Create a marketplace for your agent** section below). `init` targets **Claude Code** and **GitHub Copilot** by default; add `--agents codex,cursor` to serve more.
|
|
63
|
+
|
|
64
|
+
Step 2 has more shapes — reference a remote plugin without cloning it, vendor a template into your repo, or scaffold a plugin on its own with `agkit init --plugin`. All of them are laid out in **[Adding plugins](#-adding-plugins)**.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## 🧩 How agents consume your marketplace
|
|
69
|
+
|
|
70
|
+
agkit always writes **one canonical catalog** — `.claude-plugin/marketplace.json` — plus your plugins under `plugins/<name>/`. That catalog is the single source of truth. How each agent reads it falls into two groups:
|
|
71
|
+
|
|
72
|
+
```mermaid
|
|
73
|
+
flowchart TD
|
|
74
|
+
DEV["agkit init · add · bump · sync"] --> CAT[".claude-plugin/marketplace.json<br/>+ plugins/<name><br/><b>— canonical catalog —</b>"]
|
|
75
|
+
CAT -->|read as-is, no build| NATIVE["🟢 Native<br/>Claude Code · GitHub Copilot"]
|
|
76
|
+
CAT -->|agkit build| GEN["⚙️ Generated registries<br/>OpenAI Codex · Cursor"]
|
|
77
|
+
NATIVE --> PUSH["git push → any forge"]
|
|
78
|
+
GEN --> PUSH
|
|
79
|
+
PUSH --> INSTALL["🎉 consumers install your plugins"]
|
|
29
80
|
```
|
|
30
81
|
|
|
31
|
-
|
|
82
|
+
- 🟢 **Native (no build step)** — **Claude Code** and **GitHub Copilot** read `.claude-plugin/marketplace.json` directly. Push the repo and it installs.
|
|
83
|
+
- ⚙️ **Generated registry (`agkit build`)** — **Codex** and **Cursor** install from their own committed registry, which `agkit build` derives from the same canonical catalog. You run `agkit build` once to enable a target; after that `add` / `bump` / `sync` keep it fresh automatically.
|
|
84
|
+
|
|
85
|
+
> [!TIP]
|
|
86
|
+
> You can target several agents from a single repository — the plugin content under `plugins/` is shared across all of them.
|
|
87
|
+
|
|
88
|
+
---
|
|
32
89
|
|
|
33
|
-
## Create a marketplace for your agent
|
|
90
|
+
## 🎯 Create a marketplace for your agent
|
|
34
91
|
|
|
35
|
-
Choose targets at init with `--agents`. Every flow ends with a normal git push
|
|
92
|
+
Choose targets at init with `--agents`. Every flow ends with a normal `git push`; distribution works from any forge.
|
|
36
93
|
|
|
37
|
-
|
|
94
|
+
| Agent | Type | `agkit build`? | Consumers install with |
|
|
95
|
+
| :---- | :--- | :------------: | :--------------------- |
|
|
96
|
+
| **Claude Code** | 🟢 Native | — | `/plugin marketplace add …` |
|
|
97
|
+
| **GitHub Copilot** | 🟢 Native | — | `copilot plugin marketplace add …` |
|
|
98
|
+
| **OpenAI Codex** | ⚙️ Generated | ✅ | `codex plugin marketplace add …` |
|
|
99
|
+
| **Cursor** | ⚙️ Generated | ✅ | add in Cursor, then install by name |
|
|
38
100
|
|
|
39
|
-
|
|
101
|
+
<details open>
|
|
102
|
+
<summary><b>🤖 Claude Code</b> — native, nothing to generate</summary>
|
|
103
|
+
|
|
104
|
+
<br/>
|
|
40
105
|
|
|
41
106
|
```bash
|
|
42
107
|
agkit init my-marketplace --agents claude-code
|
|
@@ -49,14 +114,19 @@ git add -A && git commit -m "feat: initial marketplace" && git push -u origin ma
|
|
|
49
114
|
|
|
50
115
|
Consumers install in a Claude Code session:
|
|
51
116
|
|
|
52
|
-
```
|
|
117
|
+
```text
|
|
53
118
|
/plugin marketplace add <owner/repo or git URL>
|
|
54
119
|
/plugin install my-skill@my-marketplace
|
|
55
120
|
```
|
|
56
121
|
|
|
57
|
-
|
|
122
|
+
</details>
|
|
58
123
|
|
|
59
|
-
|
|
124
|
+
<details>
|
|
125
|
+
<summary><b>🐙 GitHub Copilot</b> — native, same repo as Claude Code, no build</summary>
|
|
126
|
+
|
|
127
|
+
<br/>
|
|
128
|
+
|
|
129
|
+
The default init already includes Copilot; to target it explicitly use `--agents copilot` (or `--agents claude-code,copilot`).
|
|
60
130
|
|
|
61
131
|
```bash
|
|
62
132
|
agkit init my-marketplace --agents claude-code,copilot
|
|
@@ -73,7 +143,12 @@ copilot plugin marketplace add <owner/repo or git URL>
|
|
|
73
143
|
copilot plugin install my-skill@my-marketplace
|
|
74
144
|
```
|
|
75
145
|
|
|
76
|
-
|
|
146
|
+
</details>
|
|
147
|
+
|
|
148
|
+
<details>
|
|
149
|
+
<summary><b>🧠 OpenAI Codex</b> — installs from a generated registry</summary>
|
|
150
|
+
|
|
151
|
+
<br/>
|
|
77
152
|
|
|
78
153
|
Codex installs from its own registry, which `agkit build` generates from the catalog.
|
|
79
154
|
|
|
@@ -94,7 +169,12 @@ codex plugin marketplace add <owner/repo or git URL>
|
|
|
94
169
|
|
|
95
170
|
The Codex registry format follows the official Codex plugin docs (`.agents/plugins/marketplace.json` with `source: { source: "local", path }`, `policy`, and `category`). Commit the generated files so consumers can install.
|
|
96
171
|
|
|
97
|
-
|
|
172
|
+
</details>
|
|
173
|
+
|
|
174
|
+
<details>
|
|
175
|
+
<summary><b>🖱️ Cursor</b> — installs from a generated registry</summary>
|
|
176
|
+
|
|
177
|
+
<br/>
|
|
98
178
|
|
|
99
179
|
Cursor installs from a committed `.cursor-plugin/` registry, also generated by `agkit build`.
|
|
100
180
|
|
|
@@ -109,9 +189,12 @@ git add -A && git commit -m "feat: initial marketplace" && git push -u origin ma
|
|
|
109
189
|
|
|
110
190
|
Consumers add the marketplace in Cursor, then install the plugin by name.
|
|
111
191
|
|
|
112
|
-
|
|
192
|
+
</details>
|
|
193
|
+
|
|
194
|
+
<details>
|
|
195
|
+
<summary><b>🌈 Several agents at once</b> — one repository serves them all</summary>
|
|
113
196
|
|
|
114
|
-
|
|
197
|
+
<br/>
|
|
115
198
|
|
|
116
199
|
```bash
|
|
117
200
|
agkit init my-marketplace --agents claude-code,copilot,codex,cursor
|
|
@@ -122,19 +205,25 @@ agkit validate
|
|
|
122
205
|
git add -A && git commit -m "feat: initial marketplace" && git push -u origin main
|
|
123
206
|
```
|
|
124
207
|
|
|
125
|
-
|
|
208
|
+
</details>
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## 🛠️ Commands
|
|
126
213
|
|
|
127
214
|
| Command | What it does |
|
|
128
215
|
| :------ | :----------- |
|
|
129
|
-
| `agkit init [dir]` | Scaffolds a git-first marketplace: `.claude-plugin/marketplace.json` (with `$schema`, `pluginRoot`, `targets`), `plugins/`, `AGENTS.md`, a per-agent README, `examples/team-settings.json`, CI (GitHub Actions or GitLab CI), `.gitignore`, `git init`. Pick target agents with `--agents` (see
|
|
130
|
-
| `agkit add <template\|spec> <name>` |
|
|
216
|
+
| `agkit init [dir]` | Scaffolds a git-first marketplace: `.claude-plugin/marketplace.json` (with `$schema`, `pluginRoot`, `targets`), `plugins/`, `AGENTS.md`, a per-agent README, `examples/team-settings.json`, CI (GitHub Actions or GitLab CI), `.gitignore`, `git init`. Pick target agents with `--agents` (see the **Target agents** section). Non-interactive with `-y`. Use **`--plugin [template]`** to instead scaffold a **standalone plugin** in `[dir]` — just `.claude-plugin/plugin.json` + content, its own git repo, **no marketplace** — ready to reference from any catalog (see **Adding plugins**). |
|
|
217
|
+
| `agkit add <template\|spec> <name>` | Registers a plugin in the catalog and refreshes the README table and `AGENTS.md`. A **remote git source** — bare `owner/repo`, `gh:owner/repo`, `gl:owner/repo`, or any git URL (`//subdir`, `#ref` supported) — is **referenced by default** as an object `source` (`github` / `url` / `git-subdir`): nothing is cloned, the agent fetches it at install time. Pin it with `--ref <branch\|tag>` / `--sha <commit>`. A **built-in template** (`skill`, `command`, `agent`, `hook`, `mcp`) or a **local path** is scaffolded into `plugins/<name>/`. Add **`--vendor`** to a remote source to clone and scaffold from it (treat the repo as a template) instead of referencing it. |
|
|
131
218
|
| `agkit build [--target] [--check]` | Generates the registries for **Codex** and **Cursor** from the catalog: their committed `marketplace.json` + per-plugin manifest mirrors. Default targets are the ones in `metadata.targets`; `--target codex,cursor` overrides. `--check` fails on drift (CI). |
|
|
132
|
-
| `agkit bump [plugin] [level]` | Bumps a plugin version from conventional commits scoped to its directory since the last `<plugin>@x.y.z` tag (`feat`→minor, breaking→major, else patch), or an explicit `major\|minor\|patch`. `--tag` commits and tags; `--dry-run` previews. Catalog, README, and any built registries stay in sync. |
|
|
133
|
-
| `agkit sync` | Reconciles the catalog with what's on disk. Source of truth: each plugin's `.claude-plugin/plugin.json`. Adds missing entries, fixes drift, flags orphans, regenerates the README table, and refreshes any already-built Codex/Cursor registry. |
|
|
219
|
+
| `agkit bump [plugin] [level]` | Bumps a plugin version from conventional commits scoped to its directory since the last `<plugin>@x.y.z` tag (`feat`→minor, breaking→major, else patch), or an explicit `major\|minor\|patch`. Prepends a dated entry to `plugins/<name>/CHANGELOG.md` from those commits. `--tag` commits and tags; `--dry-run` previews. Catalog, README, `AGENTS.md`, and any built registries stay in sync. |
|
|
220
|
+
| `agkit sync` | Reconciles the catalog with what's on disk. Source of truth: each plugin's `.claude-plugin/plugin.json`. Adds missing entries, fixes drift, flags orphans, regenerates the README table and the `AGENTS.md` plugin list, and refreshes any already-built Codex/Cursor registry. |
|
|
134
221
|
| `agkit validate [--strict]` | Local checks (JSON validity, kebab-case, reserved names, source resolution, manifest presence, version drift) plus delegation to `claude plugin validate` when the Claude Code CLI is installed (`--strict` forwarded). Non-zero exit on error — CI-ready. |
|
|
135
222
|
| `agkit list` | Lists available plugin templates. |
|
|
136
223
|
|
|
137
|
-
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## 🤖 Target agents
|
|
138
227
|
|
|
139
228
|
`agkit init --agents <list>` records the agents you want to serve and adapts the scaffold. Default: `claude-code,copilot`.
|
|
140
229
|
|
|
@@ -145,30 +234,129 @@ git add -A && git commit -m "feat: initial marketplace" && git push -u origin ma
|
|
|
145
234
|
|
|
146
235
|
Every init also writes a root `AGENTS.md`, read natively by most agents for repository context.
|
|
147
236
|
|
|
148
|
-
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
## 🔄 Keeping registries fresh
|
|
149
240
|
|
|
150
241
|
Generation is opt-in: run `agkit build` once to enable Codex/Cursor. From then on, `agkit add`, `agkit bump`, and `agkit sync` refresh the generated registries automatically, so they never drift as plugins change. In CI, run `agkit build --check` to fail the build if a committed registry is out of date (the generated GitHub Actions / GitLab CI workflows already do this).
|
|
151
242
|
|
|
152
|
-
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## 📝 Generated documentation
|
|
246
|
+
|
|
247
|
+
agkit maintains a small set of human-facing docs derived from the canonical catalog, so they never drift:
|
|
248
|
+
|
|
249
|
+
- **README plugin table** and **`AGENTS.md` plugin list** — regenerated between `<!-- agkit:plugins:start -->` / `<!-- agkit:plugins:end -->` markers on every mutating command (`add`, `bump`, `sync`). The name links to a plugin's `homepage` when set, and a `Keywords` column appears when any plugin declares keywords. Drop the same markers into any Markdown file to have that list maintained there too.
|
|
250
|
+
- **Per-plugin `CHANGELOG.md`** — `agkit bump` prepends a dated, newest-on-top entry built from the conventional commits it analyses, so each plugin carries its own release history (committed alongside the bump with `--tag`).
|
|
153
251
|
|
|
154
|
-
|
|
252
|
+
Everything derives from `.claude-plugin/marketplace.json` and the per-plugin manifests — edit those (or run `agkit sync`) and the docs follow.
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
## 📥 Adding plugins
|
|
257
|
+
|
|
258
|
+
A plugin can live **inside** your marketplace (its files committed next to the catalog) or **outside** it (kept in its own repo and fetched by the agent at install time). `agkit add` handles both; `agkit init --plugin` scaffolds a plugin as a standalone repo. The table maps each intent to a command and the `source` it writes to `marketplace.json`:
|
|
259
|
+
|
|
260
|
+
| You want to… | Command | Resulting `source` | Files copied in? |
|
|
261
|
+
| :----------- | :------ | :----------------- | :--------------- |
|
|
262
|
+
| Scaffold a new plugin from a **built-in** template | `agkit add skill my-skill` | `"./plugins/my-skill"` | ✅ scaffolded |
|
|
263
|
+
| Scaffold from a **local** template directory | `agkit add ./templates/hook-guard no-secrets` | `"./plugins/no-secrets"` | ✅ scaffolded |
|
|
264
|
+
| Create a plugin **without a marketplace** | `agkit init --plugin skill my-skill` | *(its own repo)* | ✅ scaffolded |
|
|
265
|
+
| Reference a repo that **is a plugin** (GitHub) | `agkit add acme/deploy deploy` | `{ "source": "github", "repo": … }` | ❌ referenced |
|
|
266
|
+
| Reference a repo that **is a plugin** (any forge) | `agkit add https://gitlab.com/team/plugin.git gl` | `{ "source": "url", "url": … }` | ❌ referenced |
|
|
267
|
+
| Reference a plugin **inside a marketplace/monorepo** | `agkit add "https://gitlab.com/team/marketplace.git//my-plugin" my-plugin` | `{ "source": "git-subdir", "url": …, "path": "my-plugin" }` | ❌ referenced |
|
|
268
|
+
| **Vendor** a remote template into your marketplace | `agkit add gh:my-org/templates/kata-fr gilded-rose --vendor` | `"./plugins/gilded-rose"` | ✅ cloned + scaffolded |
|
|
269
|
+
|
|
270
|
+
Rule of thumb: **a remote git source is referenced by default** (no clone); pass **`--vendor`** only when you want its files copied into your repo.
|
|
271
|
+
|
|
272
|
+
### Local plugins (scaffolded)
|
|
273
|
+
|
|
274
|
+
Built-in templates (`skill`, `command`, `agent`, `hook`, `mcp`) and local paths are scaffolded into `plugins/<name>/` and registered with a relative `"./plugins/<name>"` source:
|
|
275
|
+
|
|
276
|
+
```bash
|
|
277
|
+
agkit add skill tdd-coach # built-in template
|
|
278
|
+
agkit add ./shared-templates/hook-guard guard # a local template directory
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
A **template** is any directory containing `.claude-plugin/plugin.json` (adopted, `name` rewritten) or `plugin.json.tpl`. Files ending in `.tpl` are rendered with `{{pluginName}}`, `{{pluginTitle}}`, `{{description}}`, `{{authorName}}` — in contents **and** in file/directory names. Executable bits are preserved.
|
|
282
|
+
|
|
283
|
+
To create a plugin on its own, **outside any marketplace**, use `init --plugin`. It writes just `.claude-plugin/plugin.json` + the template content and makes the folder its own git repo (unless it's already inside one, e.g. dropped into a marketplace's `plugins/`):
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
agkit init --plugin skill ./my-skill # standalone plugin repo, no marketplace
|
|
287
|
+
# push it somewhere, then reference it from any marketplace:
|
|
288
|
+
agkit add my-org/my-skill my-skill # (run inside a marketplace project)
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
### Remote plugins (referenced — the default)
|
|
292
|
+
|
|
293
|
+
When the spec is a **remote git repo**, agkit writes an object `source` the agent resolves at install time — **nothing is cloned**, no files are added to your marketplace. The spec grammar (bare `owner/repo`, `gh:`/`gl:` shorthands, git URLs, `//subdir`, `#ref`) maps to the schema's three git forms:
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
# The repo IS the plugin (its .claude-plugin/plugin.json is at the root):
|
|
297
|
+
agkit add acme/deploy-plugin deploy # → { "source": "github", "repo": "acme/deploy-plugin" }
|
|
298
|
+
agkit add https://gitlab.com/team/plugin.git gl-tools # → { "source": "url", "url": "https://gitlab.com/team/plugin.git" }
|
|
299
|
+
|
|
300
|
+
# The plugin is a SUBDIRECTORY of a bigger repo — a marketplace or a monorepo.
|
|
301
|
+
# Point at the plugin's folder (it must contain .claude-plugin/plugin.json):
|
|
302
|
+
agkit add "https://gitlab.com/team/marketplace.git//my-plugin" my-plugin
|
|
303
|
+
# → { "source": "git-subdir", "url": "https://gitlab.com/team/marketplace.git", "path": "my-plugin" }
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
Pin any referenced source to a branch/tag with `--ref` (or `#ref` in the spec) and to an exact commit with `--sha <40-hex>`:
|
|
307
|
+
|
|
308
|
+
```bash
|
|
309
|
+
agkit add acme/deploy-plugin deploy --ref v2.0.0 --sha a1b2c3… # or agkit add acme/deploy-plugin#v2.0.0 deploy
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
> **Referencing vs. consuming.** `git-subdir` points **directly at a plugin folder** — it does *not* read that repo's own `marketplace.json`. Use it to **re-catalog one plugin** from someone else's marketplace into yours. If you only want to *use* their plugins, add their marketplace directly instead: `/plugin marketplace add team/marketplace` then `/plugin install my-plugin@their-marketplace`.
|
|
313
|
+
|
|
314
|
+
### Vendoring a remote template (`--vendor`)
|
|
315
|
+
|
|
316
|
+
Add **`--vendor`** to a remote spec to treat the repo as a **template**: agkit clones it (shallow), renders its `.tpl` files, and copies the result into `plugins/<name>/` — so the plugin now lives in, and releases with, your marketplace (relative `"./plugins/<name>"` source). Use it to seed a plugin from a shared team template:
|
|
155
317
|
|
|
156
318
|
```bash
|
|
157
|
-
agkit add gh:my-org/plugin-templates/kata-fr gilded-rose
|
|
158
|
-
agkit add "https://gitlab.company.io/craft/templates//skill-ddd#v2" tactical-ddd
|
|
159
|
-
agkit add ./shared-templates/hook-guard no-secrets
|
|
319
|
+
agkit add gh:my-org/plugin-templates/kata-fr gilded-rose --vendor
|
|
320
|
+
agkit add "https://gitlab.company.io/craft/templates//skill-ddd#v2" tactical-ddd --vendor
|
|
160
321
|
```
|
|
161
322
|
|
|
162
|
-
|
|
323
|
+
Pin the vendored clone with `#ref` in the spec (as above). The clone's `.git` is never copied into the plugin.
|
|
163
324
|
|
|
164
|
-
|
|
325
|
+
---
|
|
326
|
+
|
|
327
|
+
## 🌐 Forge-agnostic by design
|
|
165
328
|
|
|
166
329
|
`init` parses your git remote (https, ssh, scp-style) regardless of host. On github.com it uses the `owner/repo` shorthand and `{"source": "github"}` team settings; everywhere else it emits the git URL form — which every supported agent accepts for any forge.
|
|
167
330
|
|
|
168
|
-
|
|
331
|
+
---
|
|
332
|
+
|
|
333
|
+
## 👥 Team setup (automatic installation)
|
|
169
334
|
|
|
170
335
|
`init` writes `examples/team-settings.json` with an `extraKnownMarketplaces` block. Drop it into the settings file for each agent so teammates get the marketplace automatically when they trust the repository — `.claude/settings.json` for Claude Code, `.github/copilot/settings.json` for GitHub Copilot.
|
|
171
336
|
|
|
172
|
-
|
|
337
|
+
---
|
|
338
|
+
|
|
339
|
+
## 🧪 Development
|
|
340
|
+
|
|
341
|
+
Requires **Node.js ≥ 22**. Clone, install, and run the same gate CI does:
|
|
342
|
+
|
|
343
|
+
```bash
|
|
344
|
+
npm install
|
|
345
|
+
npm run typecheck # tsc --noEmit
|
|
346
|
+
npm run lint # biome check (lint:fix to autofix)
|
|
347
|
+
npm test # vitest run
|
|
348
|
+
npm run build # tsup → dist/index.js
|
|
349
|
+
node dist/index.js --help # run the built CLI
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
Tests live next to the code as `*.test.ts` and cover both the pure `lib/` helpers and the command layer (`add`, `init --plugin`, `sync`, `validate`) via temp-directory fixtures — the Claude CLI is stubbed in `validate` tests so the suite stays hermetic. CI runs the gate on Node 22.x and 24.x.
|
|
353
|
+
|
|
354
|
+
---
|
|
355
|
+
|
|
356
|
+
## 📄 License
|
|
357
|
+
|
|
358
|
+
[MIT](LICENSE) © fair3n
|
|
173
359
|
|
|
174
|
-
|
|
360
|
+
<div align="center">
|
|
361
|
+
<sub>Built for the age of AI coding agents. Ship a marketplace, not a config.</sub>
|
|
362
|
+
</div>
|