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