diff --git a/docs/MIGRATION-PLAYBOOK.md b/docs/MIGRATION-PLAYBOOK.md index 6579814325d..e20aa8f0a6e 100644 --- a/docs/MIGRATION-PLAYBOOK.md +++ b/docs/MIGRATION-PLAYBOOK.md @@ -153,6 +153,15 @@ Applying that precedence, the grammar of an invocation is `/:` The one residual caution is model-side: avoid a skill leaf name *identical* to a bundled skill's (auto-invocation ambiguity when the model matches descriptions); similarity alone is fine. +**That namespace guarantee covers invocation, not the slash-command listing.** The picker labels a +row with the skill's short name and keeps the namespaced form as a hidden alias, so a leaf name +shared across plugins reads identically in the list even though each is separately invocable; the +plugin name reaches the reader through the description, which renders as `() +`. See the philosophy's Naming section for the full display contract. Two consequences +for this playbook: prefix typeahead groups a family by its **leaf** name, which is what the +base-concept-first rule above is buying; and a deliberately shared leaf name (`setup` across every +plugin that ships one) is legible only if each description's first clause names its object. + ## Extensibility model — what works today These are the proven, documented mechanisms for consumer customization that do not confuse the agent. diff --git a/docs/PLUGIN-PHILOSOPHY.md b/docs/PLUGIN-PHILOSOPHY.md index 6378082a369..7ba639b9403 100644 --- a/docs/PLUGIN-PHILOSOPHY.md +++ b/docs/PLUGIN-PHILOSOPHY.md @@ -71,6 +71,18 @@ Skills specification allows. Never degrade a name to dodge a built-in command: p namespaced and cannot collide with other levels. When a name matches a built-in, the bare token still belongs to the built-in; the namespaced form is the plugin skill's only command. +That guarantee is about **resolution**, and it does not extend to **display**. The slash-command +picker lists a skill by its short name and registers the namespaced form as a hidden alias — so +`/planning:` still filters to that plugin's skills, but `planning:plan` is not what the row is +labelled. Origin travels in the description instead: a plugin skill renders as +`() `, a personal skill as ` (user)`, a project skill as +`(project)` or `(project, gitignored)` depending on whether it came from shared or local settings, +and a built-in, bundled, or MCP entry carries no marker at all. So sibling short names +across different plugins are unambiguous to *invoke* and identical to *read* — a shared leaf name +costs legibility in the description column, never correctness. Weigh it there; never rename to buy +display uniqueness, and keep the description's first clause carrying the distinguishing object, +since that column is what a reader actually scans. + ## Native-first Prefer a built-in native mechanism — `userConfig`, a native component type, a native lifecycle diff --git a/docs/topics/plugin-organization/PLAN.md b/docs/topics/plugin-organization/PLAN.md index 0ee7007ba7c..d07a898adeb 100644 --- a/docs/topics/plugin-organization/PLAN.md +++ b/docs/topics/plugin-organization/PLAN.md @@ -78,10 +78,21 @@ history; grouping lives in marketplace metadata. - Empty `deployment` category — created when first deploy plugin lands. - `music` → `creative` rename — trigger: a non-music creative plugin lands. - fable-5 regeneration — trigger: model-version change (self-authored, no upstream). +- Namespaced picker labels — trigger: anthropics/claude-code#25150 ships a namespaced name column. + Until then the leaf name is the label and the plugin name reaches the reader via the description + prefix; revisit whether any description carries disambiguating text it would no longer need. ### Deferred questions -- Empirical check: typeahead prefix filtering on plugin-skill leaf names — `/planning:plan`. +- ~~Empirical check: typeahead prefix filtering on plugin-skill leaf names — `/planning:plan`.~~ + **Resolved (Claude Code 2.1.215).** The picker labels each row with the **leaf** name and registers + the namespaced form as a hidden alias, so `/planning:` filters correctly while the row still reads + `plan`. Typeahead therefore groups families by leaf name — the base-concept-first rule (D20) is + what makes that grouping work. Origin is rendered in the description as `() …`, which + is the only thing distinguishing the 8 shared leaf names (`setup` ×33, `audit` ×6, + `check`/`clean`/`diagnose`/`plan`/`workflow`/`write` ×2). D19 stands unchanged: every one of those + is separately invocable, so no name was kept or dropped on a mistaken premise. Doctrine updated in + `docs/PLUGIN-PHILOSOPHY.md` (Naming) and `docs/MIGRATION-PLAYBOOK.md` (Naming). - session-flow category label `workflow` — judgment call (no marketplace precedent); revisit if a stronger authoritative label emerges. ## Plan