Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions docs/MIGRATION-PLAYBOOK.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,15 @@ Applying that precedence, the grammar of an invocation is `/<namespace>:<skill>`
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 `(<plugin-name>)
<description>`. 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.
Expand Down
12 changes: 12 additions & 0 deletions docs/PLUGIN-PHILOSOPHY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
`(<plugin-name>) <description>`, a personal skill as `<description> (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
Expand Down
13 changes: 12 additions & 1 deletion docs/topics/plugin-organization/PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `(<plugin-name>) …`, 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
Expand Down