fix(kyberforge): clarify skill descriptions, trim gotchas, and clean up marketplace-author

## Why
Several small quality issues accumulated across plugin-author and
marketplace-author: the plugin-author description was ambiguous about
scope, the ADD flow asked an unnecessary clarifying question when local
path is the obvious default, VALIDATE had redundant wording already
captured inline, the keywords field was missing from the validation
checklist, and tests/README.md was a placeholder with nothing to test.

## Implementation Notes
- plugin-author: tightened description scope to "inside those
  directories"; added `keywords` identical-in-both-manifests check to
  VALIDATE checklist.
- marketplace-author: moved reserved-prefix constraint from gotchas
  into the ADD checklist item; replaced the four-option prompt with a
  default+escape-hatch ("I'll treat this as local path — is that right?");
  folded the validate-from-root note inline and removed trailing padding;
  deleted tests/README.md — no scripts/ directory exists, so the
  placeholder was noise.
- README.md: removed the tests/README.md row from the file table.

.claude-plugin/marketplace.json

@@ -1,18 +1,21 @@
 {
+  "description": "AI development skills for Claude Code and GitHub Copilot CLI \u2014 factory, design, implement, review, and cross-cutting workflows.",
   "name": "holocron",
-  "owner": { "name": "Defame1297", "email": "defame1297@rkdr.net" },
+  "owner": {
-  "description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.",
+    "email": "defame1297@rkdr.net",
-  "version": "0.1.0",
+    "name": "Defame1297"
+  },
   "plugins": [
     {
-      "name": "kyberforge",
       "description": "Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.",
+      "name": "kyberforge",
       "source": "./plugins/kyberforge"
     },
     {
-      "name": "bin",
       "description": "A place for things to be binned",
+      "name": "bin",
       "source": "./plugins/bin"
     }
-  ]
+  ],
+  "version": "0.1.1"
 }

.github/plugin/marketplace.json

@@ -1,18 +1,21 @@
 {
+  "description": "AI development skills for Claude Code and GitHub Copilot CLI \u2014 factory, design, implement, review, and cross-cutting workflows.",
   "name": "holocron",
-  "owner": { "name": "Defame1297", "email": "defame1297@rkdr.net" },
+  "owner": {
-  "description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.",
+    "email": "defame1297@rkdr.net",
-  "version": "0.1.0",
+    "name": "Defame1297"
+  },
   "plugins": [
     {
-      "name": "kyberforge",
       "description": "Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.",
+      "name": "kyberforge",
       "source": "./plugins/kyberforge"
     },
     {
-      "name": "bin",
       "description": "A place for things to be binned",
+      "name": "bin",
       "source": "./plugins/bin"
     }
-  ]
+  ],
+  "version": "0.1.1"
 }

CONTEXT.md

@@ -61,6 +61,12 @@ Reusable slash commands for AI coding tools, defined as `SKILL.md` files followi
 ### Plugin
 The deployable unit in the plugin marketplace. A plugin bundles one or more skills, agents, hooks, prompts, MCP servers, and optionally a `bin/` directory into a single installable directory. Each plugin has two manifests: `.claude-plugin/plugin.json` (Claude Code) and `plugin.json` at the plugin root (Copilot CLI). Plugins are copied to a cache on install — they cannot reference files outside their own directory. In this repo, plugins live under `plugins/<name>/`. Install a plugin with `claude plugin install <name>@<marketplace>`.
 
+### Plugin scaffold
+The non-content structural parts of a plugin: both manifests (`plugin.json` and `.claude-plugin/plugin.json`), directory skeleton (`skills/`, `agents/`, `hooks/`, `bin/`), and version. Distinct from plugin content (the skills, agents, hooks, and MCP servers inside those directories). Managed by `/plugin-author`; content is managed by content-specific skills (`/skill-author`, `/agent-author`, etc.).
+
+### Version parity
+The convention that the `version` field is always present and identical in both the Copilot CLI manifest (`plugin.json`) and the Claude Code manifest (`.claude-plugin/plugin.json`). Enforced by `/plugin-author` on every create and update. Existing plugins in the repo did not follow this convention before ADR-0016.
+
 ### Plugin marketplace
 A Git repository with a `marketplace.json` manifest listing installable plugins. No backend, registry, or SaaS required — the Git repo is the marketplace. This repo is the `holocron` marketplace. The manifest lives at `.claude-plugin/marketplace.json` (read by both Claude Code and Copilot CLI) and is mirrored to `.github/plugin/marketplace.json`. Register the marketplace with `claude plugin marketplace add <owner>/<repo>`. Plugin names must be kebab-case and not reserved (`anthropic-*`, `claude-*`, `agent-skills`, `official-claude-plugins`). Cross-tool compatibility reference: `plugins/kyberforge/docs/plugin-marketplace-architecture.md`.
 

core/AGENTS.md

@@ -15,7 +15,7 @@
 - Reads, searches, exploration: proceed without asking.
 - Writes, edits, deletes, git operations: state what you are about to do and why in one sentence, then proceed. Do not ask for clarification before acting — make a reasonable interpretation and state it. Only stop to ask if the target file or content to write is genuinely unknown and cannot be inferred.
 - Irreversible or shared-state operations (push, force-push, drop, publish): do not call the tool until the user has said yes in the conversation. State what you are about to do, then wait for explicit approval. Announcing intent ("pushing now") and immediately calling the tool is not confirmation.
-- always prefer using subagents (clean or with session context) to execute well bounded actions that require no human interaction
+- always prefer using subagents (clean or with session context) to execute well bounded actions that require no human interaction. subagents can be parallelized if they will not write to the same files. subagents must be run sequentially if they depend on eachothers changes or handoff, or will write to the same files. if skills are present relevant to the work of the subagent, they should invoke that skill.
 
 # Content index
 

docs/adr/0016-plugin-version-parity.md

@@ -0,0 +1,9 @@
+# version field is present in both plugin manifests
+
+Each plugin has two manifests: `plugin.json` (Copilot CLI) and `.claude-plugin/plugin.json` (Claude Code). Both tools support a `version` field. Prior to this decision, only the CC manifest carried `version`; the Copilot manifest omitted it.
+
+We now require `version` in both manifests, always identical. A reader of `plugin.json` alone should be able to determine the plugin version without consulting the CC manifest. The `plugin-author` skill enforces this invariant on every create, update, and release operation.
+
+## Considered options
+
+**CC-only version (rejected)** — `version` only in `.claude-plugin/plugin.json`; Copilot derives version from the git tag. Rejected because it makes `plugin.json` incomplete as a standalone descriptor and creates a class of drift where the two manifests disagree on version without any tooling catching it.

plugins/bin/.claude-plugin/plugin.json

@@ -8,5 +8,5 @@
   "keywords": [],
   "license": "MIT",
   "name": "bin",
-  "version": "1.0.1"
+  "version": "1.0.2"
 }

plugins/bin/plugin.json

@@ -1,9 +1,15 @@
 {
-  "name": "bin",
-  "description": "A place for things to be binned",
-  "author": { "name": "Defame1297", "email": "defame1297@rkdr.net" },
-  "license": "MIT",
-  "keywords": [],
   "agents": "agents/",
-  "skills": ["skills/"]
+  "author": {
+    "email": "defame1297@rkdr.net",
+    "name": "Defame1297"
+  },
+  "description": "A place for things to be binned",
+  "keywords": [],
+  "license": "MIT",
+  "name": "bin",
+  "skills": [
+    "skills/"
+  ],
+  "version": "1.0.2"
 }

plugins/kyberforge/.claude-plugin/plugin.json

@@ -8,5 +8,5 @@
   "keywords": [],
   "license": "MIT",
   "name": "kyberforge",
-  "version": "1.0.1"
+  "version": "1.0.2"
 }

plugins/kyberforge/plugin.json

@@ -1,11 +1,17 @@
 {
-  "name": "kyberforge",
-  "description": "Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.",
-  "author": { "name": "Defame1297", "email": "defame1297@rkdr.net" },
-  "license": "MIT",
-  "keywords": [],
   "agents": "agents/",
-  "skills": ["skills/"],
+  "author": {
+    "email": "defame1297@rkdr.net",
+    "name": "Defame1297"
+  },
+  "description": "Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.",
   "hooks": "hooks.json",
-  "mcpServers": ".mcp.json"
+  "keywords": [],
+  "license": "MIT",
+  "mcpServers": ".mcp.json",
+  "name": "kyberforge",
+  "skills": [
+    "skills/"
+  ],
+  "version": "1.0.2"
 }

plugins/kyberforge/skills/marketplace-author/README.md

@@ -0,0 +1,35 @@
+# 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/ |
+
+## Marketplace files managed
+
+| File | Read by |
+|------|---------|
+| `.claude-plugin/marketplace.json` | Claude Code |
+| `.github/plugin/marketplace.json` | Copilot CLI |

plugins/kyberforge/skills/marketplace-author/SKILL.md

@@ -0,0 +1,230 @@
+---
+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 run `claude plugin marketplace add` or
+  equivalent CLI registration commands — only manages `marketplace.json`
+  entries.
+allowed-tools: Bash Read Write Edit
+metadata:
+  category: factory
+  source_keys:
+    - context7-websites-code-claude
+    - claude-code-plugins-docs
+    - context7-github-en-copilot
+    - 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"`).
+- 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.
+
+## 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>" },
+  "metadata": {
+    "description": "<marketplace-description>",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "<plugin-name>",
+      "description": "<plugin-description>",
+      "source": "<source>"
+    }
+  ]
+}
+```
+
+Omit `"email"` if not provided. Omit `"metadata.version"` if the user does not want a pinned catalog version. The `metadata` object is the Copilot CLI canonical location for top-level description and version — Claude Code accepts both `metadata`-nested and top-level forms; use `metadata` for dual-tool repos.
+
+### 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; reserved prefixes `anthropic-*`, `claude-*`, `agent-skills`, `official-claude-plugins` are rejected by the validator)
+- [ ] Plugin description
+- [ ] Source type and source value (see source type branching below)
+- [ ] Version (optional; omit for git-sourced plugins)
+
+If you need details on a specific source type shape or per-entry optional fields, read `references/manifest-fields.md`.
+
+### Source type branching
+
+If the user has not specified a source type, assume local path (the most common case for in-repo plugins). Only ask if the user's intent is unclear: "I'll treat this as a local path plugin — is that right, or does it live on GitHub, a git URL, or npm?"
+
+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. Add `"sha": "<commit-sha>"` if pinning to an exact commit — `sha` takes precedence over `ref` when both are present.
+
+**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.
+
+Include `"strict": false` when the plugin is a dual Claude Code / Copilot CLI plugin — this prevents Copilot from rejecting CC-specific fields in the plugin directory.
+
+### 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 end of the `plugins[]` array in `.claude-plugin/marketplace.json`. Array order is not semantically significant, but always add at the end for consistency.
+
+### 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.
+
+If you need to verify a field name or source type shape, read `references/manifest-fields.md`.
+
+### 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 from the repo root (not from the plugin directory or `.claude-plugin/`):
+
+```bash
+claude plugin validate .
+```
+
+Add `--strict` to promote warnings to errors — recommended in CI.
+
+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.

plugins/kyberforge/skills/marketplace-author/references/README.md

@@ -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.

plugins/kyberforge/skills/marketplace-author/references/manifest-fields.md

@@ -0,0 +1,177 @@
+---
+source_keys:
+  - context7-websites-code-claude
+  - claude-code-plugins-docs
+  - context7-github-en-copilot
+  - 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. |
+| `metadata` | No | object | `{ "description"?: string, "version"?: string, "pluginRoot"?: string }` — Copilot CLI canonical location for top-level description and version. Claude Code also accepts `description` and `version` directly at the top level; use `metadata` for dual-tool repos. |
+| `description` | No | string | Top-level description — Claude Code only. For dual-tool repos, prefer `metadata.description` instead. |
+| `version` | No | string | Top-level marketplace version — Claude Code only. For dual-tool repos, prefer `metadata.version` instead. |
+| `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. |
+| `homepage` | No | string | URL for the plugin homepage or docs site. |
+| `repository` | No | string | URL for the plugin source repository. |
+| `license` | No | string | SPDX license identifier (e.g. `"MIT"`, `"Apache-2.0"`). |
+| `keywords` | No | string[] | Search terms for discovery (feeds into Discover tab search index). |
+| `category` | No | string | Single category label for grouping in the Discover tab. |
+| `tags` | No | string[] | Additional classification tags. |
+| `agents` | No | string or string[] | Override the path(s) to agent definition files inside the plugin directory. Defaults to `agents/`. |
+| `skills` | No | string or string[] | Override the path(s) to skill directories inside the plugin. Defaults to `skills/`. |
+| `commands` | No | string or string[] | Override the path(s) to command definition files. |
+| `hooks` | No | string or object | Override the path(s) to hook definitions. |
+| `mcpServers` | No | string or object | Override MCP server configuration for the plugin. |
+| `lspServers` | No | string or object | Override LSP server configuration for the plugin. |
+| `strict` | No | boolean | Default `true`. Set to `false` for relaxed schema validation — allows extra or CC-specific fields without failing Copilot CLI validation. Use this for dual Claude Code / Copilot CLI plugins. |
+
+---
+
+## 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" }
+    }
+  ]
+}
+```

plugins/kyberforge/skills/marketplace-author/references/sources.md

@@ -0,0 +1,147 @@
+---
+source_keys:
+  - context7-websites-code-claude
+  - claude-code-plugins-docs
+  - context7-github-en-copilot
+  - 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`
+
+## claude-code-subagents-docs
+
+- **URL:** https://code.claude.com/docs/en/sub-agents
+- **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md
+- **Description:** Official Claude Code subagent reference — definition format, all frontmatter fields, scope priority, built-in agents, CLI flags, environment variables, known limitations
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## context7-github-en-copilot
+
+- **URL:** context7:/websites/github_en_copilot
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** Official GitHub Copilot documentation indexed by Context7; covers CLI plugins, custom agents, SDK, and marketplace — including `metadata` object schema, per-entry optional fields, `strict` field behavior
+- **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`
+
+## github-custom-agents-configuration
+
+- **URL:** https://docs.github.com/en/copilot/reference/custom-agents-configuration
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** Reference for cloud and IDE custom agent definition format — frontmatter fields, tool aliases, MCP server config, secrets interpolation, scoping hierarchy
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## github-plugins-creating
+
+- **URL:** https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** How-to for creating Copilot CLI plugins — plugin structure, agent and skill authoring, hooks format, MCP config, development lifecycle
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## github-sdk-custom-agents
+
+- **URL:** https://docs.github.com/en/copilot/how-tos/copilot-sdk/features/custom-agents
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** SDK custom agent API — CustomAgentConfig fields in all five languages, session config, sub-agent lifecycle events, tool scoping, permission handling
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## github-changelog-copilot-extensions-ga
+
+- **URL:** https://github.blog/changelog/2025-02-19-announcing-the-general-availability-of-github-copilot-extensions/
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** Announcement of GitHub Copilot Extensions general availability (February 2025) — OIDC auth, all license tiers, VS Code/Visual Studio/JetBrains/GitHub.com support
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## github-changelog-copilot-extensions-sunset
+
+- **URL:** https://github.blog/changelog/2025-09-24-deprecate-github-copilot-extensions-github-apps/
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** Sunset notice for GitHub App-based Copilot Extensions — creation blocked Sep 24, 2025; full shutdown Nov 10, 2025; MCP servers recommended as replacement
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## github-docs-copilot-extensions-skillsets
+
+- **URL:** https://docs.github.com/en/copilot/concepts/build-copilot-extensions/skillsets-for-copilot-extensions
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** Concept doc for Copilot Extension skillsets — up to 5 skills per extension, Copilot handles routing/prompt crafting/response, contrast with agent extensions
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## github-docs-copilot-extensions-building
+
+- **URL:** https://docs.github.com/en/copilot/building-copilot-extensions/setting-up-copilot-extensions
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** How-to for setting up a Copilot Extension — GitHub App registration, Copilot Chat permission, Copilot Editor Context permission, backend URL configuration
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## vscode-chat-participant-api
+
+- **URL:** https://code.visualstudio.com/api/extension-guides/ai/chat
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** VS Code Chat Participant API — createChatParticipant(), package.json contributes.chatParticipants, Language Model API, @mention invocation in Copilot Chat
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## github-marketplace-copilot-extensions
+
+- **URL:** https://github.com/marketplace?type=apps&copilot_app=true
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** GitHub Marketplace listing for Copilot Extensions — browsable list of available extensions (historical; page remains live but product is sunset)
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## github-docs-marketplace-listing-requirements
+
+- **URL:** https://docs.github.com/en/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** Requirements for listing a GitHub App on the GitHub Marketplace — verified publisher, capability description, UX stability, submission and review process
+- **Contributing files:** (none)
+- **Status:** `referenced`

plugins/kyberforge/skills/plugin-author/README.md

@@ -0,0 +1,39 @@
+# plugin-author
+
+Creates, updates, and releases plugin scaffolds for the holocron marketplace.
+
+## What it does
+
+Manages both manifests (`plugin.json` for Copilot CLI and `.claude-plugin/plugin.json` for Claude Code) in one pass. Three operations: create a new plugin scaffold with placeholder manifests and skeleton dirs; update configuration fields (shared fields updated in both manifests simultaneously); release a version with HITL gate before tagging.
+
+Out of scope: plugin content (skills, agents, hooks, MCP servers inside those dirs) and `marketplace.json` entries.
+
+## Before you start
+
+Have ready: the plugin name (kebab-case) and the repo root path.
+
+## Usage
+
+```
+/plugin-author
+```
+
+**Manual scaffold (human workflow):**
+```bash
+bash scripts/new-plugin.sh <plugin-name> <repo-root>
+
+# Examples:
+bash scripts/new-plugin.sh my-tools /root/ai-development
+bash scripts/new-plugin.sh data-tools .
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `scripts/new-plugin.sh` | Scaffolds both manifests and skeleton dirs for a new plugin |
+| `references/manifest-fields.md` | All optional fields for both manifests beyond the scaffolded defaults |
+| `references/sources.md` | Research provenance — sources that informed this skill |
+| `scripts/README.md` | Directory meta-documentation for scripts/ |
+| `references/README.md` | Directory meta-documentation for references/ |

plugins/kyberforge/skills/plugin-author/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: plugin-author
+description: >
+  Use when the user wants to create a new plugin scaffold ("create a plugin
+  for X", "new plugin called Y"), update plugin configuration ("change the
+  description", "add keyword", "bump version"), or release a plugin version
+  ("release", "tag", "publish"). Manages both Claude Code
+  (.claude-plugin/plugin.json) and Copilot CLI (plugin.json) manifests in one
+  pass. Do not use when the request is about plugin content (skills, agents,
+  hooks, or MCP servers inside those directories). Do not use for
+  marketplace.json entries — use /marketplace-author for that.
+allowed-tools: Bash Read Write Edit
+metadata:
+  category: factory
+  source_keys:
+    - context7-websites-code-claude
+    - claude-code-plugins-docs
+    - claude-code-subagents-docs
+    - context7-github-en-copilot
+    - github-cli-plugin-reference
+    - github-plugins-creating
+    - github-plugins-finding-installing
+---
+
+## Gotchas
+
+- Both manifests must carry identical `version` values — version parity is a hard invariant (ADR-0016). Never update version in one manifest without updating the other in the same edit pass.
+- `author.email` is placed in the Copilot manifest by convention; `author.url` is placed in the CC manifest by convention. Both fields are supported by both platforms — do not add them to the other manifest without a deliberate reason.
+- `claude plugin tag --push` is irreversible: it creates a git tag and pushes it to remote. Always present the HITL gate and wait for explicit confirmation before running it.
+- `claude plugin tag --push` requires a clean working tree and will fail if there are uncommitted changes. Commit or stash all changes before running it.
+- `name` in both manifests must be kebab-case and must not use reserved prefixes: `anthropic-*`, `claude-*`, `agent-skills`, `official-claude-plugins`.
+- Copilot manifest lookup order: `.plugin/plugin.json` → `plugin.json` → `.github/plugin/plugin.json` → `.claude-plugin/plugin.json`. The canonical location for the Copilot manifest in this repo is `plugin.json` at the plugin root.
+- `displayName` is a CC platform field — Copilot has no equivalent. Do not add it to the Copilot manifest.
+- `skills`, `agents`, `hooks`, `mcpServers` are declared in the Copilot manifest by convention — Copilot requires explicit path declarations while CC auto-discovers content from the plugin root. Both platforms support these fields; omit them from the CC manifest by convention.
+- Agent files in a plugin's `agents/` directory silently ignore `hooks`, `mcpServers`, and `permissionMode` frontmatter fields.
+
+## Route
+
+Determine which flow before touching the filesystem. Read both manifest files if the plugin directory exists.
+
+- **Plugin directory does not exist** → follow **CREATE flow**
+- **Plugin directory exists + version/release intent** ("release", "tag", "bump", "publish", "version") → follow **RELEASE flow**
+- **Plugin directory exists + field change intent** ("update description", "add keyword", "change author") → follow **UPDATE flow**
+- **Ambiguous** → ask: "Did you mean to create a new plugin, update its configuration, or release a version?"
+
+Validate runs automatically before tagging (in RELEASE flow) and can be invoked explicitly at any time: `claude plugin validate plugins/<name>`.
+
+## CREATE flow
+
+### Prerequisites
+
+Before touching the filesystem, confirm you have:
+- [ ] Plugin name (kebab-case, e.g. `my-tools`)
+- [ ] Repo root (absolute path or `.` for current directory)
+
+If either is missing, stop and ask before proceeding.
+
+### Step 1 — Scaffold
+
+Run the scaffold script:
+
+```bash
+bash scripts/new-plugin.sh <name> <repo-root>
+```
+
+Examples:
+```bash
+bash scripts/new-plugin.sh my-tools /root/ai-development
+bash scripts/new-plugin.sh data-tools .
+```
+
+The script creates under `<repo-root>/plugins/<name>/`:
+- `plugin.json` — Copilot manifest with `FILL_IN_*` placeholders
+- `.claude-plugin/plugin.json` — CC manifest with `FILL_IN_*` placeholders
+- Empty skeleton directories: `skills/`, `agents/`, `hooks/`, `bin/`
+
+Each file/dir is a no-op if it already exists.
+
+### Step 2 — Fill in placeholders
+
+Open both manifest files and replace every `FILL_IN_*` placeholder.
+
+**Fields shared by both manifests** (must be identical in both):
+- `name` — kebab-case plugin identifier (already set by script; verify it is correct)
+- `description` — one or two sentences; what the plugin provides
+- `version` — SemVer; defaults to `1.0.0`; must be identical in both manifests
+- `author.name` — author display name
+- `license` — SPDX identifier (default: `MIT`)
+- `keywords` — search/discovery tags (default: `[]`)
+
+**CC manifest fields** (`.claude-plugin/plugin.json` only):
+- `displayName` — human-readable name shown in plugin manager; capitalised form of `name` (CC platform field — no Copilot equivalent)
+- `author.url` — author URL (e.g. Gitea profile URL) (both platforms support this; placed here by convention)
+
+**Copilot manifest fields** (`plugin.json` only):
+- `author.email` — author email (both platforms support this; placed here by convention)
+- `skills`, `agents`, `hooks`, `mcpServers` — paths; defaults are already set by the script (CC auto-discovers these; Copilot requires explicit declarations)
+
+### Step 3 — Validate
+
+Check:
+- [ ] `name` identical in both manifests, kebab-case, no reserved prefixes
+- [ ] `description` identical in both manifests, non-empty
+- [ ] `version` identical in both manifests (version parity — ADR-0016)
+- [ ] `author.name` identical in both manifests
+- [ ] `license` identical in both manifests
+- [ ] `keywords` identical in both manifests
+- [ ] No `FILL_IN_*` placeholders remain
+- [ ] `displayName` present in CC manifest only
+- [ ] `author.url` in CC manifest, `author.email` in Copilot manifest
+
+## UPDATE flow
+
+### Step 1 — Read both manifests
+
+Read `plugins/<name>/plugin.json` and `plugins/<name>/.claude-plugin/plugin.json`. Identify the current field values.
+
+### Step 2 — Classify each change
+
+For every field the user wants to change:
+
+| Change type | What to update |
+|---|---|
+| Shared field (`name`, `description`, `version`, `author.name`, `license`, `keywords`) | Both manifests in the same edit pass |
+| CC platform field (`displayName`) | `.claude-plugin/plugin.json` only — Copilot has no equivalent field |
+| Copilot platform fields (`category`, `tags`, `extensions`) | `plugin.json` only — not in the CC manifest schema |
+| CC scaffold convention (`author.url`) | `.claude-plugin/plugin.json` only — both platforms support this field; it is placed here by convention |
+| Copilot scaffold convention (`author.email`, `skills`, `agents`, `hooks`, `mcpServers`) | `plugin.json` only by convention — CC also supports these fields; CC auto-discovers content from the plugin root rather than requiring explicit path declarations |
+
+Never update a shared field in one manifest without updating the other in the same pass.
+
+If the target field is not listed in the classification table, read `references/manifest-fields.md` for the full field list and platform support notes.
+
+### Step 3 — Announce and apply
+
+State which fields change and which files are affected. Then apply. For `version` changes not part of a release, bump both manifests in the same edit.
+
+### Step 4 — Validate
+
+Re-run the validation checklist from CREATE flow Step 3 on both files.
+
+## RELEASE flow
+
+### Step 1 — Confirm version
+
+If the user has not stated the new SemVer version, ask: "What version are you releasing?" Do not proceed until you have the version.
+
+### Step 2 — Bump version in both manifests
+
+Update `version` in both `plugin.json` and `.claude-plugin/plugin.json` in the same edit pass. Confirm they are identical after the edit.
+
+### Step 3 — Validate
+
+Run:
+
+```bash
+claude plugin validate plugins/<name>
+```
+
+Use `--strict` to promote warnings to errors: `claude plugin validate --strict plugins/<name>`.
+
+Stop and report errors if validation fails. Do not proceed to tagging until validation passes.
+
+### Step 4 — HITL gate
+
+State exactly:
+
+> "I will run `claude plugin tag --push` for plugin `<name>`, which will create git tag `<name>--v<version>` and push it to remote. This is irreversible. Confirm?"
+
+Do not call the tool until the user explicitly confirms in the conversation.
+
+### Step 5 — Tag and release
+
+To preview without tagging or pushing: `claude plugin tag --dry-run`.
+
+After explicit confirmation, run from the repo root:
+
+```bash
+claude plugin tag --push
+```
+
+Report the created tag name and confirm the push completed.

plugins/kyberforge/skills/plugin-author/references/README.md

@@ -0,0 +1,9 @@
+# references/
+
+## manifest-fields.md
+
+Complete field reference for both plugin manifests. Covers all optional fields beyond the scaffolded defaults: field classification (shared / CC-only / Copilot-only), usage examples, and the version parity convention (ADR-0016). Loaded when a user asks to add a non-default field to either manifest.
+
+## 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, the scaffold script, and the manifest-fields reference. Used by `skill-audit` to validate the provenance chain.

plugins/kyberforge/skills/plugin-author/references/manifest-fields.md

@@ -0,0 +1,146 @@
+---
+topic: manifest-fields
+source_keys:
+  - context7-websites-code-claude
+  - claude-code-plugins-docs
+  - context7-github-en-copilot
+  - github-cli-plugin-reference
+  - github-plugins-creating
+  - github-plugins-finding-installing
+---
+
+# Manifest Fields Reference
+
+This document covers optional fields beyond the scaffolded defaults. Consult it when a user asks to add a non-default field to either manifest.
+
+## Field Classification
+
+Fields fall into three categories: **shared** (identical in both manifests), **platform** (one platform does not support the field at all), and **convention** (both platforms support the field, but the repo scaffold places it in one manifest only).
+
+> CC auto-discovers content (skills, agents, hooks, MCP servers) from the plugin root; Copilot requires explicit path declarations. Convention fields in the CC manifest are omitted unless you have a deliberate reason to add them.
+
+| Field | Copilot `plugin.json` | CC `.claude-plugin/plugin.json` | Notes |
+|---|---|---|---|
+| `name` | Yes (shared) | Yes (shared) | Identical in both; kebab-case; max 64 chars (Copilot) |
+| `description` | Yes (shared) | Yes (shared) | Identical in both; max 1024 chars (Copilot) |
+| `version` | Yes (shared) | Yes (shared) | Identical in both; SemVer; version parity required (ADR-0016) |
+| `author.name` | Yes (shared) | Yes (shared) | Identical in both |
+| `license` | Yes (shared) | Yes (shared) | Identical in both; SPDX identifier |
+| `keywords` | Yes (shared) | Yes (shared) | Identical in both; string array |
+| `displayName` | No (unsupported) | Yes | CC platform field — Copilot has no equivalent |
+| `author.url` | Omitted (convention) | Yes (convention) | Author profile URL; CC scaffold places here; Copilot also supports this field |
+| `author.email` | Yes (convention) | Omitted (convention) | Author email; Copilot scaffold places here; CC also supports this field |
+| `agents` | Yes (convention) | Omitted (convention) | Path or array; default: `agents/`; Copilot requires explicit declaration; CC auto-discovers |
+| `skills` | Yes (convention) | Omitted (convention) | Path or array; default: `skills/`; Copilot requires explicit declaration; CC auto-discovers |
+| `hooks` | Yes (convention) | Omitted (convention) | Path to hooks config; Copilot requires explicit declaration; CC auto-discovers |
+| `mcpServers` | Yes (convention) | Omitted (convention) | Path or object; Copilot requires explicit declaration; CC auto-discovers |
+| `category` | Yes | No (unsupported) | Marketplace category string; Copilot platform field — not in CC manifest schema |
+| `tags` | Yes | No (unsupported) | Additional taxonomy tags (distinct from `keywords`); Copilot platform field |
+| `extensions` | Yes | No (unsupported) | Path, array, or `{ paths, exclusive: true }` to disable built-ins; Copilot platform field |
+| `homepage` | Both (independent) | Both (independent) | Documentation URL; not required to be identical |
+| `repository` | Both (independent) | Both (independent) | Source repo URL |
+
+## Non-Default Optional Fields
+
+### `homepage`
+
+Documentation or project page URL. Shown in the plugin manager. Independent in each manifest — the two values do not need to match.
+
+```json
+// Copilot plugin.json
+{ "homepage": "https://example.com/docs" }
+
+// CC .claude-plugin/plugin.json
+{ "homepage": "https://example.com/docs" }
+```
+
+### `repository`
+
+Source repository URL. Independent in each manifest.
+
+```json
+{ "repository": "https://git.example.com/owner/repo" }
+```
+
+### `category` (Copilot-only)
+
+Marketplace browsing category. Single string. Copilot manifest only.
+
+```json
+{ "category": "developer-tools" }
+```
+
+### `tags` (Copilot-only)
+
+Additional taxonomy tags for Copilot marketplace browsing. Distinct from `keywords`.
+
+```json
+{ "tags": ["testing", "ci"] }
+```
+
+### `extensions` (Copilot-only)
+
+Path to extension files, an array of paths, or an object. Use `{ "paths": [...], "exclusive": true }` to disable built-in extensions.
+
+```json
+{ "extensions": "extensions/" }
+// or
+{ "extensions": { "paths": ["extensions/"], "exclusive": true } }
+```
+
+### `lspServers`
+
+Language Server Protocol configuration. Supported in both Copilot and CC manifests.
+
+```json
+{ "lspServers": ".lsp.json" }
+```
+
+### `outputStyles` (CC-only)
+
+Path to output styles directory. Claude Code manifest only.
+
+```json
+{ "outputStyles": "styles/" }
+```
+
+### `experimental.themes` (CC-only)
+
+Path to themes directory. Claude Code manifest only. Experimental — may change.
+
+```json
+{ "experimental": { "themes": "themes/" } }
+```
+
+### `experimental.monitors` (CC-only)
+
+Path to `monitors.json`. Claude Code manifest only. Experimental.
+
+```json
+{ "experimental": { "monitors": "monitors.json" } }
+```
+
+### `dependencies` (CC-only)
+
+Plugin dependencies. Each entry is a string (plugin name) or `{ "name": "<name>", "version": "<semver>" }`.
+
+```json
+{
+  "dependencies": [
+    "base-tools",
+    { "name": "data-tools", "version": "^2.0.0" }
+  ]
+}
+```
+
+### `commands` (legacy, both)
+
+Explicit list of `.md` command file paths. Deprecated in favour of `skills/`. Use `skills` instead for new plugins.
+
+## Version Parity Convention (ADR-0016)
+
+The `version` field must be present and identical in both manifests at all times. This is a hard invariant enforced by `/plugin-author` on every create, update, and release operation.
+
+- If only the CC manifest had `version` before this convention was introduced, backfill the Copilot manifest immediately.
+- Never change `version` in one manifest without changing it in the other in the same edit pass.
+- The RELEASE flow bumps both manifests simultaneously before tagging.

plugins/kyberforge/skills/plugin-author/references/sources.md

@@ -0,0 +1,158 @@
+---
+source_keys:
+  - context7-websites-code-claude
+  - claude-code-plugins-docs
+  - claude-code-subagents-docs
+  - context7-github-en-copilot
+  - github-cli-plugin-reference
+  - github-plugins-creating
+  - github-plugins-finding-installing
+  - github-custom-agents-configuration
+  - github-plugins-marketplace
+  - github-sdk-custom-agents
+  - github-changelog-copilot-extensions-ga
+  - github-changelog-copilot-extensions-sunset
+  - github-docs-copilot-extensions-skillsets
+  - github-docs-copilot-extensions-building
+  - vscode-chat-participant-api
+  - github-marketplace-copilot-extensions
+  - github-docs-marketplace-listing-requirements
+---
+
+# 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 — plugin manifest schema, marketplace JSON format, `claude plugin` CLI commands, validation, tagging
+- **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 — plugin structure, CC manifest fields (`displayName`, `author.url`, `version`, `outputStyles`, `experimental`), marketplace submission, `claude plugin tag`
+- **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 Copilot CLI plugin reference — `plugin.json` schema (all fields, types, constraints), marketplace.json schema, CLI commands, manifest lookup order
+- **Contributing files:** SKILL.md, references/manifest-fields.md
+- **Status:** `extracted`
+
+## github-plugins-creating
+
+- **URL:** https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** How-to for creating Copilot CLI plugins — plugin structure, Copilot manifest fields, development lifecycle, hooks format, MCP config
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+
+## github-plugins-finding-installing
+
+- **URL:** https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-and-installing
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** Finding and installing Copilot CLI plugins — install spec formats, marketplace registration, `copilot plugin` CLI commands
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+
+## claude-code-subagents-docs
+
+- **URL:** https://code.claude.com/docs/en/sub-agents
+- **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md
+- **Description:** Official Claude Code subagent reference — definition format, all frontmatter fields, scope priority, built-in agents, CLI flags, environment variables, known limitations
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+
+## context7-github-en-copilot
+
+- **URL:** context7:/websites/github_en_copilot
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** Official GitHub Copilot documentation indexed by Context7; covers CLI plugins, custom agents, SDK, and marketplace
+- **Contributing files:** SKILL.md, references/manifest-fields.md
+- **Status:** `extracted`
+
+## github-custom-agents-configuration
+
+- **URL:** https://docs.github.com/en/copilot/reference/custom-agents-configuration
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** Reference for cloud and IDE custom agent definition format — frontmatter fields, tool aliases, MCP server config, secrets interpolation, scoping hierarchy
+- **Contributing files:** (none)
+- **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 plugin marketplace — marketplace.json structure, hosting options, registration commands
+- **Contributing files:** (none)
+- **Status:** `extracted`
+
+## github-sdk-custom-agents
+
+- **URL:** https://docs.github.com/en/copilot/how-tos/copilot-sdk/features/custom-agents
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** SDK custom agent API — CustomAgentConfig fields in all five languages, session config, sub-agent lifecycle events, tool scoping, permission handling
+- **Contributing files:** (none)
+- **Status:** `extracted`
+
+## github-changelog-copilot-extensions-ga
+
+- **URL:** https://github.blog/changelog/2025-02-19-announcing-the-general-availability-of-github-copilot-extensions/
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** Announcement of GitHub Copilot Extensions general availability (February 2025) — OIDC auth, all license tiers, VS Code/Visual Studio/JetBrains/GitHub.com support
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## github-changelog-copilot-extensions-sunset
+
+- **URL:** https://github.blog/changelog/2025-09-24-deprecate-github-copilot-extensions-github-apps/
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** Sunset notice for GitHub App-based Copilot Extensions — creation blocked Sep 24, 2025; full shutdown Nov 10, 2025; MCP servers recommended as replacement
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## github-docs-copilot-extensions-skillsets
+
+- **URL:** https://docs.github.com/en/copilot/concepts/build-copilot-extensions/skillsets-for-copilot-extensions
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** Concept doc for Copilot Extension skillsets — up to 5 skills per extension, Copilot handles routing/prompt crafting/response, contrast with agent extensions
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## github-docs-copilot-extensions-building
+
+- **URL:** https://docs.github.com/en/copilot/building-copilot-extensions/setting-up-copilot-extensions
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** How-to for setting up a Copilot Extension — GitHub App registration, Copilot Chat permission, Copilot Editor Context permission, backend URL configuration
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## vscode-chat-participant-api
+
+- **URL:** https://code.visualstudio.com/api/extension-guides/ai/chat
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** VS Code Chat Participant API — createChatParticipant(), package.json contributes.chatParticipants, Language Model API, @mention invocation in Copilot Chat
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## github-marketplace-copilot-extensions
+
+- **URL:** https://github.com/marketplace?type=apps&copilot_app=true
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** GitHub Marketplace listing for Copilot Extensions — browsable list of available extensions (historical; page remains live but product is sunset)
+- **Contributing files:** (none)
+- **Status:** `referenced`
+
+## github-docs-marketplace-listing-requirements
+
+- **URL:** https://docs.github.com/en/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app
+- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
+- **Description:** Requirements for listing a GitHub App on the GitHub Marketplace — verified publisher, capability description, UX stability, submission and review process
+- **Contributing files:** (none)
+- **Status:** `referenced`

plugins/kyberforge/skills/plugin-author/scripts/README.md

@@ -0,0 +1,11 @@
+# scripts/
+
+## new-plugin.sh
+
+Scaffolds a new plugin directory with both manifests and empty skeleton dirs.
+
+```
+Usage: new-plugin.sh <plugin-name> <repo-root>
+```
+
+Creates `<repo-root>/plugins/<plugin-name>/` containing: `plugin.json` (Copilot manifest), `.claude-plugin/plugin.json` (CC manifest), and empty `skills/`, `agents/`, `hooks/`, `bin/` directories. Both manifest files carry `FILL_IN_*` placeholders for fields the user must supply. Each file and directory is a no-op if it already exists. Does not touch `marketplace.json`. See `--help` for full usage.

plugins/kyberforge/skills/plugin-author/scripts/new-plugin.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# source_keys: github-cli-plugin-reference github-plugins-creating
+set -euo pipefail
+
+usage() {
+  cat <<EOF
+Usage: new-plugin.sh <plugin-name> <repo-root>
+
+Scaffold a new plugin directory with both manifests and skeleton dirs.
+
+Arguments:
+  plugin-name  Kebab-case plugin identifier (e.g. my-tools, data-tools).
+               Must be lowercase letters, numbers, and hyphens only.
+               No leading, trailing, or consecutive hyphens.
+  repo-root    Absolute or relative path to the repository root.
+               The plugin is created at <repo-root>/plugins/<plugin-name>/.
+
+Created structure:
+  <repo-root>/plugins/<plugin-name>/
+    plugin.json                     Copilot CLI manifest (FILL_IN_* placeholders)
+    .claude-plugin/
+      plugin.json                   Claude Code manifest (FILL_IN_* placeholders)
+    skills/                         Empty skeleton directory
+    agents/                         Empty skeleton directory
+    hooks/                          Empty skeleton directory
+    bin/                            Empty skeleton directory
+
+Each file and directory is a no-op if it already exists.
+Does NOT touch marketplace.json.
+
+Exit codes:
+  0  Files created or already existed (no-op)
+  1  Invalid arguments or missing root
+EOF
+}
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  usage
+  exit 0
+fi
+
+if [[ $# -lt 2 ]]; then
+  echo "Error: plugin-name and repo-root are required." >&2
+  echo "" >&2
+  usage >&2
+  exit 1
+fi
+
+PLUGIN_NAME="$1"
+REPO_ROOT="$2"
+
+# Validate plugin name format
+if ! echo "$PLUGIN_NAME" | grep -qE '^[a-z0-9]+(-[a-z0-9]+)*$'; then
+  echo "Error: plugin-name must use lowercase letters, numbers, and hyphens only." >&2
+  echo "       No leading, trailing, or consecutive hyphens." >&2
+  echo "       Received: '$PLUGIN_NAME'" >&2
+  exit 1
+fi
+
+# Expand tilde
+REPO_ROOT="${REPO_ROOT/#\~/$HOME}"
+
+# Resolve to absolute path
+REPO_ROOT="$(cd "$REPO_ROOT" 2>/dev/null && pwd)" || {
+  echo "Error: repo-root directory '$2' does not exist." >&2
+  exit 1
+}
+
+PLUGIN_DIR="$REPO_ROOT/plugins/$PLUGIN_NAME"
+CC_DIR="$PLUGIN_DIR/.claude-plugin"
+COPILOT_MANIFEST="$PLUGIN_DIR/plugin.json"
+CC_MANIFEST="$CC_DIR/plugin.json"
+
+# Create directory skeleton
+created_any=false
+
+create_dir_if_missing() {
+  local dir="$1"
+  if [[ -d "$dir" ]]; then
+    echo "Skipping directory '$dir' — already exists." >&2
+  else
+    mkdir -p "$dir"
+    echo "Created directory: $dir" >&2
+    created_any=true
+  fi
+}
+
+create_dir_if_missing "$PLUGIN_DIR"
+create_dir_if_missing "$CC_DIR"
+create_dir_if_missing "$PLUGIN_DIR/skills"
+create_dir_if_missing "$PLUGIN_DIR/agents"
+create_dir_if_missing "$PLUGIN_DIR/hooks"
+create_dir_if_missing "$PLUGIN_DIR/bin"
+
+# Create Copilot manifest (plugin.json)
+if [[ -f "$COPILOT_MANIFEST" ]]; then
+  echo "Skipping '$COPILOT_MANIFEST' — already exists." >&2
+else
+  cat > "$COPILOT_MANIFEST" <<COPILOT_JSON
+{
+  "name": "$PLUGIN_NAME",
+  "description": "FILL_IN_DESCRIPTION",
+  "version": "1.0.0",
+  "author": { "name": "FILL_IN_AUTHOR_NAME", "email": "FILL_IN_AUTHOR_EMAIL" },
+  "license": "MIT",
+  "keywords": [],
+  "agents": "agents/",
+  "skills": ["skills/"],
+  "hooks": "hooks.json",
+  "mcpServers": ".mcp.json"
+}
+COPILOT_JSON
+  echo "Created: $COPILOT_MANIFEST" >&2
+  created_any=true
+fi
+
+# Create Claude Code manifest (.claude-plugin/plugin.json)
+if [[ -f "$CC_MANIFEST" ]]; then
+  echo "Skipping '$CC_MANIFEST' — already exists." >&2
+else
+  cat > "$CC_MANIFEST" <<CC_JSON
+{
+  "name": "$PLUGIN_NAME",
+  "displayName": "FILL_IN_DISPLAY_NAME",
+  "description": "FILL_IN_DESCRIPTION",
+  "version": "1.0.0",
+  "author": { "name": "FILL_IN_AUTHOR_NAME", "url": "FILL_IN_AUTHOR_URL" },
+  "license": "MIT",
+  "keywords": []
+}
+CC_JSON
+  echo "Created: $CC_MANIFEST" >&2
+  created_any=true
+fi
+
+if [[ "$created_any" == false ]]; then
+  echo "All files already exist — nothing to do." >&2
+else
+  echo "" >&2
+  echo "Plugin: $PLUGIN_NAME" >&2
+  echo "Location: $PLUGIN_DIR" >&2
+  echo "" >&2
+  echo "Next steps:" >&2
+  echo "  1. Fill in $COPILOT_MANIFEST — replace all FILL_IN_* placeholders" >&2
+  echo "  2. Fill in $CC_MANIFEST — replace all FILL_IN_* placeholders" >&2
+  echo "  3. Verify version is identical in both manifests (version parity — ADR-0016)" >&2
+  echo "  4. Add plugin content: skills in skills/, agents in agents/, etc." >&2
+fi