gh-hyperskill-claude-code-marketplace-plugins-plugin-development/skills/plugin-authoring/best-practices/naming-conventions.md

Naming Conventions

Consistent naming patterns for Claude Code plugins and components.

General Principles

1. Predictable: Names should indicate purpose
2. Consistent: Follow patterns throughout plugin
3. Case-sensitive: Respect case conventions for each component type
4. Descriptive: Prefer clarity over brevity
5. Avoid conflicts: Namespace to prevent collisions

Plugin Names

Format

kebab-case (lowercase with hyphens)

Examples

✅ Good:

• plugin-development
• code-review-tools
• git-workflow
• python-helpers

❌ Bad:

• PluginDevelopment (camelCase)
• plugin_development (snake_case)
• plugindevelopment (no separators)
• PLUGIN-DEVELOPMENT (uppercase)

Naming Tips

• Descriptive: Name reflects functionality
• Concise: 1-3 words typical
• No prefix: Don't use "plugin-" prefix (redundant)
  • ✅ code-review
  • ❌ plugin-code-review

Command Names

Format

kebab-case (lowercase with hyphens)

Files: command-name.md

Examples

✅ Good:

• init.md → /plugin-name:init
• add-command.md → /plugin-name:add-command
• validate-all.md → /plugin-name:validate-all
• run-tests.md → /plugin-name:run-tests

❌ Bad:

• Init.md (capitalized)
• add_command.md (snake_case)
• addCommand.md (camelCase)

Command Invocation

Commands can be invoked with or without the plugin prefix:

Full format: /plugin-name:command-name

Examples:

• /plugin-development:init
• /git-workflow:commit-push
• /test-runner:run-all

Namespacing

Plugin prefix is optional unless there are name conflicts. When no conflict exists, you can use the command directly:

• Direct: /format-code (when no conflict)
• Prefixed: /my-tools:format-code (when needed for disambiguation)

Commands are automatically namespaced by plugin name:

• Plugin: my-tools
• Command file: format.md
• Invocation options:
  • /format (if no other plugin has this command)
  • /my-tools:format (when needed to disambiguate)

This prevents conflicts between plugins.

Verb-Based Naming

Start commands with action verbs:

✅ Good:

• create-component
• validate-config
• run-tests
• deploy-app

❌ Bad:

• component-creation (noun-based)
• config-validation (noun-based)

Skill Names

Format

kebab-case (lowercase with hyphens)

Directory: skill-name/ File: SKILL.md (always uppercase)

Examples

✅ Good:

• plugin-authoring/SKILL.md
• code-review/SKILL.md
• api-design/SKILL.md

❌ Bad:

• PluginAuthoring/SKILL.md (camelCase)
• plugin_authoring/SKILL.md (snake_case)
• plugin-authoring/skill.md (lowercase skill.md)

Frontmatter Name

Should match directory name (recommended for consistency):

---
name: plugin-authoring    # Matches directory
description: ...
---

❌ Poor practice:

Directory: plugin-authoring/
Frontmatter: name: PluginAuthoring  # Doesn't match! Use kebab-case

Note: While the name field in frontmatter is what Claude uses to discover and reference Skills, having it match the directory name prevents confusion and follows best practices.

Skill Naming Tips

• Domain-focused: Name reflects area of expertise
• Singular: code-review not code-reviews
• Avoid "skill" suffix: Name is the capability
  • ✅ plugin-authoring
  • ❌ plugin-authoring-skill

Agent Names

Format

kebab-case (lowercase with hyphens)

Files: agent-name.md

Examples

✅ Good:

• code-reviewer.md
• test-analyzer.md
• security-auditor.md
• plugin-reviewer.md

❌ Bad:

• CodeReviewer.md (camelCase)
• code_reviewer.md (snake_case)

Agent Naming Tips

• Role-based: Name indicates what agent does
• Often noun: Describes the agent's role
  • reviewer, analyzer, auditor
• Suffix optional: -er, -or common but not required
  • ✅ code-reviewer
  • ✅ security-audit

Hook Script Names

Format

kebab-case (lowercase with hyphens)

Extension: .sh for bash scripts

Examples

✅ Good:

• validate-plugin.sh
• format-code.sh
• pre-write-check.sh
• session-start-info.sh

❌ Bad:

• validatePlugin.sh (camelCase)
• validate_plugin.sh (snake_case)
• VALIDATE-PLUGIN.sh (uppercase)

Hook Naming Tips

• Purpose-based: Name indicates what hook does
• Event optional: Can include event in name
  • pre-write-validate.sh
  • post-write-format.sh

Marketplace Names

Format

kebab-case (lowercase with hyphens)

Examples

✅ Good:

• team-tools
• acme-plugins
• dev-marketplace
• internal-tools

❌ Bad:

• TeamTools (camelCase)
• team_tools (snake_case)

Variable and Argument Names

In Commands

Use uppercase with underscores for built-in variables:

• $ARGUMENTS: All arguments as string
• $1, $2, etc.: Individual arguments

In Documentation

Use lowercase with hyphens in examples:

argument-hint: [plugin-name] [command-type]

File Extensions

Markdown

• Commands: .md
• Agents: .md
• Skills: SKILL.md (specific name)
• Documentation: .md

Configuration

• Plugin manifest: plugin.json
• Marketplace manifest: marketplace.json
• Hooks config: hooks.json

Scripts

• Bash: .sh
• Python: .py
• Node: .js

Directory Names

Standard Directories

Use these exact names:

• commands/ (not command/ or cmd/)
• agents/ (not agent/ or subagents/)
• skills/ (not skill/)
• hooks/ (not hook/)
• scripts/ (not script/ or bin/)

Custom Directories

For additional organization, use kebab-case:

• templates/
• schemas/
• examples/
• best-practices/
• test-fixtures/

Metadata Fields

In plugin.json

{
  "name": "kebab-case",
  "description": "Sentence case with capital first letter",
  "keywords": ["lowercase", "multi-word-hyphenated"],
  "license": "UPPERCASE (e.g., MIT, Apache-2.0)"
}

Author Names

Use natural capitalization:

{
  "author": {
    "name": "John Smith",
    "email": "john@example.com"
  }
}

Category and Tag Conventions

Categories

Use singular, lowercase:

• development
• productivity
• utilities
• devops

Tags

Use lowercase, hyphenated for multi-word:

• code-review
• testing
• deployment
• git-workflow

Consistency Checklist

□ Plugin name: kebab-case
□ Commands: kebab-case, .md extension
□ Skills: kebab-case directory, SKILL.md file
□ Agents: kebab-case, .md extension
□ Scripts: kebab-case, appropriate extension
□ Directories: standard names (commands/, agents/, etc.)
□ Frontmatter names match directory/file names
□ Categories and tags: lowercase

Examples by Component

Complete Plugin

my-dev-tools/                    # kebab-case
├── .claude-plugin/
│   └── plugin.json              # name: "my-dev-tools"
├── commands/
│   ├── format-code.md           # kebab-case
│   ├── run-tests.md             # kebab-case
│   └── validate-all.md          # kebab-case
├── agents/
│   └── code-reviewer.md         # kebab-case
├── skills/
│   └── code-quality/            # kebab-case
│       └── SKILL.md             # UPPERCASE
├── hooks/
│   └── hooks.json
└── scripts/
    ├── pre-write-check.sh       # kebab-case
    └── post-write-format.sh     # kebab-case

Invocations

/my-dev-tools:format-code
/my-dev-tools:run-tests
/my-dev-tools:validate-all

Anti-Patterns

❌ Mixed Case

MyDevTools/
├── commands/
│   ├── FormatCode.md      # Wrong!
│   └── runTests.md        # Wrong!

❌ Inconsistent Separators

my_dev_tools/              # snake_case
├── commands/
│   ├── format-code.md     # kebab-case
│   └── runTests.md        # camelCase

❌ Wrong SKILL.md Case

skills/
└── my-skill/
    └── skill.md           # Should be SKILL.md

When in Doubt

Follow these defaults:

• Files/directories: kebab-case
• SKILL.md: Always uppercase
• JSON fields: Follow schema (usually camelCase for author fields, kebab-case for names)
• Invocation: /plugin-name:command-name (always kebab-case)