---
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-16
date: 2026-07-02
related:
  - vault-conventions
  - CLAUDE
  - cc-os-hub
---

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