Defame1297
3a91126d3f
## 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>
5.5 KiB
topic, source_keys
| topic | source_keys | ||||||
|---|---|---|---|---|---|---|---|
| manifest-fields |
|
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.
// 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.
{ "repository": "https://git.example.com/owner/repo" }
category (Copilot-only)
Marketplace browsing category. Single string. Copilot manifest only.
{ "category": "developer-tools" }
tags (Copilot-only)
Additional taxonomy tags for Copilot marketplace browsing. Distinct from keywords.
{ "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.
{ "extensions": "extensions/" }
// or
{ "extensions": { "paths": ["extensions/"], "exclusive": true } }
lspServers
Language Server Protocol configuration. Supported in both Copilot and CC manifests.
{ "lspServers": ".lsp.json" }
outputStyles (CC-only)
Path to output styles directory. Claude Code manifest only.
{ "outputStyles": "styles/" }
experimental.themes (CC-only)
Path to themes directory. Claude Code manifest only. Experimental — may change.
{ "experimental": { "themes": "themes/" } }
experimental.monitors (CC-only)
Path to monitors.json. Claude Code manifest only. Experimental.
{ "experimental": { "monitors": "monitors.json" } }
dependencies (CC-only)
Plugin dependencies. Each entry is a string (plugin name) or { "name": "<name>", "version": "<semver>" }.
{
"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
versionbefore this convention was introduced, backfill the Copilot manifest immediately. - Never change
versionin one manifest without changing it in the other in the same edit pass. - The RELEASE flow bumps both manifests simultaneously before tagging.