Proposal: portable qualified names for plugin skills (<plugin>:<skill>) and ambiguity behavior

[danielmeppiel]

Problem

Agent Plugins 1.1.0 standardizes how a plugin supplies skills, but not how a client names a plugin's skill once it is loaded. When two installed plugins each ship a skill with the same name, each client resolves it differently. As a result, authors cannot write portable instructions such as "use the review skill from plugin alpha".

Agent Skills requires name to match the skill's directory name. Package managers and installers therefore cannot safely disambiguate by renaming skills; that would break the Agent Skills contract and the author's own references. Namespacing has to come from the plugin layer.

Current behavior varies

The following comparison was reported with the same two plugins in github/copilot-cli#5249 (2026-10-23):

Client	Unique skill	Colliding skill	Bare colliding name
Claude Code	alpha:unique	alpha:shared, beta:shared	also loads as an alias
Codex CLI	alpha:unique	alpha:shared, beta:shared	not listed
Copilot CLI	bare for the model, /alpha:unique for slash commands	alpha:shared, beta:shared	ambiguity error
Pi (default)	unique	only one copy kept	only name listed

Several clients already converge on <plugin>:<skill>, but the behavior is not specified, so authors and installers cannot rely on it.

Proposal (for discussion)

1. Qualified name. A loaded plugin skill has a qualified name <plugin-name>:<skill-name>, where <plugin-name> is the manifest name and <skill-name> is the Agent Skills name. Clients MUST accept the qualified name everywhere they accept a skill name (user invocation and model-facing tools).
2. Bare names. Clients MAY also accept the bare <skill-name> when it is unambiguous. When it is ambiguous, they MUST NOT silently pick or drop a copy; they MUST require the qualified name.
3. No renaming. Clients and installers MUST NOT rewrite a skill's name or directory to achieve uniqueness.
4. Out of scope: nested sub-namespaces, which Proposal: A mechanism for lazy progressive discovery of (possibly namespaced), vendor-bundled skills agentskills/agentskills#656 explores for vendor bundles, and non-skill components. These could follow the same pattern later.

Who hits this

• Plugin authors writing cross-client instructions.
• Clients loading several plugins at once.
• Package managers that install plugins for multiple clients. For example, APM keeps skill names intact and points its users to native plugin namespacing ([FEATURE] Support package namespaces microsoft/apm#739).

APM will follow whatever qualified-name contract the specification adopts and will not invent its own prefixing.

Related: agentskills/agentskills#656, github/copilot-cli#5249, github/copilot-cli#1766.