diff --git a/docs/MIGRATION-PLAYBOOK.md b/docs/MIGRATION-PLAYBOOK.md index 41151e4ec..2c9a3ab55 100644 --- a/docs/MIGRATION-PLAYBOOK.md +++ b/docs/MIGRATION-PLAYBOOK.md @@ -117,10 +117,12 @@ Applying that precedence, the grammar of an invocation is `/:` is failing at its job — the namespace is not naming the domain, or the skill is not naming its action. Fix it by, in preference order: rename the skill to its real action verb; rename the plugin to its domain noun; decompose, when the single skill actually hides distinct discovery - intents (per the Organization section's split rule above). The one exemption is + intents (per the Organization section's split rule above). Two exemptions: **root-echo** — the domain's core action shares the domain's root word - (`implementation:implement`, `code-tidying:tidy`, `work-items:work`); that is honest naming, not - a true doubling, and is accepted. + (`implementation:implement`, `code-tidying:tidy`, `work-items:work`) — and + **wrapper-echo** — a single-skill vendor-CLI wrapper whose one router skill repeats the tool + name (`firecrawl:firecrawl`, `playwright:playwright`), per the philosophy's Naming section. + Both are honest naming, not true doubling, and are accepted. - **Skill families order base-concept-first.** Sibling skills sharing a base concept put the base first (`design`, `design-handoff`, `implement`, `implement-dispatch`) so prefix typeahead and sorted listings group the family. A standalone skill keeps natural English order (`batch-simplify`, `quality-gate`). @@ -132,11 +134,12 @@ Applying that precedence, the grammar of an invocation is `/:` (a dispatch variant of `research`) are siblings on this axis; the `-deep` suffix names that isolation tier, not a depth knob on the same execution path — a true effort knob on one execution path still takes an argument. -- **A vendor-CLI plugin names its skills after the vendor's own CLI verbs.** A tool-scoped plugin - wrapping a CLI mirrors that CLI's verb vocabulary — `/playwright:test` mirrors - `npx playwright test`; a firecrawl decomposition would use `scrape` / `crawl` / `map` per - `firecrawl-cli` — the consumer already knows the vendor's verbs. -- **Generic skill names are safe under namespacing** (`help`, `list`, `configure`) — the overloaded-term +- **A vendor-CLI plugin that decomposes names its skills after the vendor's own CLI verbs.** When a + tool-scoped plugin splits into multiple skills, it mirrors that CLI's verb vocabulary — + `/playwright:test` would mirror `npx playwright test`; a firecrawl decomposition would use + `scrape` / `crawl` / `map` per `firecrawl-cli` — the consumer already knows the vendor's verbs. + While it remains a single-skill router, the wrapper-echo exemption above applies instead. +- **Generic skill names are safe under namespacing** (`help`, `list`, `update`) — the overloaded-term caution governs plugin *identity*, not a namespaced skill leaf. - **Tool-scope shows up as brand-in-name, not a structural split.** A branded name signals a tool-scoped plugin; a plain domain-noun signals a tool-agnostic one. No marketplace separates plugins by tool-scope @@ -286,8 +289,8 @@ a skill ships them only when they earn their keep. that could silently regress — how it triggers, how it routes an ambiguous request, when it refuses, or the shape of what it emits. A skill is an explicit **skip** when it is pure-reference (answers from a knowledge corpus with no decision contract — `playbooks:fable-5`, `tdd`, …) or lives in a **hook** plugin -(deterministic, silent-always-on, guarded by `.test.sh`, no model-invoked skill). A `setup` / -`configure` skill *is* warrantable — it makes interview and write-config decisions (the +(deterministic, silent-always-on, guarded by `.test.sh`, no model-invoked skill). A `setup` +skill *is* warrantable — it makes interview and write-config decisions (the `codebase-health/setup` eval is the model). Gray-zone skills (thin mechanical wrappers, reference-ish routers) are **author-confirm**: re-check the warrant against the live `SKILL.md` at authoring time and record an explicit skip verdict if it dissolves — a satisfied "looks covered" is not a warrant. diff --git a/docs/PLUGIN-PHILOSOPHY.md b/docs/PLUGIN-PHILOSOPHY.md index 94f7e9716..ccd3e995e 100644 --- a/docs/PLUGIN-PHILOSOPHY.md +++ b/docs/PLUGIN-PHILOSOPHY.md @@ -24,11 +24,47 @@ Keep plugins horizontally decoupled: (`claude plugin tag --push`) with it. - Every plugin remains useful alone. If an optional collaborator is absent, use a documented fallback or report the missing optional capability clearly. +- Every cross-plugin reference is therefore either declared (the `dependencies` array above, which + Claude Code installs automatically) or guarded behind an "if installed" check with the documented + fallback. A bare unguarded cross-plugin reference is a defect. This follows Claude Code's distinction between project-specific standalone configuration and plugins intended for reusable, versioned distribution. Namespaced skill invocations are part of that isolation, not an implementation detail. +## Naming + +A skill name is an imperative verb phrase; the plugin namespace supplies the object +(`/machine-health:audit`, `/source-control:commit`). Names compose into instruction sentences — +"/discovery:explore the module, then /planning:interview me" — and one grammar keeps every name in +the marketplace predictable. This is a deliberate, documented deviation from the official authoring +guidance's gerund preference; that guidance sanctions imperative alternatives and treats +collection-wide consistency as a requirement, which this section provides. + +Verb meanings are fixed: + +| Verb | Contract | +|---|---| +| `audit`, `scan` | Read-only findings report. Mutation only behind an explicit user override such as an autofix argument, never on bare invocation; safety qualifiers may narrow what an override touches. | +| `check` | Deterministic pass/fail gate. | +| `clean`, `tidy`, `fix` | Mutates the target. | +| `setup` | Configures the plugin for a consumer, per the setup section below. | +| `update` | Refreshes vendored upstream material. | + +When a bare verb would collide with or under-specify against a sibling in the same namespace, a +topic qualifier follows the verb with a hyphen (`audit-noise` beside `audit-encapsulation`, +`scan-todos` under `work-items`); the verb keeps its fixed meaning from the table. + +Nouns are reserved for knowledge routers (`principles`, `methodology`) and lifecycle-object routers +(`worktree`, `pull-request`). Two further documented exceptions: a single-skill vendor-CLI wrapper +repeats its tool name (`firecrawl:firecrawl`), and a `-deep` suffix marks the heavier +isolated-execution tier of a sibling skill (`explore`/`explore-deep`). + +The frontmatter `name` always matches the skill directory name, in the character set the Agent +Skills specification allows. Never degrade a name to dodge a built-in command: plugin skills are +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. + ## Native-first Prefer a built-in native mechanism — `userConfig`, a native component type, a native lifecycle @@ -236,3 +272,14 @@ authoritative self-updating master list. Pages load-bearing for this document, v the special storage and read scopes of `pluginConfigs`. - `melodic-software/standards` engineering philosophy and cross-platform review criteria — repository design and verification policy. + +Verified 2026-07-17: + +- [Plugin dependencies](https://code.claude.com/docs/en/plugin-dependencies) — the `dependencies` + array, automatic installation, and version constraints. +- [Skills](https://code.claude.com/docs/en/skills) — command-name derivation and the plugin skill + namespace. +- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) + — naming-convention guidance this document deviates from deliberately. +- [Agent Skills specification](https://agentskills.io/specification) — `name` field constraints and + directory matching.