naming-conventions

name	naming-conventions
description	Naming conventions for Claude Code plugin components -- plugins (tier prefixes: kb-*, dx-*, int-*), skills, commands, agents, argument hints, and descriptions. Use when creating, renaming, or auditing any plugin component to ensure correct naming patterns, description quality, and context budget optimization.
user-invocable	false

Naming Conventions

Knowledge base for naming Claude Code plugin components correctly. Names serve humans (typing, recall), descriptions serve Claude (routing, auto-discovery), and each component type has a natural part of speech.

The Naming Taxonomy

Every component type has a natural part of speech. Consistency within a type creates a predictable mental model.

Entity	Case	Part of Speech	Length	Examples
Plugin (core)	kebab-case	Noun/noun-compound	1-3 words	cortex-engineering, git-workflow
Plugin (knowledge bank)	kb- + kebab-case	Prefix + tool noun	2-3 words	kb-mpe, kb-obsidian, kb-tailwind
Plugin (dev experience)	dx- + kebab-case	Prefix + tool noun	2-3 words	dx-biome, dx-eslint
Plugin (integration)	int- + kebab-case	Prefix + service noun	2-3 words	int-firecrawl, int-rclone
Skill (action)	kebab-case	Verb or verb-phrase	1-3 words	research, deploy-staging
Skill (knowledge)	kebab-case	Noun or noun-compound	1-3 words	api-conventions, frontmatter
Command	kebab-case	Verb (imperative)	1-2 words	deploy, fix-issue
Agent	kebab-case	Role-noun	1-3 words	debugger, code-reviewer
argument-hint	POSIX brackets	Descriptive noun	<30 chars	<topic>, [format]

Plugin Tier Prefixes

Plugins use a tier prefix to signal their lifecycle and purpose. Pick the tier first -- it determines the name prefix.

Tier	Prefix	When to use	Skill pattern
Core	none	Foundational workflow plugins (skills, commands, agents, hooks)	Mixed action + knowledge skills
Knowledge bank	kb-	Reference knowledge for a specific tool or framework	Single user-invocable: false skill with routing table hub
Developer experience	dx-	Dev tooling (linters, formatters, test runners)	May have hooks and commands
Integration	int-	External service wrappers (APIs, CLIs, cloud services)	May have MCP tools

The tier prefix is part of the published plugin name and is an API contract (renaming = semver-major). For kb-* plugins, the skill name is the tool noun without the prefix -- e.g., plugin kb-mpe has skill mpe, making the fully qualified name kb-mpe:mpe.

Naming Patterns by Use Case

Pattern	When to use	Examples
verb-noun	Action skills/commands (dominant)	fix-issue, explain-code, deploy-staging
noun-noun	Reference/knowledge content	api-conventions, legacy-system-context
single verb	High-frequency universal actions	simplify, batch, deploy
adjective-noun	Specialized variants	deep-research, safe-reader
platform-task	Domain-scoped tools	youtube-research, spam-check

Invocation Control Changes Naming Strategy

• User-invoked skills/commands (disable-model-invocation: true): optimize for human recall -- verb-noun, memorable, typable
• Auto-triggered skills: description is primary, name can be shorter/compressed
• Commands: always user-invoked, so typeability is the top priority

The Five Rules of Plugin Hierarchy Coherence

Rule 1: Never repeat the plugin name in component names. The namespace already provides scope. cortex-engineering:frontmatter not cortex-engineering:cortex-engineering-frontmatter.

Rule 2: Match skill names to their command counterparts. If /research delegates to a skill, the skill should also be named research, not producing-research-documents.

Rule 3: Use the description for AI routing, not the name. The name is for humans (typing, remembering). The description is for Claude (routing, auto-discovery). Don't try to make the name do both jobs.

Rule 4: Maintain part-of-speech consistency within a type. Commands should all be verbs. Agents should all be role-nouns. Knowledge skills should all be nouns. Action skills should all be verbs.

Rule 5: Treat published names as API contracts. Plugin names are in marketplace.json. Skill names become /slash-commands. Agent names appear in permission rules. Renaming any of these is a semver-major change.

Name Anti-Patterns

Anti-Pattern	Why It Fails	Fix
Overly generic: check, process	Too broad, fails both recall and discovery	Add domain context: spam-check
Ambiguous siblings: update vs upgrade	Users can't remember which is which	Use distinct verbs with clear boundaries
Plugin name repeated: cortex:cortex-research	Namespace stuttering	Drop prefix: cortex:research
Abbreviation conflicts	Prefix collision in autocomplete	Use full, distinctive words
Too long: code-review-and-security-analysis-agent	Untypable, exceeds mental model	1-3 words max
Missing domain context: check vs spam-check	Ambiguous across workflows	Front-load the domain

Agent Naming

Use role-nouns, not action-verbs. Agents are persistent entities with identity.

• Good: code-reviewer, debugger, beat-reporter, formatter
• Bad: review-code (verb-object -- that's a task), reviewing (gerund -- ambiguous)

The builder-validator pattern is the dominant architectural naming idiom. The names map directly to enforced tool restrictions. Naming is enforcement.

SKILL.md name vs Directory Name

When the name field differs from the directory name, the name field wins for /slash-command invocation. Keep them matching for maximum predictability. The description handles the verbose explanation.

Namespace Strategy

• Global skills (~/.claude/skills/): broader names, cross-project relevance
• Project skills (.claude/skills/): more specialized, project context baked in
• Plugin skills: auto-namespaced via plugin:skill, so the skill name itself can be shorter

Technical Constraints

• Lowercase letters, numbers, hyphens only
• Maximum 64 characters
• The name field directly becomes the /slash-command invocation
• Same-name collisions resolve by priority: enterprise > personal > project

Reference Files

For detailed guidance on specific topics:

• description-writing.md -- The WHAT+WHEN+WHEN NOT pattern, pushy language, activation rates, and length optimization
• argument-hints.md -- POSIX conventions, length limits, and examples
• budget-strategy.md -- 2% context budget, skill count limits, and description length tradeoffs

Source Research

Full research document: docs/research/2026-03-01-naming-conventions-claude-code-plugins.md