Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat(kyberforge): add plugin-author and marketplace-author skills

Browse Source 
## Why

Plugin and marketplace management had no governed authoring path. Creating or
updating a plugin required knowing the dual-manifest convention, version parity
rules, and directory skeleton by memory — nothing enforced consistency or guided
the process.

`/plugin-author` closes that gap by owning the full plugin scaffold lifecycle:
create, update, rename, and release. `/marketplace-author` handles the
marketplace-facing side: register, deregister, and update plugin entries in
`marketplace.json`.

ADR-0016 codifies the version parity convention (identical `version` in both
`plugin.json` and `.claude-plugin/plugin.json`) that `/plugin-author` now
enforces. The two plugin.json files in this repo are backfilled to comply
(keys also sorted to pass the pretty-format-json hook). CONTEXT.md gains
glossary entries for "plugin scaffold" and "version parity" so future agents
have shared vocabulary for these concepts.

## Implementation Notes

`/plugin-author` ships a `scripts/new-plugin.sh` scaffold script that generates
the directory skeleton and both manifests in one shot; the skill calls the script
rather than generating files ad hoc so the scaffold is reviewable and repeatable.

Version parity is an invariant, not a suggestion — the skill will fail loudly
on create/update if the two versions would diverge.

ADR: docs/adr/0016-plugin-version-parity.md
This commit is contained in:
Defame1297
2026-06-28 10:45:03 +00:00
parent 098fc7315e
commit 4d061bd199
18 changed files with 1159 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
plugins/kyberforge/skills/marketplace-author/README.md Normal file
View File

@@ -0,0 +1,36 @@
# marketplace-author
Adds, removes, and updates plugin entries in the holocron marketplace manifest.
## What it does
Manages entries in the `plugins[]` array of `marketplace.json`. Always updates both `.claude-plugin/marketplace.json` and `.github/plugin/marketplace.json` in the same edit pass — never one without the other. Routes automatically to add, remove, update, or create-from-scratch based on whether the files exist and whether the named plugin is already in the catalog. Runs `claude plugin validate .` after every mutating operation.
## Before you start
Have ready: the plugin name (kebab-case), what you want to do (add/remove/update), and — for add — the source type and source value. If adding from an external repo, know the source type (local path, GitHub, git URL, or npm).
## Usage
```
/marketplace-author
```
No manual script. This skill is purely agentic — it reads, edits, and writes the marketplace files directly using the Read/Edit/Write tools.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/manifest-fields.md` | Full field reference for top-level and per-entry `marketplace.json` fields, all four source type shapes with examples, and why both files must stay identical |
| `references/sources.md` | Research provenance — sources that informed this skill |
| `references/README.md` | Directory meta-documentation for references/ |
| `tests/README.md` | Notes on test coverage for this skill |
## Marketplace files managed
| File | Read by |
|------|---------|
| `.claude-plugin/marketplace.json` | Claude Code |
| `.github/plugin/marketplace.json` | Copilot CLI |

234
plugins/kyberforge/skills/marketplace-author/SKILL.md Normal file
View File

@@ -0,0 +1,234 @@
---
name: marketplace-author
description: >
Use when the user wants to add a plugin to the marketplace ("register my
plugin", "add to marketplace", "list plugin X"), remove an entry ("unlist
plugin X", "remove from marketplace"), or update an existing entry ("bump
the marketplace version", "update the description for Y"). Always updates
both .claude-plugin/marketplace.json and .github/plugin/marketplace.json in
the same pass. Out of scope: plugin scaffold and configuration — use
/plugin-author for that. Does not manage marketplace registration with
Claude Code or Copilot CLI.
allowed-tools: Bash Read Write Edit
metadata:
category: factory
source_keys:
- context7-websites-code-claude
- claude-code-plugins-docs
- github-cli-plugin-reference
- github-plugins-marketplace
- github-plugins-finding-installing
---
## Gotchas
- Both marketplace files must be identical after every operation — never update one without the other in the same edit pass.
- `source` for local plugins is a relative path from the marketplace root, not the plugin directory name alone (e.g. `"./plugins/kyberforge"`, not `"kyberforge"`).
- `claude plugin validate .` must be run from the repo root, not from the plugin directory or the `.claude-plugin/` directory.
- The `{ "source": "github", ... }` object form is only for GitHub. For GitLab, Gitea, or any other git host, use `{ "source": "git", "url": "https://..." }` with a full URL.
- Removing an entry from the marketplace does NOT delete the plugin files — it only removes the catalog listing.
- `version` in a marketplace entry is optional for git-sourced plugins; Claude Code derives version from git tags automatically. Include it when the source is npm or when the user explicitly wants a pinned version visible in the catalog.
- `name` must be kebab-case. Reserved prefixes (`anthropic-*`, `claude-*`, `agent-skills`, `official-claude-plugins`) are rejected by the validator.
- The `plugins[]` array order is not semantically significant, but maintain it consistently — add new entries at the end.
- For Copilot CLI, the canonical marketplace.json location is `.github/plugin/marketplace.json`. Claude Code also reads `.claude-plugin/marketplace.json`. Both are equivalent; this repo maintains both files in sync.
Read `references/manifest-fields.md` for the full field reference and source type shapes before editing any file.
## Route
Determine which operation applies before touching any file:
- **Neither `.claude-plugin/marketplace.json` nor `.github/plugin/marketplace.json` exist** → follow **CREATE**
- **Only one file exists** → stop and note the mirror is missing; ask the user whether to create the missing mirror from the existing file, or whether this is an error. Do not proceed until both files are present or the user has explicitly directed you to create the missing one.
- **Both files exist + plugin name NOT in `plugins[]` + add/register/list intent** → follow **ADD**
- **Both files exist + plugin name IS in `plugins[]` + remove/unlist/delete intent** → follow **REMOVE**
- **Both files exist + plugin name IS in `plugins[]` + change/update/bump intent** → follow **UPDATE**
- **User asks to validate without any add/remove/update intent** → follow **VALIDATE**
- **Ambiguous** → ask: "Did you mean to add a new plugin entry, update an existing one, or remove one?"
---
## CREATE
Run this flow only when no marketplace.json exists anywhere in the repo.
### Prerequisites
Confirm you have:
- [ ] Marketplace name (kebab-case, e.g. `my-marketplace`)
- [ ] Owner name (and optionally email)
- [ ] Marketplace description (optional but recommended)
- [ ] At least one initial plugin entry (name, source, description)
If prerequisites are missing, ask before writing.
### Step 1 — Write `.claude-plugin/marketplace.json`
Create the file with the following structure (fill in the values from prerequisites):
```json
{
"name": "<marketplace-name>",
"owner": { "name": "<owner-name>", "email": "<owner-email>" },
"description": "<marketplace-description>",
"version": "0.1.0",
"plugins": [
{
"name": "<plugin-name>",
"description": "<plugin-description>",
"source": "<source>"
}
]
}
```
Omit `"email"` if not provided. Omit `"version"` from plugin entries unless the user specifies one (see Gotchas).
### Step 2 — Write `.github/plugin/marketplace.json`
Write identical content to `.github/plugin/marketplace.json`. These two files must always be identical.
### Step 3 — Validate
Follow the **VALIDATE** flow.
---
## ADD
Run this flow when a plugin name does not yet exist in `plugins[]` and the intent is to add it.
### Prerequisites
Confirm you have:
- [ ] Plugin name (kebab-case)
- [ ] Plugin description
- [ ] Source type and source value (see source type branching below)
- [ ] Version (optional; omit for git-sourced plugins)
### Source type branching
If the user has not specified a source type, ask:
> "Which source type does this plugin use?
> 1. **Local path** — plugin lives in this repo (e.g. `./plugins/<name>`)
> 2. **GitHub** — separate GitHub repo (e.g. `owner/repo`)
> 3. **Git URL** — any git host via full URL (e.g. `https://gitlab.com/org/repo.git`)
> 4. **npm** — distributed on npm (e.g. `@scope/package`)"
Source shapes per type:
**Local path:**
```json
"source": "./plugins/<name>"
```
**GitHub:**
```json
"source": { "source": "github", "repo": "owner/repo" }
```
Add `"ref": "<branch-or-tag>"` inside the object if the user specifies a branch or tag.
**Git URL:**
```json
"source": { "source": "git", "url": "https://..." }
```
Add `"ref": "<branch-or-tag>"` inside the object if specified.
**npm:**
```json
"source": { "source": "npm", "package": "@scope/pkg", "version": "1.0.0" }
```
`version` is required for npm source.
### Entry shape
The full entry added to `plugins[]`:
```json
{
"name": "<name>",
"description": "<description>",
"source": <source per type above>
}
```
Include `"version": "<version>"` at the entry level only when the source is npm or when the user explicitly requests a pinned version in the catalog.
### Step 1 — Read both files
Read `.claude-plugin/marketplace.json` and `.github/plugin/marketplace.json`. Verify they are identical. If they differ, stop and report the divergence — do not proceed until the user resolves it.
### Step 2 — Add the entry
Append the new entry to the `plugins[]` array in `.claude-plugin/marketplace.json`.
### Step 3 — Mirror
Apply the identical addition to `.github/plugin/marketplace.json` in the same edit pass.
### Step 4 — Validate
Follow the **VALIDATE** flow.
---
## REMOVE
Run this flow when an entry exists in `plugins[]` and the intent is to remove it.
### Step 1 — Confirm the target
Read `.claude-plugin/marketplace.json`. Identify the entry to remove. State the full entry as it currently appears.
### Step 2 — HITL gate
State clearly before proceeding:
> "I will remove the `<name>` entry from both `.claude-plugin/marketplace.json` and `.github/plugin/marketplace.json`. This does not delete the plugin files. Confirm?"
Do not proceed until the user confirms. If the user says "yes" or equivalent, continue to Step 3.
### Step 3 — Remove from both files
Remove the entry from `plugins[]` in `.claude-plugin/marketplace.json`.
Apply the identical removal to `.github/plugin/marketplace.json` in the same edit pass.
### Step 4 — Validate
Follow the **VALIDATE** flow.
---
## UPDATE
Run this flow when an entry exists in `plugins[]` and the intent is to change one or more fields.
### Step 1 — Read the current entry
Read `.claude-plugin/marketplace.json`. Show the current state of the target entry so the user can confirm the fields to change.
### Step 2 — Apply changes
State which fields will change and to what values, then edit `.claude-plugin/marketplace.json`.
Apply the identical change to `.github/plugin/marketplace.json` in the same edit pass.
### Step 3 — Validate
Follow the **VALIDATE** flow.
---
## VALIDATE
Run `claude plugin validate .` from the repo root:
```bash
cd <repo-root> && claude plugin validate .
```
Report the output. If validation fails, describe the specific error and what needs to be fixed. Do not attempt to auto-fix validation errors unless the fix is unambiguous (e.g. a trailing comma that violates JSON syntax); otherwise, describe the fix and ask the user to confirm.
Validation checks include: `marketplace.json` schema compliance, duplicate plugin names, source path traversal, and version mismatches.

9
plugins/kyberforge/skills/marketplace-author/references/README.md Normal file
View File

@@ -0,0 +1,9 @@
# references/
## manifest-fields.md
Full field reference for `marketplace.json`. Covers: top-level fields (`name`, `owner`, `description`, `version`, `plugins`), per-entry fields (`name`, `description`, `source`, `version`, `author`), all four source type shapes (local path string, `github` object, `git` object, `npm` object) with examples, where each marketplace file lives and why both must stay identical. Load this before editing any marketplace.json file.
## sources.md
Research provenance record for this skill. Lists the upstream research sources (claude-code-plugins and github-copilot-plugins research docs) that informed SKILL.md and manifest-fields.md. Used by `skill-audit` to validate the provenance chain.

162
plugins/kyberforge/skills/marketplace-author/references/manifest-fields.md Normal file
View File

@@ -0,0 +1,162 @@
---
source_keys:
- context7-websites-code-claude
- claude-code-plugins-docs
- github-cli-plugin-reference
- github-plugins-marketplace
---
# Marketplace Manifest Fields
Reference for all fields in `marketplace.json`. Applies to both `.claude-plugin/marketplace.json` and `.github/plugin/marketplace.json`, which must always be identical.
## File Locations
| File | Read by | Notes |
|---|---|---|
| `.claude-plugin/marketplace.json` | Claude Code | Primary location for Claude Code marketplace manifest |
| `.github/plugin/marketplace.json` | Copilot CLI | Canonical location for Copilot CLI marketplace manifest |
Both files must be kept identical at all times. Every operation that modifies one must apply the same change to the other in the same edit pass.
---
## Top-Level Fields
| Field | Required | Type | Description |
|---|---|---|---|
| `name` | Yes | string | Marketplace name. Kebab-case, max 64 chars. Becomes the marketplace identifier used in `plugin install <name>@<marketplace>`. |
| `owner` | Yes | object | `{ "name": string, "email"?: string }` — the marketplace maintainer. |
| `description` | No | string | Human-readable description of the marketplace. Not in all schemas but accepted and displayed in the Discover tab. |
| `version` | No | string | Marketplace-level version string. Used for catalog caching; bump when the plugin list changes significantly. |
| `plugins` | Yes | array | Array of plugin entry objects. See Per-Entry Fields below. |
---
## Per-Entry Fields (inside `plugins[]`)
| Field | Required | Type | Description |
|---|---|---|---|
| `name` | Yes | string | Plugin name. Kebab-case, max 64 chars. Must be unique within the marketplace. Reserved prefixes (`anthropic-*`, `claude-*`, `agent-skills`, `official-claude-plugins`) are rejected by the validator. |
| `source` | Yes | string or object | How to locate the plugin. See Source Types below. |
| `description` | No | string | Human-readable plugin description. Max 1024 chars (Copilot CLI schema). Displayed in browse output. |
| `version` | No | string | Pinned version for catalog display. Optional for git-sourced plugins — Claude Code derives version from git tags. Required for npm source. Include when the user wants an explicit pinned version visible in the catalog. |
| `author` | No | object | `{ "name": string, "email"?: string, "url"?: string }` — the plugin author. |
---
## Source Types
The `source` field accepts four forms.
### 1. Local path (string)
Plugin lives in the same repo as the marketplace.
```json
"source": "./plugins/<plugin-name>"
```
The path is relative from the marketplace root (the repo root where `marketplace.json` sits), **not** from the plugin directory. Always prefix with `./`.
**Example:**
```json
{
"name": "kyberforge",
"description": "Skills and agents for the Claude Code plugin factory.",
"source": "./plugins/kyberforge"
}
```
---
### 2. GitHub (object)
Plugin lives in a separate GitHub repository. GitHub shorthand only — do not use this form for GitLab, Gitea, or other hosts.
```json
"source": { "source": "github", "repo": "owner/repo" }
```
Optional fields inside the object:
- `"ref"` — branch name, tag, or commit SHA to pin. Omit to follow the default branch.
- `"sha"` — exact commit SHA; takes precedence over `ref` when both are present.
**Example:**
```json
{
"name": "deploy-tools",
"description": "Deployment automation.",
"source": { "source": "github", "repo": "acme-corp/deploy-tools-plugin", "ref": "v2.0.0" }
}
```
---
### 3. Git URL (object)
Plugin in any git host — GitHub, GitLab, Gitea, Bitbucket, or self-hosted — via full HTTPS or SSH URL. Use this instead of the `github` form for any non-GitHub host.
```json
"source": { "source": "git", "url": "https://..." }
```
Optional fields inside the object:
- `"ref"` — branch name, tag, or commit SHA.
**Examples:**
```json
{ "source": "git", "url": "https://gitlab.com/org/plugin.git" }
{ "source": "git", "url": "https://gitea.example.com/org/plugin.git", "ref": "v1.0.0" }
{ "source": "git", "url": "git@github.com:org/plugin.git" }
```
---
### 4. npm (object)
Plugin distributed as an npm package. `version` is required inside the object.
```json
"source": { "source": "npm", "package": "@scope/pkg", "version": "1.0.0" }
```
**Example:**
```json
{
"name": "formatter",
"description": "Code formatting plugin.",
"source": { "source": "npm", "package": "@acme/claude-formatter", "version": "3.1.0" }
}
```
---
## Why Both Files Must Stay Identical
`.claude-plugin/marketplace.json` is the Claude Code-native path. `.github/plugin/marketplace.json` is the Copilot CLI canonical path per the reference docs (`github/copilot-plugins` and `github/awesome-copilot` both use this path). Both tools are used in this repo, so both files must exist and match. A divergence creates a split-catalog state where the two tools see different plugins — this is a silent inconsistency that is hard to detect and diagnose. Treat them as a single logical file that happens to exist at two paths.
---
## Complete Example
```json
{
"name": "holocron",
"owner": { "name": "Defame1297", "email": "defame1297@rkdr.net" },
"description": "AI development skills for Claude Code and GitHub Copilot CLI.",
"version": "0.1.0",
"plugins": [
{
"name": "kyberforge",
"description": "Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.",
"source": "./plugins/kyberforge"
},
{
"name": "external-tool",
"description": "An externally hosted plugin.",
"source": { "source": "github", "repo": "acme/external-tool" }
}
]
}
```

50
plugins/kyberforge/skills/marketplace-author/references/sources.md Normal file
View File

@@ -0,0 +1,50 @@
---
source_keys:
- context7-websites-code-claude
- claude-code-plugins-docs
- github-cli-plugin-reference
- github-plugins-marketplace
- github-plugins-finding-installing
---
# Sources
## context7-websites-code-claude
- **URL:** context7:/websites/code_claude
- **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md
- **Description:** Official Claude Code documentation site indexed by Context7 — marketplace.json format, source types, `claude plugin validate` command, plugin update lifecycle, private marketplace registration, source URL formats
- **Contributing files:** SKILL.md, references/manifest-fields.md
- **Status:** `extracted`
## claude-code-plugins-docs
- **URL:** https://code.claude.com/docs/en/plugins
- **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md
- **Description:** Official Claude Code plugin authoring guide — `marketplace.json` schema, source type shapes (local path, github object, git object, npm object), `claude plugin validate .` behavior, end-to-end publish walkthrough, marketplace catalog format
- **Contributing files:** SKILL.md, references/manifest-fields.md
- **Status:** `extracted`
## github-cli-plugin-reference
- **URL:** https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference
- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
- **Description:** Full CLI plugin reference — `marketplace.json` schema (top-level and per-entry fields), all `copilot plugin marketplace` commands, install specification formats, `.github/plugin/marketplace.json` canonical path, `strict` field behavior
- **Contributing files:** SKILL.md, references/manifest-fields.md
- **Status:** `extracted`
## github-plugins-marketplace
- **URL:** https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-marketplace
- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
- **Description:** How-to for creating and publishing a Copilot CLI plugin marketplace — `marketplace.json` structure at `.github/plugin/marketplace.json`, per-entry fields, marketplace registration commands, reference implementations (`github/copilot-plugins`, `github/awesome-copilot`)
- **Contributing files:** SKILL.md, references/manifest-fields.md
- **Status:** `extracted`
## github-plugins-finding-installing
- **URL:** https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing
- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
- **Description:** User-facing guide to discovering and installing CLI plugins — marketplace browsing commands, install/update/uninstall workflow; informs REMOVE flow design (unlisting does not uninstall from existing users)
- **Contributing files:** SKILL.md
- **Status:** `extracted`

29
plugins/kyberforge/skills/marketplace-author/tests/README.md Normal file
View File

@@ -0,0 +1,29 @@
# tests/
Test files for scripts bundled with this skill.
## When to add tests
Add tests here when the skill has scripts in `scripts/` that are complex enough
to break silently — validators, parsers, generators, anything with branching
logic or edge cases. Test infrastructure (`.bats`, `*_test.*`, `test_*.sh`)
belongs here, not in `scripts/`.
## Current state
`marketplace-author` has no `scripts/` directory — all operations are performed
directly by the agent using Read/Edit/Write tools. No test infrastructure is
needed.
If a script is added in the future, add bats tests here. Dependencies:
```bash
git clone https://github.com/bats-core/bats-support tests/test_helper/bats-support
git clone https://github.com/bats-core/bats-assert tests/test_helper/bats-assert
```
Run tests from the repo root:
```bash
bats plugins/kyberforge/skills/marketplace-author/tests/
```