Plugin commands/skills: support `aliases` for NL routing + optional native disambiguation
Problem
Plugin commands (commands/*.md) and skills (skills/*/SKILL.md) only route from natural language via a semantic match on the description field. There is no way to declare alternate trigger phrases, and no native disambiguation when several commands plausibly match. In practice:
- To make phrasings like "ship it" / "push it up" / "open the PR" / "run full git" reliably reach one command, you have to stuff a keyword list of trigger phrases into the
description— which is also doing double duty as human-facing documentation. It's brittle, and for non-English teams you end up maintaining phrases in two languages inside the description. - When two commands could match (e.g. "commit + push + open PR" vs "resolve the review comments"), the model just picks one — there's no built-in "which did you mean?" step.
Confirmed there is no aliases frontmatter field today; NL auto-invocation considers only description (+ its char budget), and disambiguation isn't a native feature.
Proposal
- An
aliases:frontmatter array oncommands/*.mdandskills/*/SKILL.md— alternate trigger phrases considered for NL auto-invocation, kept separate from the human-readabledescription:
``yaml``
---
description: Run the full git flow (stage, commit, push, open/update the PR).
aliases: ["run full git", "ship it", "push it up", "open the PR", "commit and push"]
---
- (Optional) A native disambiguation signal — e.g.
disambiguate: trueor a shared group key — so that when more than one command matches, Claude asks "did you mean X or Y?" instead of silently guessing.
Workaround today
Keyword-dense description fields plus a disambiguation instruction placed in an always-injected rule (SessionStart hook). It works, but it couples triggers to docs, burns the description char budget, and can't guarantee the ask-when-ambiguous behavior.
Why it matters
Teams shipping shared plugins (single-sourcing style/git rules across multiple repos) want stable verbal shortcuts and predictable routing. Today that means prompt-engineering the description and hoping the match lands — a first-class aliases field (and optional disambiguation) would make plugin command routing deterministic and much easier to maintain.
---
_Filed from real usage while hardening a team plugin's git/PR commands._