47 lines
2.2 KiB
Markdown
47 lines
2.2 KiB
Markdown
# 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`
|