Plugin commands/skills: support `aliases` for NL routing + optional native disambiguation

Open 💬 0 comments Opened Jul 8, 2026 by JohanAlvarado

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

  1. An aliases: frontmatter array on commands/*.md and skills/*/SKILL.md — alternate trigger phrases considered for NL auto-invocation, kept separate from the human-readable description:

``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"]
---
``

  1. (Optional) A native disambiguation signal — e.g. disambiguate: true or 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._

View original on GitHub ↗