diff --git a/cc-os-plugin-skill-naming-convention.md b/cc-os-plugin-skill-naming-convention.md new file mode 100644 index 0000000..353f95f --- /dev/null +++ b/cc-os-plugin-skill-naming-convention.md @@ -0,0 +1,63 @@ +--- +type: convention +title: cc-os Plugin and Skill Naming Convention +source: cc-os +summary: When creating or naming a cc-os plugin or skill, use the `os-` prefix (for plugins) and verb-first names (for skills) to make invocations unambiguous and readable. +tags: + - type/convention + - project/cc-os + - tool/claude-code +scope: global +last_updated: 2026-07-02 +date: 2026-07-02 +related: + - vault-conventions + - CLAUDE +--- + +# cc-os Plugin and Skill Naming Convention + +Established 2026-07-02, when the `memory` plugin was renamed to `os-vault` and its skills renamed to verb-first names. + +## Purpose + +This convention ensures that cc-os plugins and skills are named consistently, unambiguously, and in a way that communicates their purpose at a glance. The naming strategy disambiguates cc-os components from adjacent Claude Code tools (like `memsearch`, which is NOT part of cc-os) and produces command invocations that read naturally as action + object. + +## Core Principles + +**1. Plugins use an `os-` prefix.** Each cc-os plugin name starts with `os-` (e.g., `os-vault`), visually tying it to the cc-os project and making it instantly distinguishable from unrelated plugins. This avoids naming collisions and makes the project affiliation explicit. Example: `os-vault` is a Claude Code plugin that is part of cc-os; `memsearch` is a separate plugin outside cc-os. + +**2. Skills within a plugin use verb-first names.** The plugin namespace already answers "what is this about?" (`os-vault` → about the vault), so the skill name should answer "what action does this perform?" (`query`, `write`, `reorganize`). This produces invocations like `/os-vault:query` (query the vault) and `/os-vault:write` (write to the vault) — command-like phrasing that reads as action + object rather than two nouns stacked together. + +**3. Multi-word skill names use kebab-case with verb + noun.** When a skill needs two words, verb comes first (`design-template`, `onboard-project`), producing `/os-vault:design-template` and `/os-vault:onboard-project`. This preserves the verb-first pattern and reads as a complete action. Kebab-case is a Claude Code requirement for plugin `name` fields per code.claude.com/docs/en/plugins-reference.md. + +**4. Naming communicates scope and audience.** The combination of plugin prefix + verb-first skills makes the scope and audience clear at invocation time. A user types `/os-vault:query` and immediately understands they're querying the cc-os vault system, not a generic memory tool. + +## Patterns + +**Plugin naming pattern: `os-[domain]`** — `os-vault` (the knowledge vault interface). Additional plugins, if created, would follow the same pattern: `os-[domain]` where domain describes what the plugin surfaces (vault, projects, agents, hooks, etc.). + +**Skill naming pattern: `[verb]` or `[verb]-[noun]`** — single-word verbs for common actions (`query`, `write`, `read`, `delete`); verb-noun pairs for more specific operations (`design-template`, `onboard-project`, `reorganize`). In multi-word skills, the verb always comes first. + +**Invocation readability: `/os-vault:query [tag]`** → "query the vault using a tag." `/os-vault:onboard-project`→ "onboard this project to the vault graph." The pattern reads naturally without requiring context. + +## Anti-Patterns + +- **Plugin name without prefix** — `vault` instead of `os-vault` — loses the visual cc-os affiliation and risks collision with other tools that might use `vault` as a name. +- **Noun-stacked skill names** — `memory-vault` or `vault-query` instead of `query` — ambiguous about which noun is the subject and which is the action; requires reading both words before understanding the command. +- **Generic skill verbs divorced from the plugin domain** — `/os-vault:find` instead of `/memory-find` — loses the context that this is a vault-specific find, not a global search. The plugin namespace provides the context; the skill name should not duplicate it. +- CamelCase or snake_case in plugin `name` fields — Claude Code requires kebab-case here (not a cc-os choice). +- CamelCase or snake_case in skill names — cc-os extends kebab-case to skills by convention (not a Claude Code requirement). + +## Exceptions + +None currently. This convention applies to all cc-os plugins and skills. + +## Open Questions / Future Extension + +**How should agent names and hook script names be governed, if/when cc-os adds more of either?** + +- **Agent names:** If cc-os agents are created (e.g., `agent-onboard-project`), should they follow the same `os-` prefix? Unresolved; test with one agent before establishing a rule. +- **Hook script names:** Hook scripts are currently thin entry-point wrappers (e.g., `session_start.py`), not externally visible. If hooks become more prominent or user-configurable, establish a naming rule. For now, snakecase works (Python convention). + +These extensions are deferred until their use patterns stabilize.