From b602b9335f5e5724cbc9d385475e7f450b52da31 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 20 Jul 2026 13:17:11 -0400 Subject: [PATCH 1/2] docs(naming): separate the invocation guarantee from picker display The naming doctrine reasoned about invocation namespacing and model-side auto-invocation ambiguity, but never about what a human reads in the `/` picker. "Namespaced and cannot collide" is a resolution claim, and it is easy to carry over to presentation, where it does not hold. Claude Code 2.1.215 labels a picker row with the skill's leaf name and registers the namespaced form as a hidden alias. Origin travels in the description: `() ` for a plugin skill, a `(user)` / `(project)` suffix for personal and project skills, and no marker at all for built-in, bundled, and MCP entries. Every locked decision stands. D19's shadow-dodge names are unambiguously invocable; the built-in keeps the bare token and the plugin skill is reachable at its namespaced alias, exactly as documented. What changes is that a shared leaf name is now recorded as a legibility cost in the description column rather than an unexamined non-issue. Resolves the standing deferred question on typeahead prefix filtering, and records the upstream trigger for a namespaced picker label. Closes #710 Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_011ogVV7z2Heg9ojJ88nqNxh --- docs/MIGRATION-PLAYBOOK.md | 9 +++++++++ docs/PLUGIN-PHILOSOPHY.md | 11 +++++++++++ docs/topics/plugin-organization/PLAN.md | 13 ++++++++++++- 3 files changed, 32 insertions(+), 1 deletion(-) 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..01f6e66779b 100644 --- a/docs/PLUGIN-PHILOSOPHY.md +++ b/docs/PLUGIN-PHILOSOPHY.md @@ -71,6 +71,17 @@ 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 or project skill as ` (user)` or +`(project)`, 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 From e50bd6d3448fd1d788a13238d9e9e080cd50e146 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 20 Jul 2026 13:37:34 -0400 Subject: [PATCH 2/2] docs(naming): name the local-settings picker marker The display paragraph presented the source markers as the full contract but listed only (user) and (project), so it misdescribed the common local-settings case: 2.1.215 maps localSettings to "project, gitignored", not "project". Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_011ogVV7z2Heg9ojJ88nqNxh --- docs/PLUGIN-PHILOSOPHY.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/PLUGIN-PHILOSOPHY.md b/docs/PLUGIN-PHILOSOPHY.md index 01f6e66779b..7ba639b9403 100644 --- a/docs/PLUGIN-PHILOSOPHY.md +++ b/docs/PLUGIN-PHILOSOPHY.md @@ -75,8 +75,9 @@ That guarantee is about **resolution**, and it does not extend to **display**. T 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 or project skill as ` (user)` or -`(project)`, and a built-in, bundled, or MCP entry carries no marker at all. So sibling short names +`() `, 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,