# cc-os Plugin and Skill Naming Convention

Canonical repo copy of the convention established 2026-07-02 (previously only in the
SecondBrain vault note `cc-os-plugin-skill-naming-convention.md`, which now points here).
Read this before naming ANY new cc-os plugin, skill, or slash command.

## Core principles

1. **Plugins use an `os-` prefix**: `os-[domain]` (e.g. `os-vault`, `os-backlog`). The
   prefix ties the plugin to cc-os and distinguishes it from unrelated tools
   (`memsearch` is NOT cc-os).
2. **Skills are verb-first**: the plugin namespace answers "what is this about?", the
   skill name answers "what action?" — `query`, `write`, `reorganize`, producing
   invocations like `/os-vault:query`.
3. **Multi-word skills are kebab-case, verb + noun**: `design-template`,
   `onboard-project`. Kebab-case in plugin `name` fields is a Claude Code requirement;
   cc-os extends it to skill names by convention.
4. **No `commands/` dispatcher directories** — skills are the only invocation surface.

## Registration mechanics

**Never set a `name:` field in SKILL.md frontmatter.** The directory name is the skill
name; with `name:` absent, Claude Code registers the namespaced `/plugin:skill` form.
An explicit `name: find` collapses the command to bare unnamespaced `/find`
(discovered 2026-07-04 in os-adr and os-doc-hygiene; fixed by deleting the lines).
After any SKILL.md edit, run `bin/refresh-plugins` — installs copy files into
`~/.claude/plugins/cache/`, so source edits don't reach sessions until refreshed.

## Anti-patterns

- Plugin name without the `os-` prefix (`vault` instead of `os-vault`).
- Noun-stacked skill names (`vault-query` instead of `query`).
- Generic verbs duplicating the namespace context (`/memory-find` instead of
  `/os-vault:find` — the namespace provides the context).
- CamelCase or snake_case in plugin or skill names.

## Open questions

Agent-name and hook-script-name governance are deferred until their use patterns
stabilize; hook scripts currently use snake_case (Python convention) and are not
externally visible.

## Cross-references

- ADR-0025 (Ruby structure standard — the structural layer below this naming layer)
- `references/layout/plugin-structure.md`, `references/layout/skill-structure.md`