cc-os/plugins/cc-architect/references/conventions/cc-os-naming.md

# 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.

## Agents

Decided 2026-07-18, first applied in os-sdlc (`test-writer`, `programmer`, `reviewer`).

- **Agents are kebab-case role-nouns naming the actor** — who does the job, not what action
  it takes: `test-writer`, `programmer`, `reviewer`. Verb-first is a **skills-only** rule
  (skills = actions; agents = actors) and does not apply to agent names.
- **Agents are not user-invocable** — they get no slash commands and no `/plugin:agent`
  namespaced form. They are dispatched by skills/orchestrators, never typed by a human.

## 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

Hook-script-name governance is deferred until its use patterns stabilize; hook scripts
currently use snake_case (Python convention) and are not externally visible. (Agent-name
governance is resolved above, 2026-07-18.)

## Cross-references

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