cc-os Plugin and Skill Naming Convention

Canonical copy moved 2026-07-16 to the cc-os repo: plugins/cc-architect/references/conventions/cc-os-naming.md. Update there first; this vault note is the cross-project pointer.

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.

Registration Mechanics (Claude Code)

Do NOT set a name: field in SKILL.md frontmatter. The skill's directory name is the skill name, and Claude Code registers the slash command as the namespaced /plugin:skill form when name: is absent. Setting name: find explicitly overrides the registered command to the bare, unnamespaced /find — ambiguous in the command palette and inconsistent with sibling plugins. Discovered 2026-07-04: os-adr and os-doc-hygiene had explicit name: fields and registered as /find, /check, etc., while os-vault (no name: fields) correctly registered as /os-vault:query. Fixed by deleting the name: lines. After any SKILL.md edit, refresh the plugin cache (cc-os/bin/refresh-plugins) — installs copy files into ~/.claude/plugins/cache/, so source edits don't reach sessions until refreshed.

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.

5.8 KiB Raw Blame History