Initial commit
This commit is contained in:
Zhongwei Li
404
skills/plugin-authoring/best-practices/naming-conventions.md
Normal file
404
skills/plugin-authoring/best-practices/naming-conventions.md
Normal file
@@ -0,0 +1,404 @@
|
||||
# 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):
|
||||
|
||||
```markdown
|
||||
---
|
||||
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:
|
||||
```markdown
|
||||
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
|
||||
|
||||
```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:
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```bash
|
||||
/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)
|
||||
440
skills/plugin-authoring/best-practices/organization.md
Normal file
440
skills/plugin-authoring/best-practices/organization.md
Normal file
@@ -0,0 +1,440 @@
|
||||
# Plugin Organization Best Practices
|
||||
|
||||
Guidelines for structuring well-organized, maintainable Claude Code plugins.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
### Standard Layout
|
||||
|
||||
```
|
||||
plugin-name/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json # Manifest only
|
||||
├── commands/ # Slash commands (*.md)
|
||||
├── agents/ # Sub-agents (*.md)
|
||||
├── skills/ # Skills (folders with SKILL.md)
|
||||
├── hooks/ # Hook configurations
|
||||
│ └── hooks.json # Main hook config file
|
||||
├── scripts/ # Hook scripts, utilities
|
||||
└── README.md # User-facing documentation
|
||||
```
|
||||
|
||||
### Key Principles
|
||||
|
||||
1. **Manifest isolation**: Only `plugin.json` goes in `.claude-plugin/`
|
||||
2. **Component separation**: Keep commands, agents, skills, and hooks in separate directories
|
||||
3. **Relative paths**: All paths in manifests are relative to plugin root
|
||||
4. **Default directories**: Standard directories (`commands/`, `agents/`, `skills/`, `hooks/`) are automatically discovered
|
||||
5. **Flat commands**: Command files go directly in `commands/`, not subdirectories (unless using custom paths)
|
||||
6. **Nested skills**: Skills are folders with `SKILL.md` + support files
|
||||
7. **Custom paths**: Use component fields in `plugin.json` only for non-standard locations
|
||||
|
||||
## File Naming
|
||||
|
||||
### Commands
|
||||
|
||||
- **Format**: `command-name.md`
|
||||
- **Case**: kebab-case (lowercase with hyphens)
|
||||
- **Examples**: `init.md`, `add-command.md`, `validate.md`
|
||||
|
||||
### Agents
|
||||
|
||||
- **Format**: `agent-name.md`
|
||||
- **Case**: kebab-case
|
||||
- **Examples**: `code-reviewer.md`, `test-analyzer.md`
|
||||
|
||||
### Skills
|
||||
|
||||
- **Format**: `skill-name/SKILL.md` (directory + SKILL.md)
|
||||
- **Case**: kebab-case for directory
|
||||
- **Examples**: `plugin-authoring/SKILL.md`, `code-review/SKILL.md`
|
||||
|
||||
### Hooks
|
||||
|
||||
- **Standard**: `hooks.json` (one per plugin)
|
||||
- **Scripts**: `scripts/script-name.sh` (kebab-case)
|
||||
|
||||
## Skill Organization
|
||||
|
||||
### Progressive Disclosure Pattern
|
||||
|
||||
Keep `SKILL.md` concise (< 500 lines) and link to detailed files:
|
||||
|
||||
```
|
||||
skills/my-skill/
|
||||
├── SKILL.md # Main skill definition (concise)
|
||||
├── schemas/ # Data format documentation
|
||||
│ └── config-schema.md
|
||||
├── templates/ # Reusable templates
|
||||
│ └── config-template.json
|
||||
├── examples/ # Usage examples
|
||||
│ └── basic-usage.md
|
||||
└── best-practices/ # Detailed guidance
|
||||
└── patterns.md
|
||||
```
|
||||
|
||||
### SKILL.md Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: What and when (concise, < 200 chars)
|
||||
allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
[2-3 sentence overview]
|
||||
|
||||
## Quick Links
|
||||
- [Reference 1](./reference1.md)
|
||||
- [Reference 2](./reference2.md)
|
||||
|
||||
## [Concise sections...]
|
||||
```
|
||||
|
||||
## Command Organization
|
||||
|
||||
### Simple Plugins
|
||||
|
||||
For plugins with few commands (< 5):
|
||||
|
||||
```
|
||||
commands/
|
||||
├── command1.md
|
||||
├── command2.md
|
||||
└── command3.md
|
||||
```
|
||||
|
||||
### Complex Plugins
|
||||
|
||||
For plugins with many related commands, consider namespacing:
|
||||
|
||||
```
|
||||
commands/
|
||||
├── git-commit.md
|
||||
├── git-push.md
|
||||
├── git-branch.md
|
||||
├── test-unit.md
|
||||
├── test-integration.md
|
||||
└── test-e2e.md
|
||||
```
|
||||
|
||||
Commands are invoked as `/plugin-name:git-commit`, etc.
|
||||
|
||||
## Hook Organization
|
||||
|
||||
### Simple Hooks
|
||||
|
||||
Hooks configuration goes in `hooks/hooks.json`:
|
||||
|
||||
```
|
||||
hooks/
|
||||
└── hooks.json
|
||||
```
|
||||
|
||||
Alternatively, hooks can be defined inline in `plugin.json` or specified via the `hooks` field:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"hooks": "./hooks/hooks.json"
|
||||
}
|
||||
```
|
||||
|
||||
Or inline configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"hooks": {
|
||||
"PostToolUse": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Complex Hooks
|
||||
|
||||
With multiple scripts, organize them under `hooks/scripts/`:
|
||||
|
||||
```
|
||||
hooks/
|
||||
├── hooks.json
|
||||
└── scripts/
|
||||
├── pre-write-validation.sh
|
||||
├── post-write-format.sh
|
||||
└── session-start-info.sh
|
||||
```
|
||||
|
||||
Reference scripts using the `${CLAUDE_PLUGIN_ROOT}` environment variable:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/pre-write-validation.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
### README.md (Required)
|
||||
|
||||
User-facing documentation:
|
||||
|
||||
```markdown
|
||||
# Plugin Name
|
||||
|
||||
Brief description
|
||||
|
||||
## Installation
|
||||
|
||||
[How to install]
|
||||
|
||||
## Usage
|
||||
|
||||
[Commands, examples]
|
||||
|
||||
## Configuration
|
||||
|
||||
[If applicable]
|
||||
```
|
||||
|
||||
### Additional Docs
|
||||
|
||||
For complex plugins:
|
||||
|
||||
```
|
||||
docs/
|
||||
├── getting-started.md
|
||||
├── api-reference.md
|
||||
├── troubleshooting.md
|
||||
└── examples/
|
||||
├── basic.md
|
||||
└── advanced.md
|
||||
```
|
||||
|
||||
## Size Guidelines
|
||||
|
||||
### Keep Components Focused
|
||||
|
||||
- **Commands**: 50-200 lines (including examples)
|
||||
- **Skills**: SKILL.md < 500 lines, plus support files
|
||||
- **Agents**: 100-400 lines
|
||||
- **Hooks**: Keep scripts fast (< 1 second runtime)
|
||||
|
||||
### When to Split
|
||||
|
||||
Consider splitting when:
|
||||
- Single skill > 500 lines → Create multiple skills
|
||||
- Many related commands → Create separate plugins
|
||||
- Complex logic → Move to support files with progressive disclosure
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Multi-Component Plugin
|
||||
|
||||
Combines multiple component types:
|
||||
|
||||
```
|
||||
my-dev-tools/
|
||||
├── .claude-plugin/plugin.json
|
||||
├── commands/ # Quick actions
|
||||
│ ├── format.md
|
||||
│ └── lint.md
|
||||
├── agents/ # Deep analysis
|
||||
│ └── code-reviewer.md
|
||||
├── skills/ # Ambient guidance
|
||||
│ └── code-review/SKILL.md
|
||||
└── hooks/ # Automation
|
||||
├── hooks.json
|
||||
└── scripts/
|
||||
```
|
||||
|
||||
### Command-Only Plugin
|
||||
|
||||
Simple plugins with just commands:
|
||||
|
||||
```
|
||||
utility-commands/
|
||||
├── .claude-plugin/plugin.json
|
||||
├── commands/
|
||||
│ ├── command1.md
|
||||
│ ├── command2.md
|
||||
│ └── command3.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### Skill-Focused Plugin
|
||||
|
||||
Domain expertise plugins:
|
||||
|
||||
```
|
||||
framework-expert/
|
||||
├── .claude-plugin/plugin.json
|
||||
├── skills/
|
||||
│ └── framework-guidance/
|
||||
│ ├── SKILL.md
|
||||
│ ├── schemas/
|
||||
│ ├── templates/
|
||||
│ └── examples/
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Versioning
|
||||
|
||||
### Plugin Versioning
|
||||
|
||||
Use **SemVer** in `plugin.json`:
|
||||
- **Major** (1.0.0): Breaking changes
|
||||
- **Minor** (0.1.0): New features, backward compatible
|
||||
- **Patch** (0.0.1): Bug fixes
|
||||
|
||||
### Change Documentation
|
||||
|
||||
Maintain `CHANGELOG.md`:
|
||||
|
||||
```markdown
|
||||
# Changelog
|
||||
|
||||
## [1.1.0] - 2024-01-15
|
||||
### Added
|
||||
- New command: validate-all
|
||||
|
||||
### Changed
|
||||
- Improved error messages
|
||||
|
||||
## [1.0.0] - 2024-01-01
|
||||
### Added
|
||||
- Initial release
|
||||
```
|
||||
|
||||
## Testing Organization
|
||||
|
||||
### Test Structure
|
||||
|
||||
```
|
||||
tests/
|
||||
├── commands/
|
||||
│ ├── test-command1.sh
|
||||
│ └── test-command2.sh
|
||||
├── hooks/
|
||||
│ ├── test-validation.sh
|
||||
│ └── test-formatting.sh
|
||||
└── integration/
|
||||
└── test-workflow.sh
|
||||
```
|
||||
|
||||
### Validation Scripts
|
||||
|
||||
Keep in `scripts/` for reuse:
|
||||
|
||||
```
|
||||
scripts/
|
||||
├── validate-plugin.sh # Used by hooks
|
||||
├── validate-commands.sh # Used by tests
|
||||
└── validate-manifest.sh # Used by CI
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Don't: Components in .claude-plugin/
|
||||
|
||||
```
|
||||
.claude-plugin/
|
||||
├── plugin.json
|
||||
├── commands/ # Wrong!
|
||||
└── hooks.json # Wrong!
|
||||
```
|
||||
|
||||
### ✅ Do: Components at Plugin Root
|
||||
|
||||
```
|
||||
.claude-plugin/
|
||||
└── plugin.json # Only manifest
|
||||
commands/ # At root
|
||||
hooks/ # At root
|
||||
```
|
||||
|
||||
### ❌ Don't: Specify Default Paths in Manifest
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"commands": "./commands/",
|
||||
"agents": "./agents/"
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ Do: Omit Component Fields When Using Default Directories
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin"
|
||||
}
|
||||
```
|
||||
|
||||
When using standard directories (`commands/`, `agents/`, `skills/`, `hooks/`), they are automatically discovered and you don't need to specify them in `plugin.json`. Only use component fields (`commands`, `agents`, etc.) when:
|
||||
1. Using non-standard directory names (e.g., `./custom-commands/`)
|
||||
2. Including specific individual files (e.g., `["./commands/special.md"]`)
|
||||
3. Combining custom paths with default paths
|
||||
|
||||
### ❌ Don't: Absolute Paths
|
||||
|
||||
```json
|
||||
{
|
||||
"commands": ["/Users/you/plugins/my-plugin/commands/cmd.md"]
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ Do: Relative Paths (for custom paths only)
|
||||
|
||||
```json
|
||||
{
|
||||
"commands": ["./custom/cmd.md"]
|
||||
}
|
||||
```
|
||||
|
||||
### ❌ Don't: Monolithic Skills
|
||||
|
||||
```markdown
|
||||
# SKILL.md (3000 lines)
|
||||
[Everything in one file...]
|
||||
```
|
||||
|
||||
### ✅ Do: Progressive Disclosure
|
||||
|
||||
```markdown
|
||||
# SKILL.md (400 lines)
|
||||
Quick Links:
|
||||
- [Details](./details.md)
|
||||
- [Examples](./examples/)
|
||||
```
|
||||
|
||||
## Summary Checklist
|
||||
|
||||
```
|
||||
□ Manifest isolated in .claude-plugin/
|
||||
□ Components at plugin root (not inside .claude-plugin/)
|
||||
□ Default directories (commands/, agents/, skills/, hooks/) are automatically discovered
|
||||
□ Component fields in plugin.json only when using custom paths
|
||||
□ Kebab-case naming throughout
|
||||
□ Relative paths in all configs (start with ./)
|
||||
□ Skills use progressive disclosure
|
||||
□ Commands are focused (< 200 lines)
|
||||
□ Scripts are executable
|
||||
□ Hooks reference scripts using ${CLAUDE_PLUGIN_ROOT}
|
||||
□ README.md documents usage
|
||||
□ Version follows SemVer
|
||||
□ CHANGELOG.md tracks changes
|
||||
```
|
||||
Reference in New Issue
Block a user