feat(kyberforge): add plugin-author and marketplace-author skills
## 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:
@@ -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.
|
||||
@@ -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" }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -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`
|
||||
Reference in New Issue
Block a user