fix(kyberforge): correct field classification and fill provenance gaps in plugin-author and marketplace-author
## Why
The manifest-fields tables in both skills used imprecise labels ("CC-only",
"Copilot-only") that conflated two distinct reasons a field appears in only
one manifest: platform constraint (the other tool does not support the field
at all) versus repo convention (both tools support it, but the scaffold places
it in one manifest by design). This caused agents to treat convention
boundaries as hard platform constraints, producing unnecessary errors when
updating manifests for dual-tool repos.
Provenance was also incomplete: sources.md files were missing entries for
sources that had been consulted and were already contributing to SKILL.md
and manifest-fields.md content, making the evidence chain unverifiable.
## Implementation Notes
Field classification now uses three explicit categories — shared, platform
(one tool does not support the field), and convention (both tools support it;
scaffold places it in one manifest by design). The distinction matters because
convention fields may legitimately appear in the other manifest when there is
a deliberate reason; platform fields may not.
New gotchas added to plugin-author: agent files silently ignore hooks,
mcpServers, and permissionMode frontmatter; claude plugin tag --push requires
a clean working tree; --dry-run preview before tagging; --strict flag on
validate. New gotchas in marketplace-author: metadata object as Copilot CLI
canonical location for top-level fields; strict: false for dual-tool plugins;
sha takes precedence over ref for pinning; --strict flag on validate.
tests/ removed from plugin-author because new-plugin.sh has no branching
logic warranting a bats suite at this stage.
## Impact
Skill prompt changes only — no runtime code affected. Agents using these
skills will now correctly distinguish convention from constraint when deciding
which manifest to update for a given field.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -6,14 +6,17 @@ description: >
|
||||
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. Explicitly out of scope: plugin content (skills, agents, hooks, MCP
|
||||
servers) and marketplace.json entries — use /marketplace-author for those.
|
||||
pass. Do not use when the request is about plugin content (skills, agents,
|
||||
hooks, MCP servers) or marketplace.json entries — use /marketplace-author
|
||||
for those.
|
||||
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
|
||||
@@ -22,12 +25,14 @@ metadata:
|
||||
## 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` belongs in the Copilot manifest (`plugin.json`); `author.url` belongs in the CC manifest (`.claude-plugin/plugin.json`). Do not swap them.
|
||||
- `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 CC-only — do not add it to the Copilot manifest.
|
||||
- `skills`, `agents`, `hooks`, `mcpServers` are Copilot-only fields — do not add them to the CC manifest.
|
||||
- `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
|
||||
|
||||
@@ -38,7 +43,7 @@ Determine which flow before touching the filesystem. Read both manifest files if
|
||||
- **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.
|
||||
Validate runs automatically before tagging (in RELEASE flow) and can be invoked explicitly at any time: `claude plugin validate plugins/<name>`.
|
||||
|
||||
## CREATE flow
|
||||
|
||||
@@ -83,13 +88,13 @@ Open both manifest files and replace every `FILL_IN_*` placeholder.
|
||||
- `license` — SPDX identifier (default: `MIT`)
|
||||
- `keywords` — search/discovery tags (default: `[]`)
|
||||
|
||||
**CC-only fields** (`.claude-plugin/plugin.json` only):
|
||||
- `displayName` — human-readable name shown in plugin manager; capitalised form of `name`
|
||||
- `author.url` — author URL (e.g. Gitea profile URL)
|
||||
**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-only fields** (`plugin.json` only):
|
||||
- `author.email` — author email
|
||||
- `skills`, `agents`, `hooks`, `mcpServers` — paths; defaults are already set by the script
|
||||
**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
|
||||
|
||||
@@ -116,11 +121,15 @@ 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-only (`displayName`, `author.url`) | `.claude-plugin/plugin.json` only |
|
||||
| Copilot-only (`author.email`, `skills`, `agents`, `hooks`, `mcpServers`, `category`, `tags`, `extensions`) | `plugin.json` only |
|
||||
| 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.
|
||||
@@ -147,6 +156,8 @@ Run:
|
||||
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
|
||||
@@ -159,6 +170,8 @@ 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
|
||||
|
||||
Reference in New Issue
Block a user