Initial commit
This commit is contained in:
Zhongwei Li
102
skills/plugin-authoring/SKILL.md
Normal file
102
skills/plugin-authoring/SKILL.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
name: plugin-authoring
|
||||
description: Expert guidance for Claude Code plugin development. Use when creating or modifying plugins, working with plugin.json or marketplace.json, or adding commands, agents, Skills, or hooks.
|
||||
allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
|
||||
# Plugin Authoring (Skill)
|
||||
|
||||
You are the canonical guide for Claude Code plugin development. Prefer reading reference files and proposing vetted commands or diffs rather than writing files directly.
|
||||
|
||||
## Triggers & Scope
|
||||
|
||||
Activate whenever context includes `.claude-plugin/`, `plugin.json`, `marketplace.json`, `commands/`, `agents/`, `skills/`, or `hooks/`.
|
||||
|
||||
## Flow of Operation
|
||||
|
||||
1. **Diagnose** current repo layout (read-only)
|
||||
2. **Propose** the minimal safe action (scaffold, validate, or review)
|
||||
3. **Execute** via `/plugin-development:...` commands when the user agrees
|
||||
4. **Escalate** to the **plugin-reviewer** agent for deep audits
|
||||
5. **Guardrails**: default to read-only; ask before edits
|
||||
|
||||
## Quick Links (Progressive Disclosure)
|
||||
|
||||
- **Schemas**: [schemas/plugin-manifest.md](schemas/plugin-manifest.md), [schemas/hooks-schema.md](schemas/hooks-schema.md), [schemas/marketplace-schema.md](schemas/marketplace-schema.md)
|
||||
- **Templates**: [templates/](templates/)
|
||||
- **Examples**: [examples/](examples/)
|
||||
- **Best practices**: [best-practices/](best-practices/)
|
||||
|
||||
## Checklists
|
||||
|
||||
### Component Checklist
|
||||
|
||||
```
|
||||
□ .claude-plugin/plugin.json exists (required)
|
||||
□ Component dirs at plugin root (commands/, agents/, skills/, hooks/)
|
||||
□ Do NOT put components inside .claude-plugin/ directory
|
||||
□ Commands use kebab-case naming
|
||||
□ Skills have valid frontmatter (name + description required)
|
||||
□ Skills name matches directory (lowercase-hyphenated, max 64 chars)
|
||||
□ Hooks use ${CLAUDE_PLUGIN_ROOT} for paths (not relative paths)
|
||||
□ All scripts are executable (chmod +x)
|
||||
```
|
||||
|
||||
### Release Checklist
|
||||
|
||||
```
|
||||
□ plugin.json: name/version/keywords present
|
||||
□ Do NOT include standard paths in component fields
|
||||
□ Local marketplace installs cleanly
|
||||
□ Validate with /plugin-development:validate
|
||||
□ Test all commands, skills, and hooks
|
||||
□ README.md exists with usage examples
|
||||
```
|
||||
|
||||
## Playbooks
|
||||
|
||||
- **Scaffold** → `/plugin-development:init <name>` then fill templates
|
||||
- **Add a component** → `/plugin-development:add-command|add-skill|add-agent|add-hook`
|
||||
- **Validate** → `/plugin-development:validate` (schema & structure checks)
|
||||
- **Test locally** → `/plugin-development:test-local` (dev marketplace)
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Creating a New Plugin
|
||||
|
||||
1. Run `/plugin-development:init <plugin-name>` to scaffold structure
|
||||
2. Edit `.claude-plugin/plugin.json` with your metadata
|
||||
3. Add components using `/plugin-development:add-command`, etc.
|
||||
4. Validate with `/plugin-development:validate`
|
||||
5. Test locally with `/plugin-development:test-local`
|
||||
|
||||
### Adding a Slash Command
|
||||
|
||||
1. Run `/plugin-development:add-command <name> <description>`
|
||||
2. Edit `commands/<name>.md` with instructions
|
||||
3. Add frontmatter: `description` and `argument-hint`
|
||||
4. Test: `/plugin install` your plugin, then `/<name>`
|
||||
|
||||
### Adding a Skill
|
||||
|
||||
1. Run `/plugin-development:add-skill <name> <when-to-use>`
|
||||
2. Edit `skills/<name>/SKILL.md` with your instructions
|
||||
3. **Frontmatter requirements**:
|
||||
- `name`: lowercase, hyphenated, max 64 chars (required)
|
||||
- `description`: include both WHAT the Skill does AND WHEN to use it, max 1024 chars (required)
|
||||
- `allowed-tools`: comma-separated list of tools (optional, restricts tool access)
|
||||
4. Keep SKILL.md concise; place details in sibling files (reference.md, examples.md, scripts/)
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
- **Plugin not loading?** Check `plugin.json` paths are relative to plugin root. Do NOT include `commands`, `agents`, `skills`, or `hooks` fields for standard directories.
|
||||
- **Commands not showing?** Verify `commands/` directory exists at plugin root with `.md` files. Do NOT add `commands` field to `plugin.json` for standard paths.
|
||||
- **Hooks not running?** Ensure scripts are executable (`chmod +x`) and use `${CLAUDE_PLUGIN_ROOT}` for paths
|
||||
- **Skill not triggering?** Check `name` matches directory and is lowercase-hyphenated (max 64 chars). Ensure `description` includes both what and when to use (max 1024 chars)
|
||||
|
||||
## Notes
|
||||
|
||||
- Prefer templates & scripts over freeform generation for deterministic tasks
|
||||
- If writes are needed, propose a command or a PR-style diff first
|
||||
- For complex audits, delegate to `/agents plugin-reviewer`
|
||||
- Always validate with `/plugin-development:validate` before testing
|
||||
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
|
||||
```
|
||||
135
skills/plugin-authoring/examples/simple-plugin.md
Normal file
135
skills/plugin-authoring/examples/simple-plugin.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# Example: Simple Plugin
|
||||
|
||||
This example shows a minimal but complete Claude Code plugin.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
my-greeting-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json
|
||||
├── commands/
|
||||
│ └── greet.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## plugin.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-greeting-plugin",
|
||||
"version": "1.0.0",
|
||||
"description": "A simple greeting plugin",
|
||||
"author": {
|
||||
"name": "Your Name"
|
||||
},
|
||||
"license": "MIT",
|
||||
"keywords": ["greeting", "example"]
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: No `commands` field needed since we're using the standard `commands/` directory.
|
||||
|
||||
## commands/greet.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Greet the user with a personalized message
|
||||
argument-hint: [name]
|
||||
---
|
||||
|
||||
# Greet Command
|
||||
|
||||
Provide a warm, friendly greeting to the user.
|
||||
|
||||
## Instructions
|
||||
|
||||
1. If the user provided a name via `$ARGUMENTS`, greet them personally
|
||||
2. If no name provided, use a generic friendly greeting
|
||||
3. Add a fun emoji to make it welcoming
|
||||
|
||||
## Examples
|
||||
|
||||
**Input**: `/my-greeting-plugin:greet Alice`
|
||||
**Output**: "Hello, Alice! 👋 Great to see you!"
|
||||
|
||||
**Input**: `/my-greeting-plugin:greet`
|
||||
**Output**: "Hello there! 👋 How can I help you today?"
|
||||
```
|
||||
|
||||
## README.md
|
||||
|
||||
```markdown
|
||||
# My Greeting Plugin
|
||||
|
||||
A simple example plugin that demonstrates Claude Code plugin basics.
|
||||
|
||||
## Installation
|
||||
|
||||
From a marketplace:
|
||||
```bash
|
||||
/plugin install my-greeting-plugin@marketplace-name
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/my-greeting-plugin:greet [name]
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
- `/my-greeting-plugin:greet World` - Greet with a name
|
||||
- `/my-greeting-plugin:greet` - Generic greeting
|
||||
```
|
||||
|
||||
## Adding to a Marketplace
|
||||
|
||||
In your marketplace's `.claude-plugin/marketplace.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": [
|
||||
{
|
||||
"name": "my-greeting-plugin",
|
||||
"description": "A simple greeting plugin",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Your Name"
|
||||
},
|
||||
"source": "./plugins/my-greeting-plugin",
|
||||
"category": "examples",
|
||||
"tags": ["greeting", "example"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Locally
|
||||
|
||||
1. Create the plugin structure
|
||||
2. Create a dev marketplace:
|
||||
```bash
|
||||
mkdir -p dev-marketplace/.claude-plugin
|
||||
```
|
||||
3. Create `dev-marketplace/.claude-plugin/marketplace.json` (see above)
|
||||
4. Add marketplace:
|
||||
```bash
|
||||
/plugin marketplace add ./dev-marketplace
|
||||
```
|
||||
5. Install plugin:
|
||||
```bash
|
||||
/plugin install my-greeting-plugin@dev-marketplace
|
||||
```
|
||||
6. Test command:
|
||||
```bash
|
||||
/my-greeting-plugin:greet World
|
||||
```
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
- **Minimal structure**: Only `.claude-plugin/plugin.json` and `commands/` are required
|
||||
- **Frontmatter**: Commands need `description` (and optionally `argument-hint`)
|
||||
- **Namespacing**: Commands are called with `/plugin-name:command-name`
|
||||
- **Arguments**: Access via `$ARGUMENTS` or `$1`, `$2`, etc.
|
||||
- **Standard paths**: No need to specify component fields in `plugin.json` when using standard directories
|
||||
233
skills/plugin-authoring/examples/testing-workflow.md
Normal file
233
skills/plugin-authoring/examples/testing-workflow.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# Testing Workflow
|
||||
|
||||
A step-by-step guide to testing plugins locally during development.
|
||||
|
||||
## Overview
|
||||
|
||||
Testing plugins locally uses a **dev marketplace** that points to your working plugin directory. This allows you to:
|
||||
- Test changes without publishing
|
||||
- Iterate quickly
|
||||
- Validate before distribution
|
||||
|
||||
## Setup: One-Time
|
||||
|
||||
### 1. Create Dev Marketplace Structure
|
||||
|
||||
```bash
|
||||
# From your project root
|
||||
mkdir -p dev-marketplace/.claude-plugin
|
||||
```
|
||||
|
||||
### 2. Create marketplace.json
|
||||
|
||||
Create `dev-marketplace/.claude-plugin/marketplace.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "dev-marketplace",
|
||||
"owner": {
|
||||
"name": "Developer"
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Local development marketplace",
|
||||
"version": "0.1.0"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"description": "Plugin under development",
|
||||
"source": "../plugins/my-plugin"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Key**: `source` points to your plugin directory (relative path from marketplace).
|
||||
|
||||
### 3. Add Marketplace to Claude Code
|
||||
|
||||
```bash
|
||||
claude
|
||||
/plugin marketplace add ./dev-marketplace
|
||||
```
|
||||
|
||||
Verify:
|
||||
```bash
|
||||
/plugin marketplace list
|
||||
```
|
||||
|
||||
You should see `dev-marketplace` listed.
|
||||
|
||||
## Iteration Loop
|
||||
|
||||
### Install Plugin
|
||||
|
||||
```bash
|
||||
/plugin install my-plugin@dev-marketplace
|
||||
```
|
||||
|
||||
### Test Commands
|
||||
|
||||
```bash
|
||||
/my-plugin:command-name args
|
||||
```
|
||||
|
||||
Or test via `/help` to see if commands appear.
|
||||
|
||||
### Make Changes
|
||||
|
||||
Edit your plugin files (commands, skills, etc.).
|
||||
|
||||
### Reinstall
|
||||
|
||||
```bash
|
||||
/plugin uninstall my-plugin@dev-marketplace
|
||||
/plugin install my-plugin@dev-marketplace
|
||||
```
|
||||
|
||||
**Note**: You must uninstall/reinstall to pick up changes.
|
||||
|
||||
### Repeat
|
||||
|
||||
Continue the edit → reinstall → test cycle.
|
||||
|
||||
## Validation
|
||||
|
||||
Before each test cycle, validate your plugin:
|
||||
|
||||
```bash
|
||||
/plugin-development:validate
|
||||
```
|
||||
|
||||
This checks:
|
||||
- `plugin.json` exists and is valid JSON
|
||||
- Component directories exist
|
||||
- Paths are correct
|
||||
- No common mistakes
|
||||
|
||||
## Debugging
|
||||
|
||||
### Plugin Not Loading
|
||||
|
||||
1. Check `plugin.json` exists at `.claude-plugin/plugin.json`
|
||||
2. Verify JSON syntax: `cat .claude-plugin/plugin.json | jq .`
|
||||
3. Check paths are relative: `./commands/` not `/absolute/path/`
|
||||
|
||||
### Commands Not Showing
|
||||
|
||||
1. Verify `commands` field in `plugin.json` points to `./commands/`
|
||||
2. Check command files have `.md` extension
|
||||
3. Verify frontmatter has `description` field
|
||||
4. Reinstall the plugin
|
||||
|
||||
### Hooks Not Running
|
||||
|
||||
1. Check `hooks` field in `plugin.json` points to correct path
|
||||
2. Verify `hooks.json` is valid JSON
|
||||
3. Make scripts executable: `chmod +x scripts/*.sh`
|
||||
4. Test script directly: `./scripts/validate-plugin.sh`
|
||||
5. Use `claude --debug` to see hook execution
|
||||
|
||||
### Skills Not Triggering
|
||||
|
||||
1. Check `skills` field in `plugin.json` (if specified)
|
||||
2. Verify `SKILL.md` has frontmatter with `name` and `description`
|
||||
3. Ensure `name` matches directory name (lowercase, hyphenated)
|
||||
4. Check `description` includes clear trigger conditions
|
||||
|
||||
## Advanced: Debug Mode
|
||||
|
||||
Run Claude Code in debug mode to see detailed plugin loading:
|
||||
|
||||
```bash
|
||||
claude --debug
|
||||
```
|
||||
|
||||
This shows:
|
||||
- Plugin registration
|
||||
- Component discovery
|
||||
- Hook execution
|
||||
- Tool usage
|
||||
|
||||
Look for errors related to your plugin in the output.
|
||||
|
||||
## Multiple Plugins
|
||||
|
||||
You can test multiple plugins from one dev marketplace:
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": [
|
||||
{
|
||||
"name": "plugin-one",
|
||||
"source": "../plugins/plugin-one"
|
||||
},
|
||||
{
|
||||
"name": "plugin-two",
|
||||
"source": "../plugins/plugin-two"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Install each separately:
|
||||
```bash
|
||||
/plugin install plugin-one@dev-marketplace
|
||||
/plugin install plugin-two@dev-marketplace
|
||||
```
|
||||
|
||||
## Clean Up
|
||||
|
||||
### Uninstall Plugin
|
||||
|
||||
```bash
|
||||
/plugin uninstall my-plugin@dev-marketplace
|
||||
```
|
||||
|
||||
### Remove Marketplace
|
||||
|
||||
```bash
|
||||
/plugin marketplace remove dev-marketplace
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Validate first**: Always run `/plugin-development:validate` before testing
|
||||
2. **Small changes**: Test incrementally, don't make many changes at once
|
||||
3. **Check logs**: Use `--debug` when troubleshooting
|
||||
4. **Script testing**: Test hook scripts directly before adding to hooks.json
|
||||
5. **Clean installs**: Uninstall fully before reinstalling to avoid cache issues
|
||||
|
||||
## Troubleshooting Checklist
|
||||
|
||||
```
|
||||
□ plugin.json exists and is valid JSON
|
||||
□ All paths are relative (start with ./)
|
||||
□ Component directories exist (commands/, etc.)
|
||||
□ Command files have .md extension
|
||||
□ Scripts are executable (chmod +x)
|
||||
□ marketplace.json plugin name matches plugin.json name
|
||||
□ Reinstalled after making changes
|
||||
```
|
||||
|
||||
## Example Session
|
||||
|
||||
```bash
|
||||
# One-time setup
|
||||
mkdir -p dev-marketplace/.claude-plugin
|
||||
# ... create marketplace.json ...
|
||||
/plugin marketplace add ./dev-marketplace
|
||||
|
||||
# Development loop
|
||||
/plugin install my-plugin@dev-marketplace
|
||||
/my-plugin:test-command
|
||||
|
||||
# Make changes to plugin files...
|
||||
|
||||
/plugin-development:validate
|
||||
/plugin uninstall my-plugin@dev-marketplace
|
||||
/plugin install my-plugin@dev-marketplace
|
||||
/my-plugin:test-command
|
||||
|
||||
# Repeat...
|
||||
```
|
||||
333
skills/plugin-authoring/schemas/hooks-schema.md
Normal file
333
skills/plugin-authoring/schemas/hooks-schema.md
Normal file
@@ -0,0 +1,333 @@
|
||||
# Hooks Schema
|
||||
|
||||
Hooks allow you to run commands at specific lifecycle events. Define them in `hooks/hooks.json`.
|
||||
|
||||
## Location
|
||||
|
||||
`hooks/hooks.json` (at plugin root, referenced in `plugin.json`)
|
||||
|
||||
## Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Optional description of what these hooks do",
|
||||
"hooks": {
|
||||
"EventName": [
|
||||
{
|
||||
"matcher": "pattern",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "path/to/script.sh",
|
||||
"timeout": 30
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Event Types
|
||||
|
||||
### PreToolUse
|
||||
|
||||
Runs **before** Claude uses a tool. Can block tool execution.
|
||||
|
||||
```json
|
||||
{
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
|
||||
"timeout": 30
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Matcher**: Regex pattern matching tool names (e.g., `Write`, `Read`, `Bash.*`)
|
||||
|
||||
**Exit codes**:
|
||||
- `0`: Allow (stdout visible to Claude)
|
||||
- `2`: **Block** (stderr shown to Claude as feedback)
|
||||
- Other: Warning (non-blocking)
|
||||
|
||||
### PostToolUse
|
||||
|
||||
Runs **after** a tool completes. Cannot block.
|
||||
|
||||
```json
|
||||
{
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
|
||||
"timeout": 30
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### SessionStart
|
||||
|
||||
Runs when Claude Code session starts.
|
||||
|
||||
```json
|
||||
{
|
||||
"SessionStart": [
|
||||
{
|
||||
"matcher": "startup",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'Plugin loaded!'"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Matchers**:
|
||||
- `startup` - Invoked from startup
|
||||
- `resume` - Invoked from `--resume`, `--continue`, or `/resume`
|
||||
- `clear` - Invoked from `/clear`
|
||||
- `compact` - Invoked from auto or manual compact
|
||||
|
||||
**Note**: SessionStart stdout is added to context automatically for Claude.
|
||||
|
||||
### SessionEnd
|
||||
|
||||
Runs when a Claude Code session ends.
|
||||
|
||||
```json
|
||||
{
|
||||
"SessionEnd": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/cleanup.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### UserPromptSubmit
|
||||
|
||||
Runs when user submits a prompt. Can block prompt processing.
|
||||
|
||||
```json
|
||||
{
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/context-injector.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Exit codes**:
|
||||
- `0`: Allow (stdout added to context)
|
||||
- `2`: **Block** (stderr shown to user)
|
||||
|
||||
### Stop / SubagentStop
|
||||
|
||||
Runs when Claude attempts to stop (main agent or subagent).
|
||||
|
||||
```json
|
||||
{
|
||||
"Stop": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/check-continuation.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Available in hook commands:
|
||||
|
||||
- `${CLAUDE_PLUGIN_ROOT}`: Absolute path to plugin root
|
||||
- `${CLAUDE_PROJECT_DIR}`: Project root directory (where Claude Code started)
|
||||
- Standard shell environment variables
|
||||
|
||||
## Timeouts
|
||||
|
||||
- Default: No timeout
|
||||
- Recommended: 10-30 seconds for validation
|
||||
- Max: Keep under 60 seconds for good UX
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Validation Hook (Blocking)
|
||||
|
||||
```json
|
||||
{
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
|
||||
"timeout": 30
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**validate.sh**:
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
if [ validation_fails ]; then
|
||||
echo "Error: validation failed" >&2
|
||||
exit 2 # Block the tool
|
||||
fi
|
||||
exit 0 # Allow
|
||||
```
|
||||
|
||||
**Advanced JSON output** (alternative to exit codes):
|
||||
```json
|
||||
{
|
||||
"permissionDecision": "deny",
|
||||
"permissionDecisionReason": "File violates security policy",
|
||||
"suppressOutput": true
|
||||
}
|
||||
```
|
||||
|
||||
### Formatting Hook (Non-blocking)
|
||||
|
||||
```json
|
||||
{
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
|
||||
"timeout": 30
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Startup Message
|
||||
|
||||
```json
|
||||
{
|
||||
"SessionStart": [
|
||||
{
|
||||
"matcher": "startup",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo '✓ My Plugin loaded'"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Use `${CLAUDE_PLUGIN_ROOT}`** for portable paths
|
||||
- **Set timeouts** to prevent hanging (10-30 seconds recommended)
|
||||
- **Exit code 2** to block (PreToolUse/UserPromptSubmit)
|
||||
- **Keep scripts fast** (< 1 second ideally)
|
||||
- **Make scripts executable** (`chmod +x`)
|
||||
- **Test hooks** before distributing
|
||||
- **Handle JSON output** for advanced control (see advanced examples)
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
❌ **Absolute paths** (not portable)
|
||||
```json
|
||||
{
|
||||
"command": "/Users/you/plugin/scripts/validate.sh"
|
||||
}
|
||||
```
|
||||
|
||||
✅ **Plugin-relative paths**
|
||||
```json
|
||||
{
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
|
||||
}
|
||||
```
|
||||
|
||||
❌ **No timeout** on slow operations
|
||||
```json
|
||||
{
|
||||
"command": "npm install"
|
||||
// Missing timeout!
|
||||
}
|
||||
```
|
||||
|
||||
✅ **Set appropriate timeout**
|
||||
```json
|
||||
{
|
||||
"command": "npm install",
|
||||
"timeout": 300000
|
||||
}
|
||||
```
|
||||
|
||||
❌ **Missing required matcher**
|
||||
```json
|
||||
{
|
||||
"SessionStart": [
|
||||
{
|
||||
"hooks": [...] // No matcher!
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
✅ **Include appropriate matcher**
|
||||
```json
|
||||
{
|
||||
"SessionStart": [
|
||||
{
|
||||
"matcher": "startup",
|
||||
"hooks": [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Debugging
|
||||
|
||||
Use `claude --debug` to see:
|
||||
- Hook registration
|
||||
- Hook execution timing
|
||||
- Exit codes and output
|
||||
- Blocking decisions
|
||||
359
skills/plugin-authoring/schemas/marketplace-schema.md
Normal file
359
skills/plugin-authoring/schemas/marketplace-schema.md
Normal file
@@ -0,0 +1,359 @@
|
||||
# Marketplace Schema
|
||||
|
||||
The `marketplace.json` file defines a collection of plugins that users can install.
|
||||
|
||||
## Location
|
||||
|
||||
`.claude-plugin/marketplace.json` (at marketplace root)
|
||||
|
||||
## Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "marketplace-name",
|
||||
"owner": {
|
||||
"name": "Your Organization",
|
||||
"email": "team@your-org.com"
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Marketplace description",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "plugin-name",
|
||||
"description": "What the plugin does",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Author Name"
|
||||
},
|
||||
"source": "./plugins/plugin-name",
|
||||
"category": "utilities",
|
||||
"tags": ["tag1", "tag2"],
|
||||
"keywords": ["keyword1", "keyword2"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Required Fields
|
||||
|
||||
### Marketplace Level
|
||||
|
||||
- **name**: kebab-case string, unique marketplace identifier
|
||||
- **owner**: Object with `name` (required) and optional `email`
|
||||
- **plugins**: Array of plugin entries
|
||||
|
||||
### Plugin Entry
|
||||
|
||||
- **name**: Plugin name (must match `plugin.json`)
|
||||
- **source**: Relative path to plugin directory OR git URL
|
||||
|
||||
## Optional Fields
|
||||
|
||||
### Marketplace Level
|
||||
|
||||
- **metadata**: Object with:
|
||||
- **description**: Brief marketplace description
|
||||
- **version**: Marketplace version
|
||||
- **pluginRoot**: Base path for relative plugin sources (allows resolving relative plugin paths)
|
||||
|
||||
### Plugin Entry
|
||||
|
||||
**Standard metadata fields:**
|
||||
|
||||
- **description**: Brief description
|
||||
- **version**: SemVer version
|
||||
- **author**: String or object with `name`, `email`, `url`
|
||||
- **category**: Category string (e.g., "utilities", "productivity")
|
||||
- **tags**: Array of tags for filtering
|
||||
- **keywords**: Array of keywords for search
|
||||
- **homepage**: Plugin homepage URL
|
||||
- **repository**: Plugin repository URL
|
||||
- **license**: License identifier (e.g., "MIT")
|
||||
- **strict**: Boolean (default: true) - Require plugin.json in plugin folder
|
||||
|
||||
**Component configuration fields:**
|
||||
|
||||
- **commands**: String or array - Custom paths to command files or directories
|
||||
- **agents**: String or array - Custom paths to agent files
|
||||
- **hooks**: String or object - Custom hooks configuration or path to hooks file
|
||||
- **mcpServers**: String or object - MCP server configurations or path to MCP config
|
||||
|
||||
## Source Types
|
||||
|
||||
### Local Path (Development)
|
||||
|
||||
```json
|
||||
{
|
||||
"source": "./plugins/my-plugin"
|
||||
}
|
||||
```
|
||||
|
||||
### Git Repository
|
||||
|
||||
Simple string format:
|
||||
|
||||
```json
|
||||
{
|
||||
"source": "https://github.com/user/repo"
|
||||
}
|
||||
```
|
||||
|
||||
Object format for advanced configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "owner/plugin-repo"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Git URL Source
|
||||
|
||||
```json
|
||||
{
|
||||
"source": {
|
||||
"source": "url",
|
||||
"url": "https://gitlab.com/team/plugin.git"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Git with Subdirectory
|
||||
|
||||
```json
|
||||
{
|
||||
"source": "https://github.com/user/repo/tree/main/plugins/my-plugin"
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Local Dev Marketplace
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "dev-marketplace",
|
||||
"owner": {
|
||||
"name": "Developer",
|
||||
"email": "dev@localhost"
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Local development marketplace",
|
||||
"version": "0.1.0"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"description": "Plugin in development",
|
||||
"source": "../my-plugin"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Team Marketplace
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "acme-tools",
|
||||
"owner": {
|
||||
"name": "ACME Corp",
|
||||
"email": "tools@acme.com"
|
||||
},
|
||||
"metadata": {
|
||||
"description": "ACME internal tools for Claude Code",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "code-review",
|
||||
"description": "ACME code review standards",
|
||||
"version": "2.1.0",
|
||||
"author": {
|
||||
"name": "DevTools Team"
|
||||
},
|
||||
"source": "./plugins/code-review",
|
||||
"category": "development",
|
||||
"tags": ["code-review", "standards"],
|
||||
"keywords": ["review", "quality", "standards"]
|
||||
},
|
||||
{
|
||||
"name": "deploy-tools",
|
||||
"description": "Deployment automation",
|
||||
"version": "1.5.0",
|
||||
"author": {
|
||||
"name": "DevOps Team"
|
||||
},
|
||||
"source": "./plugins/deploy-tools",
|
||||
"category": "devops",
|
||||
"tags": ["deployment", "automation"],
|
||||
"keywords": ["deploy", "ci", "cd"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Advanced Plugin Entry
|
||||
|
||||
Plugin entries can override default component locations and provide inline configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "enterprise-tools",
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "company/enterprise-plugin"
|
||||
},
|
||||
"description": "Enterprise workflow automation tools",
|
||||
"version": "2.1.0",
|
||||
"author": {
|
||||
"name": "Enterprise Team",
|
||||
"email": "enterprise@company.com"
|
||||
},
|
||||
"homepage": "https://docs.company.com/plugins/enterprise-tools",
|
||||
"repository": "https://github.com/company/enterprise-plugin",
|
||||
"license": "MIT",
|
||||
"keywords": ["enterprise", "workflow", "automation"],
|
||||
"category": "productivity",
|
||||
"commands": [
|
||||
"./commands/core/",
|
||||
"./commands/enterprise/",
|
||||
"./commands/experimental/preview.md"
|
||||
],
|
||||
"agents": [
|
||||
"./agents/security-reviewer.md",
|
||||
"./agents/compliance-checker.md"
|
||||
],
|
||||
"hooks": "./config/hooks.json",
|
||||
"mcpServers": {
|
||||
"enterprise-db": {
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
|
||||
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
|
||||
}
|
||||
},
|
||||
"strict": false
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
**Schema relationship**: Plugin entries are based on the *plugin manifest schema* (with all fields made optional) plus marketplace-specific fields (`source`, `strict`, `category`, `tags`). This means any field valid in a `plugin.json` file can also be used in a marketplace entry. When `strict: false`, the marketplace entry serves as the complete plugin manifest if no `plugin.json` exists. When `strict: true` (default), marketplace fields supplement the plugin's own manifest file.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
**Environment variables**: Use `${CLAUDE_PLUGIN_ROOT}` in hooks and mcpServers configurations. This variable resolves to the plugin's installation directory and ensures paths work correctly regardless of where the plugin is installed.
|
||||
</Note>
|
||||
|
||||
## Usage
|
||||
|
||||
### Add Marketplace (Local)
|
||||
|
||||
```bash
|
||||
/plugin marketplace add /path/to/marketplace
|
||||
```
|
||||
|
||||
### Add Marketplace (GitHub)
|
||||
|
||||
```bash
|
||||
/plugin marketplace add your-org/your-repo
|
||||
```
|
||||
|
||||
### Install Plugin from Marketplace
|
||||
|
||||
```bash
|
||||
/plugin install plugin-name@marketplace-name
|
||||
```
|
||||
|
||||
### Team Auto-Install
|
||||
|
||||
In project `.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"extraKnownMarketplaces": {
|
||||
"team-tools": {
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "your-org/marketplace-repo"
|
||||
}
|
||||
}
|
||||
},
|
||||
"enabledPlugins": {
|
||||
"plugin-name@team-tools": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Workflow
|
||||
|
||||
1. Create dev marketplace:
|
||||
```bash
|
||||
mkdir -p dev-marketplace/.claude-plugin
|
||||
# Create marketplace.json pointing to ../your-plugin
|
||||
```
|
||||
|
||||
2. Add to Claude Code:
|
||||
```bash
|
||||
/plugin marketplace add ./dev-marketplace
|
||||
```
|
||||
|
||||
3. Install plugin:
|
||||
```bash
|
||||
/plugin install your-plugin@dev-marketplace
|
||||
```
|
||||
|
||||
4. After changes, reinstall:
|
||||
```bash
|
||||
/plugin uninstall your-plugin@dev-marketplace
|
||||
/plugin install your-plugin@dev-marketplace
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Use kebab-case** for marketplace and plugin names
|
||||
- **Keep descriptions concise** (< 100 chars)
|
||||
- **Add meaningful tags** for discoverability
|
||||
- **Version consistently** using SemVer
|
||||
- **Test locally** before publishing to GitHub
|
||||
- **Document plugins** in their README files
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
❌ **Plugin name mismatch**
|
||||
```json
|
||||
// marketplace.json
|
||||
{ "name": "my-plugin", "source": "./plugins/other-plugin" }
|
||||
|
||||
// plugin.json (in other-plugin/)
|
||||
{ "name": "other-plugin" } // Names don't match!
|
||||
```
|
||||
|
||||
✅ **Names must match**
|
||||
```json
|
||||
// marketplace.json
|
||||
{ "name": "my-plugin", "source": "./plugins/my-plugin" }
|
||||
|
||||
// plugin.json
|
||||
{ "name": "my-plugin" } // Matches!
|
||||
```
|
||||
|
||||
❌ **Absolute source paths**
|
||||
```json
|
||||
{
|
||||
"source": "/Users/you/plugins/my-plugin"
|
||||
}
|
||||
```
|
||||
|
||||
✅ **Relative source paths**
|
||||
```json
|
||||
{
|
||||
"source": "./plugins/my-plugin"
|
||||
}
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
Use `/plugin-development:validate` to check marketplace structure.
|
||||
258
skills/plugin-authoring/schemas/plugin-manifest.md
Normal file
258
skills/plugin-authoring/schemas/plugin-manifest.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# Plugin Manifest Schema
|
||||
|
||||
The `plugin.json` file in `.claude-plugin/` defines your plugin's metadata and optionally custom component paths.
|
||||
|
||||
## Location
|
||||
|
||||
`.claude-plugin/plugin.json` (at plugin root)
|
||||
|
||||
## Required Fields
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "plugin-name"
|
||||
}
|
||||
```
|
||||
|
||||
- **name**: kebab-case string, unique identifier (REQUIRED)
|
||||
|
||||
## Optional Fields
|
||||
|
||||
### Standard Metadata
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"description": "What your plugin does",
|
||||
"author": {
|
||||
"name": "Your Name",
|
||||
"email": "you@example.com",
|
||||
"url": "https://github.com/your-username"
|
||||
},
|
||||
"homepage": "https://your-plugin-homepage.com",
|
||||
"repository": "https://github.com/your-org/your-repo",
|
||||
"license": "MIT",
|
||||
"keywords": ["tag1", "tag2"]
|
||||
}
|
||||
```
|
||||
|
||||
- **version**: Semantic version format (optional metadata)
|
||||
- **description**: Brief explanation of plugin purpose (optional metadata)
|
||||
- **author**: Can be string or object with name, email, url
|
||||
- **homepage**: Documentation URL (optional metadata)
|
||||
- **repository**: Source code URL (optional metadata)
|
||||
- **license**: License identifier like "MIT" (optional metadata)
|
||||
- **keywords**: Array of tags for discovery (optional metadata)
|
||||
|
||||
### Component Configuration (Custom Paths Only)
|
||||
|
||||
**IMPORTANT**: Only include these fields if you're using **non-standard** paths. If using standard directory structure (`commands/`, `agents/`, `skills/`, `hooks/`), omit these fields entirely.
|
||||
|
||||
```json
|
||||
{
|
||||
"commands": ["./custom/path/cmd1.md", "./custom/path/cmd2.md"],
|
||||
"agents": ["./custom/agents/reviewer.md", "./custom/agents/tester.md"],
|
||||
"hooks": "./custom/hooks/hooks.json",
|
||||
"mcpServers": {
|
||||
"server-name": {
|
||||
"command": "node",
|
||||
"args": ["path/to/server.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Component Path Rules
|
||||
|
||||
- **commands**: Array of paths to individual `.md` command files, OR string path to a directory
|
||||
- **agents**: Array of paths to individual `.md` agent files (NOT a directory path)
|
||||
- **hooks**: Path to `hooks.json` configuration file OR inline hooks object
|
||||
- **mcpServers**: MCP server configurations object OR path to MCP config file
|
||||
|
||||
All paths must be **relative to plugin root** (where `.claude-plugin/` lives) and start with `./`
|
||||
|
||||
**Note**: Custom paths supplement default directories - they don't replace them. If `commands/` exists, it's loaded in addition to custom command paths.
|
||||
|
||||
### Skills Configuration
|
||||
|
||||
For Skills (Agent Skills) provided by your plugin, you can restrict which tools Claude can use:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-skill-plugin",
|
||||
"skills": [
|
||||
{
|
||||
"name": "safe-reader",
|
||||
"allowed-tools": ["Read", "Grep", "Glob"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
However, the recommended approach is to specify `allowed-tools` directly in the `SKILL.md` frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: safe-reader
|
||||
description: Read files without making changes
|
||||
allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
**`${CLAUDE_PLUGIN_ROOT}`** is a special environment variable available in your plugin that contains the absolute path to your plugin directory. Use this in hooks, MCP servers, and scripts to ensure correct paths regardless of installation location.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"hooks": "./hooks/hooks.json"
|
||||
}
|
||||
```
|
||||
|
||||
Where `hooks/hooks.json` contains:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or inline hooks:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use `${CLAUDE_PLUGIN_ROOT}` for:
|
||||
- Scripts executed by hooks
|
||||
- MCP server paths
|
||||
- Config files referenced by components
|
||||
- Any file paths in your plugin configuration
|
||||
|
||||
## Examples
|
||||
|
||||
### Standard Directory Structure (Recommended)
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-dev-tools"
|
||||
}
|
||||
```
|
||||
|
||||
**Minimal plugin** - The simplest possible plugin. Claude Code automatically discovers `commands/`, `agents/`, `skills/`, and `hooks/` directories.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-dev-tools",
|
||||
"version": "1.2.0",
|
||||
"description": "Developer productivity tools for Claude Code",
|
||||
"author": {
|
||||
"name": "Dev Team",
|
||||
"email": "dev@company.com"
|
||||
},
|
||||
"license": "MIT",
|
||||
"keywords": ["productivity", "tools"]
|
||||
}
|
||||
```
|
||||
|
||||
**With metadata** - Adding optional metadata for better discovery and documentation.
|
||||
|
||||
### Custom Paths
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "enterprise-plugin",
|
||||
"description": "Enterprise development tools",
|
||||
"author": {
|
||||
"name": "Your Name"
|
||||
},
|
||||
"commands": [
|
||||
"./specialized/deploy.md",
|
||||
"./utilities/batch-process.md"
|
||||
],
|
||||
"agents": [
|
||||
"./custom-agents/reviewer.md",
|
||||
"./custom-agents/tester.md"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: Using custom paths to organize components. The `description` and `author` fields are optional metadata.
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
❌ **Wrong**: Including component fields with standard paths
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"commands": "./commands/",
|
||||
"agents": "./agents/"
|
||||
}
|
||||
```
|
||||
|
||||
✅ **Correct**: Omit component fields for standard paths
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin"
|
||||
}
|
||||
```
|
||||
|
||||
❌ **Wrong**: agents as directory path
|
||||
```json
|
||||
{
|
||||
"agents": "./agents/"
|
||||
}
|
||||
```
|
||||
|
||||
✅ **Correct**: agents as array of file paths
|
||||
```json
|
||||
{
|
||||
"agents": ["./agents/reviewer.md", "./agents/tester.md"]
|
||||
}
|
||||
```
|
||||
|
||||
❌ **Wrong**: Absolute paths
|
||||
```json
|
||||
{
|
||||
"commands": "/Users/you/plugins/my-plugin/commands/"
|
||||
}
|
||||
```
|
||||
|
||||
✅ **Correct**: Relative paths
|
||||
```json
|
||||
{
|
||||
"commands": ["./custom/cmd.md"]
|
||||
}
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
Use `/plugin-development:validate` to check your manifest structure.
|
||||
51
skills/plugin-authoring/templates/agent-template.md
Normal file
51
skills/plugin-authoring/templates/agent-template.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
description: What this agent specializes in and when to invoke it (third person).
|
||||
capabilities: ["capability-1", "capability-2", "capability-3"]
|
||||
---
|
||||
|
||||
# Agent Name
|
||||
|
||||
[Brief introduction to the agent's purpose and specialization]
|
||||
|
||||
## What This Agent Does
|
||||
|
||||
[Detailed description of the agent's responsibilities]
|
||||
|
||||
## Capabilities
|
||||
|
||||
1. **Capability 1**: [Description]
|
||||
2. **Capability 2**: [Description]
|
||||
3. **Capability 3**: [Description]
|
||||
|
||||
## When to Use This Agent
|
||||
|
||||
Invoke this agent when:
|
||||
- [Scenario 1]
|
||||
- [Scenario 2]
|
||||
- [Scenario 3]
|
||||
|
||||
## How It Proceeds
|
||||
|
||||
[Step-by-step workflow the agent follows]
|
||||
|
||||
1. **Analyze**: [What it reads/examines]
|
||||
2. **Evaluate**: [How it assesses the situation]
|
||||
3. **Report**: [What it returns to the main conversation]
|
||||
|
||||
## Output Format
|
||||
|
||||
[What kind of report or recommendations the agent provides]
|
||||
|
||||
Example:
|
||||
- Critical issues (must fix)
|
||||
- Warnings (should fix)
|
||||
- Suggestions (nice to have)
|
||||
- Summary of findings
|
||||
|
||||
## Tool Access
|
||||
|
||||
[What tools this agent has access to and why]
|
||||
|
||||
## Notes
|
||||
|
||||
[Any limitations, constraints, or important considerations]
|
||||
32
skills/plugin-authoring/templates/command-template.md
Normal file
32
skills/plugin-authoring/templates/command-template.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
description: Brief, third-person description of what this command does
|
||||
argument-hint: [arg1] [arg2]
|
||||
---
|
||||
|
||||
# Command Name
|
||||
|
||||
[Detailed instructions for Claude on how to execute this command]
|
||||
|
||||
## Context
|
||||
|
||||
[When and why to use this command]
|
||||
|
||||
## Instructions
|
||||
|
||||
1. [Step 1: What to do first]
|
||||
2. [Step 2: Next action]
|
||||
3. [Step 3: Final step]
|
||||
|
||||
## Arguments
|
||||
|
||||
- `$ARGUMENTS` or `$1`, `$2`, etc.: [Explain what each argument means]
|
||||
|
||||
## Example Usage
|
||||
|
||||
**Command**: `/namespace:command-name arg1 arg2`
|
||||
|
||||
**Expected behavior**: [Describe what should happen]
|
||||
|
||||
## Notes
|
||||
|
||||
[Any additional context, warnings, or tips]
|
||||
25
skills/plugin-authoring/templates/marketplace-manifest.json
Normal file
25
skills/plugin-authoring/templates/marketplace-manifest.json
Normal file
@@ -0,0 +1,25 @@
|
||||
{
|
||||
"name": "MARKETPLACE-NAME",
|
||||
"owner": {
|
||||
"name": "Your Organization",
|
||||
"email": "team@your-org.com"
|
||||
},
|
||||
"metadata": {
|
||||
"description": "A curated collection of Claude Code plugins",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "plugin-name",
|
||||
"description": "What the plugin does",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Author Name"
|
||||
},
|
||||
"source": "./plugins/plugin-name",
|
||||
"category": "utilities",
|
||||
"tags": ["tag1", "tag2"],
|
||||
"keywords": ["keyword1", "keyword2"]
|
||||
}
|
||||
]
|
||||
}
|
||||
14
skills/plugin-authoring/templates/plugin-manifest.json
Normal file
14
skills/plugin-authoring/templates/plugin-manifest.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"name": "PLUGIN-NAME",
|
||||
"version": "0.1.0",
|
||||
"description": "Brief description of what this plugin does",
|
||||
"author": {
|
||||
"name": "Your Name",
|
||||
"email": "you@example.com",
|
||||
"url": "https://github.com/your-username"
|
||||
},
|
||||
"homepage": "https://github.com/your-org/your-repo",
|
||||
"repository": "https://github.com/your-org/your-repo",
|
||||
"license": "MIT",
|
||||
"keywords": ["keyword1", "keyword2"]
|
||||
}
|
||||
49
skills/plugin-authoring/templates/skill-template.md
Normal file
49
skills/plugin-authoring/templates/skill-template.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
name: skill-name
|
||||
description: What the Skill does and WHEN to use it (third person). Be specific about triggers.
|
||||
# allowed-tools: Read, Grep, Glob # Optional: Only add if you want to restrict available tools
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
[Brief introduction to what this Skill provides]
|
||||
|
||||
## Purpose
|
||||
|
||||
[Explain the Skill's role and capabilities]
|
||||
|
||||
## When to Activate
|
||||
|
||||
[Describe specific contexts or patterns that should trigger this Skill]
|
||||
|
||||
Examples:
|
||||
- When the user mentions [specific topic]
|
||||
- When files matching [pattern] are present
|
||||
- When working with [technology/framework]
|
||||
|
||||
## Capabilities
|
||||
|
||||
[What this Skill can help with]
|
||||
|
||||
1. [Capability 1]
|
||||
2. [Capability 2]
|
||||
3. [Capability 3]
|
||||
|
||||
## Quick Links
|
||||
|
||||
[Link to sibling files for progressive disclosure]
|
||||
|
||||
- [Reference 1](./reference1.md)
|
||||
- [Reference 2](./reference2.md)
|
||||
|
||||
## Workflow
|
||||
|
||||
[Step-by-step approach this Skill follows]
|
||||
|
||||
1. [Analyze/Read relevant files]
|
||||
2. [Propose actions]
|
||||
3. [Execute via commands or provide guidance]
|
||||
|
||||
## Notes
|
||||
|
||||
[Any constraints, best practices, or important information]
|
||||
Reference in New Issue
Block a user