Initial commit
This commit is contained in:
Zhongwei Li
@@ -0,0 +1,225 @@
|
||||
# Common Plugin Patterns
|
||||
|
||||
## Pattern: Simple Plugin with One Skill
|
||||
|
||||
**Use when:** Creating a focused plugin with documentation/reference material
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/
|
||||
│ ├── plugin.json
|
||||
│ └── marketplace.json
|
||||
├── skills/
|
||||
│ └── my-skill/
|
||||
│ ├── SKILL.md
|
||||
│ ├── scripts/ # Optional - Executable helpers
|
||||
│ └── references/ # Optional - Documentation files
|
||||
└── README.md
|
||||
```
|
||||
|
||||
**Real example:** `superpowers-developing-for-claude-code`
|
||||
- Single skill with comprehensive documentation
|
||||
- Scripts for self-updating
|
||||
- 40+ reference files
|
||||
- No MCP servers, commands, or hooks
|
||||
|
||||
**When to use:**
|
||||
- Teaching Claude about a specific topic/domain
|
||||
- Providing process workflows (TDD, debugging, code review)
|
||||
- Bundling documentation for easy reference
|
||||
- Creating reusable knowledge bases
|
||||
|
||||
---
|
||||
|
||||
## Pattern: MCP Plugin with Skill
|
||||
|
||||
**Use when:** Providing both a tool integration (MCP) and guidance on using it (skill)
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json # Includes mcpServers config
|
||||
├── skills/
|
||||
│ └── using-the-tools/
|
||||
│ └── SKILL.md # How to use the MCP tools
|
||||
├── mcp/
|
||||
│ └── dist/
|
||||
│ └── index.js # MCP server implementation
|
||||
└── README.md
|
||||
```
|
||||
|
||||
**Real example:** `superpowers-chrome`
|
||||
- MCP server provides browser control tools
|
||||
- Skill teaches Claude how to use those tools effectively
|
||||
- Skill includes patterns, examples, workflows
|
||||
|
||||
**When to use:**
|
||||
- Adding new tools/capabilities to Claude
|
||||
- Integrating external APIs or services
|
||||
- Tools need guidance on when/how to use them
|
||||
- Want Claude to use tools idiomatically, not just technically
|
||||
|
||||
**Key insight:** MCP provides *capability*, skill provides *judgment*. The MCP server exposes `click()`, the skill teaches "await elements before clicking them".
|
||||
|
||||
---
|
||||
|
||||
## Pattern: Command Collection
|
||||
|
||||
**Use when:** Providing multiple custom slash commands for common tasks
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json
|
||||
├── commands/
|
||||
│ ├── status.md
|
||||
│ ├── logs.md
|
||||
│ ├── deploy.md
|
||||
│ └── rollback.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- Project-specific workflows (deploy, test, build)
|
||||
- Common task shortcuts
|
||||
- Standardized responses (greetings, status reports)
|
||||
- Quick context injection
|
||||
|
||||
**Example use cases:**
|
||||
- `/deploy-staging` - Step-by-step deployment workflow
|
||||
- `/incident-report` - Template for incident documentation
|
||||
- `/code-review` - Checklist for reviewing PRs
|
||||
- `/security-check` - Security audit workflow
|
||||
|
||||
---
|
||||
|
||||
## Pattern: Hook-Enhanced Workflow
|
||||
|
||||
**Use when:** Automating actions in response to Claude's behavior
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json
|
||||
├── hooks/
|
||||
│ └── hooks.json
|
||||
├── scripts/
|
||||
│ ├── format-code.sh
|
||||
│ ├── run-linter.sh
|
||||
│ └── update-docs.sh
|
||||
└── README.md
|
||||
```
|
||||
|
||||
**Common hooks:**
|
||||
- `PostToolUse[Write|Edit]` → Auto-format code
|
||||
- `SessionStart` → Load project context
|
||||
- `UserPromptSubmit` → Enforce conventions
|
||||
- `PreCompact` → Save conversation summaries
|
||||
|
||||
**When to use:**
|
||||
- Enforcing code style automatically
|
||||
- Injecting project-specific context
|
||||
- Running validations or checks
|
||||
- Maintaining project conventions
|
||||
|
||||
**Warning:** Hooks that block operations can disrupt workflow. Use sparingly and make failure messages clear.
|
||||
|
||||
---
|
||||
|
||||
## Pattern: Full-Featured Plugin
|
||||
|
||||
**Use when:** Building a comprehensive plugin with multiple integration points
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json
|
||||
├── skills/
|
||||
│ ├── main-workflow/
|
||||
│ └── advanced-techniques/
|
||||
├── commands/
|
||||
│ ├── start.md
|
||||
│ └── help.md
|
||||
├── hooks/
|
||||
│ └── hooks.json
|
||||
├── agents/
|
||||
│ └── specialist.md
|
||||
├── mcp/
|
||||
│ └── dist/
|
||||
│ └── server.js
|
||||
└── README.md
|
||||
```
|
||||
|
||||
**Real example:** See `examples/full-featured-plugin/` in this repo
|
||||
|
||||
**When to use:**
|
||||
- Complete domain coverage (e.g., "the definitive AWS plugin")
|
||||
- Multiple related workflows
|
||||
- Tools + guidance + automation all needed
|
||||
- Building a "platform" plugin
|
||||
|
||||
**Caution:** Start simple, add complexity only when justified. Most plugins don't need all components.
|
||||
|
||||
---
|
||||
|
||||
## Pattern: Skill with Bundled Resources
|
||||
|
||||
**Use when:** A skill needs reference material, scripts, or templates
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
skills/my-skill/
|
||||
├── SKILL.md # Main skill instructions
|
||||
├── scripts/
|
||||
│ ├── helper.py # Executable utilities
|
||||
│ └── generator.js
|
||||
├── references/
|
||||
│ ├── api-docs.md # Documentation to load
|
||||
│ ├── examples.md
|
||||
│ └── cheatsheet.md
|
||||
└── assets/
|
||||
├── template.txt # Files for output
|
||||
└── config-example.json
|
||||
```
|
||||
|
||||
**How resources are used:**
|
||||
- SKILL.md tells Claude to "read references/api-docs.md for complete API reference"
|
||||
- Scripts can be executed via Bash tool
|
||||
- Assets can be copied/modified for output
|
||||
- References are loaded into context when skill is invoked
|
||||
|
||||
**When to use:**
|
||||
- Skill needs detailed technical reference
|
||||
- Want to separate workflow (SKILL.md) from reference (docs)
|
||||
- Need executable helpers
|
||||
- Providing templates or examples
|
||||
|
||||
---
|
||||
|
||||
## Choosing the Right Pattern
|
||||
|
||||
| Your Goal | Use This Pattern |
|
||||
|-----------|------------------|
|
||||
| Teach Claude a process/workflow | Simple Plugin with One Skill |
|
||||
| Add new tools + guidance | MCP Plugin with Skill |
|
||||
| Provide project shortcuts | Command Collection |
|
||||
| Enforce conventions automatically | Hook-Enhanced Workflow |
|
||||
| Comprehensive domain coverage | Full-Featured Plugin |
|
||||
| Skill needs reference docs | Skill with Bundled Resources |
|
||||
|
||||
## Combining Patterns
|
||||
|
||||
Patterns are composable:
|
||||
|
||||
**Example: "superpowers" plugin**
|
||||
- Multiple skills (brainstorming, TDD, debugging) ← Skill collection
|
||||
- Each skill has references/ ← Bundled resources
|
||||
- Could add hooks for enforcement ← Add hooks pattern
|
||||
- Could add MCP for new tools ← Add MCP pattern
|
||||
|
||||
**Start simple, grow intentionally.** Add components when you have a clear reason, not because they exist.
|
||||
@@ -0,0 +1,314 @@
|
||||
# Plugin Structure Reference
|
||||
|
||||
## Standard Directory Layout
|
||||
|
||||
All paths relative to plugin root:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/
|
||||
│ ├── plugin.json # REQUIRED - Plugin metadata
|
||||
│ └── marketplace.json # Optional - For local dev/distribution
|
||||
├── skills/ # Optional - Agent Skills
|
||||
│ └── skill-name/
|
||||
│ ├── SKILL.md # Required for each skill
|
||||
│ ├── scripts/ # Optional - Executable helpers
|
||||
│ ├── references/ # Optional - Documentation
|
||||
│ └── assets/ # Optional - Templates/files
|
||||
├── commands/ # Optional - Custom slash commands
|
||||
│ └── command-name.md
|
||||
├── agents/ # Optional - Specialized subagents
|
||||
│ └── agent-name.md
|
||||
├── hooks/ # Optional - Event handlers
|
||||
│ └── hooks.json
|
||||
├── .mcp.json # Optional - MCP server config
|
||||
├── LICENSE
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Critical Rules
|
||||
|
||||
### 1. `.claude-plugin/` Contains ONLY Manifests
|
||||
|
||||
**❌ WRONG:**
|
||||
```
|
||||
.claude-plugin/
|
||||
├── plugin.json
|
||||
├── skills/ # NO! Skills don't go here
|
||||
└── commands/ # NO! Commands don't go here
|
||||
```
|
||||
|
||||
**✅ CORRECT:**
|
||||
```
|
||||
.claude-plugin/
|
||||
├── plugin.json # Only manifests
|
||||
└── marketplace.json # Only manifests
|
||||
|
||||
skills/ # Skills at plugin root
|
||||
commands/ # Commands at plugin root
|
||||
```
|
||||
|
||||
### 2. Always Use `${CLAUDE_PLUGIN_ROOT}` for Paths in Config
|
||||
|
||||
**❌ WRONG - Hardcoded paths:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-server": {
|
||||
"command": "/Users/name/plugins/my-plugin/server.js"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**✅ CORRECT - Variable paths:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-server": {
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/server.js"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Use Relative Paths in `plugin.json`
|
||||
|
||||
All paths in `plugin.json` must:
|
||||
- Start with `./`
|
||||
- Be relative to plugin root
|
||||
|
||||
**❌ WRONG:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server": {
|
||||
"args": ["server/index.js"] // Missing ./
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**✅ CORRECT:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server": {
|
||||
"args": ["${CLAUDE_PLUGIN_ROOT}/server/index.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Plugin Manifest (plugin.json)
|
||||
|
||||
### Minimal Version
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"version": "1.0.0",
|
||||
"description": "Brief description of what the plugin does",
|
||||
"author": {
|
||||
"name": "Your Name"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Complete Version
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"version": "1.0.0",
|
||||
"description": "Comprehensive plugin description",
|
||||
"author": {
|
||||
"name": "Your Name",
|
||||
"email": "you@example.com",
|
||||
"url": "https://github.com/you"
|
||||
},
|
||||
"homepage": "https://github.com/you/my-plugin",
|
||||
"repository": "https://github.com/you/my-plugin",
|
||||
"license": "MIT",
|
||||
"keywords": ["keyword1", "keyword2"],
|
||||
"mcpServers": {
|
||||
"server-name": {
|
||||
"command": "node",
|
||||
"args": ["${CLAUDE_PLUGIN_ROOT}/path/to/server.js"],
|
||||
"env": {
|
||||
"ENV_VAR": "value"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Development Marketplace (marketplace.json)
|
||||
|
||||
For local testing, create in `.claude-plugin/`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin-dev",
|
||||
"description": "Development marketplace for my plugin",
|
||||
"owner": {
|
||||
"name": "Your Name"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"description": "Plugin description",
|
||||
"version": "1.0.0",
|
||||
"source": "./",
|
||||
"author": {
|
||||
"name": "Your Name"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
/plugin marketplace add /path/to/my-plugin
|
||||
/plugin install my-plugin@my-plugin-dev
|
||||
```
|
||||
|
||||
## Component Formats
|
||||
|
||||
### Skills (skills/skill-name/SKILL.md)
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: Use when [triggering conditions] - [what it does]
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
## Overview
|
||||
|
||||
What this skill does in 1-2 sentences.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Specific scenario 1
|
||||
- Specific scenario 2
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Step one
|
||||
2. Step two
|
||||
3. Step three
|
||||
```
|
||||
|
||||
### Commands (commands/command-name.md)
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Brief description of what this command does
|
||||
---
|
||||
|
||||
# Command Instructions
|
||||
|
||||
Tell Claude what to do when this command is invoked.
|
||||
Be specific and clear about the expected behavior.
|
||||
```
|
||||
|
||||
### Hooks (hooks/hooks.json)
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"SessionStart": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/init.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available hook events:**
|
||||
- `PreToolUse`, `PostToolUse`
|
||||
- `UserPromptSubmit`
|
||||
- `SessionStart`, `SessionEnd`
|
||||
- `Stop`, `SubagentStop`
|
||||
- `PreCompact`
|
||||
- `Notification`
|
||||
|
||||
### MCP Servers
|
||||
|
||||
**Option 1: In plugin.json**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"mcpServers": {
|
||||
"server-name": {
|
||||
"command": "node",
|
||||
"args": ["${CLAUDE_PLUGIN_ROOT}/server/index.js"],
|
||||
"env": {
|
||||
"API_KEY": "${PLUGIN_ENV_API_KEY}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Option 2: Separate .mcp.json file**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server-name": {
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/bin/server",
|
||||
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Agents (agents/agent-name.md)
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: What this agent specializes in
|
||||
capabilities: ["capability1", "capability2"]
|
||||
---
|
||||
|
||||
# Agent Name
|
||||
|
||||
Detailed description of when to invoke this specialized agent.
|
||||
|
||||
## Expertise
|
||||
|
||||
- Specific domain knowledge
|
||||
- Specialized techniques
|
||||
- When to use vs other agents
|
||||
```
|
||||
|
||||
## File Permissions
|
||||
|
||||
Scripts must be executable:
|
||||
|
||||
```bash
|
||||
chmod +x scripts/helper.sh
|
||||
chmod +x bin/server
|
||||
```
|
||||
@@ -0,0 +1,374 @@
|
||||
# Troubleshooting Plugin Development
|
||||
|
||||
## Plugin Not Loading
|
||||
|
||||
### Symptom
|
||||
Plugin doesn't appear in `/plugin list` or components aren't available.
|
||||
|
||||
### Debug Steps
|
||||
|
||||
1. **Check plugin.json syntax**
|
||||
```bash
|
||||
# Validate JSON
|
||||
cat .claude-plugin/plugin.json | jq .
|
||||
```
|
||||
If this errors, you have invalid JSON.
|
||||
|
||||
2. **Verify directory structure**
|
||||
```bash
|
||||
# Ensure .claude-plugin/ exists at plugin root
|
||||
ls -la .claude-plugin/
|
||||
# Should show plugin.json (required)
|
||||
```
|
||||
|
||||
3. **Check all paths**
|
||||
- Search for hardcoded paths: `grep -r "/Users/" .claude-plugin/`
|
||||
- Should use `${CLAUDE_PLUGIN_ROOT}` instead
|
||||
- Relative paths in plugin.json must start with `./`
|
||||
|
||||
4. **Restart Claude Code**
|
||||
- Changes only take effect after restart
|
||||
- Exit and relaunch the application
|
||||
|
||||
5. **Check installation**
|
||||
```bash
|
||||
/plugin list
|
||||
# Your plugin should appear here
|
||||
```
|
||||
|
||||
### Common Causes
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| `.claude-plugin/` missing | Create directory with `plugin.json` |
|
||||
| Invalid JSON in `plugin.json` | Validate with `jq` or JSON linter |
|
||||
| Hardcoded paths | Replace with `${CLAUDE_PLUGIN_ROOT}` |
|
||||
| Forgot to restart | Always restart after install/changes |
|
||||
|
||||
---
|
||||
|
||||
## Skill Not Triggering
|
||||
|
||||
### Symptom
|
||||
Skill exists but Claude doesn't use it when expected.
|
||||
|
||||
### Debug Steps
|
||||
|
||||
1. **Check YAML frontmatter format**
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: Use when [clear trigger] - [what it does]
|
||||
---
|
||||
```
|
||||
- Must have `---` delimiters
|
||||
- Must include `name` and `description`
|
||||
- No tabs, only spaces for indentation
|
||||
|
||||
2. **Verify description clarity**
|
||||
- Description should clearly state WHEN to use skill
|
||||
- Use "Use when..." format
|
||||
- Be specific about triggering conditions
|
||||
|
||||
❌ Bad: `description: A helpful skill`
|
||||
|
||||
✅ Good: `description: Use when debugging test failures - systematic approach to finding root causes`
|
||||
|
||||
3. **Test explicitly**
|
||||
Ask for a task that exactly matches the description:
|
||||
```
|
||||
"I need to debug a test failure"
|
||||
# Should trigger systematic-debugging skill
|
||||
```
|
||||
|
||||
4. **Check skill location**
|
||||
- Must be in `skills/skill-name/SKILL.md`
|
||||
- NOT in `.claude-plugin/skills/`
|
||||
|
||||
### Common Causes
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| Vague description | Make description specific and action-oriented |
|
||||
| Skill in wrong location | Move to `skills/` at plugin root |
|
||||
| Missing frontmatter | Add YAML with name and description |
|
||||
| Malformed YAML | Check for tabs, missing dashes, etc. |
|
||||
|
||||
---
|
||||
|
||||
## Command Not Appearing
|
||||
|
||||
### Symptom
|
||||
Custom slash command doesn't show up or can't be executed.
|
||||
|
||||
### Debug Steps
|
||||
|
||||
1. **Verify location**
|
||||
```bash
|
||||
ls -la commands/
|
||||
# Should show command-name.md files
|
||||
```
|
||||
Commands must be at `commands/` in plugin root, NOT in `.claude-plugin/`
|
||||
|
||||
2. **Check markdown format**
|
||||
```markdown
|
||||
---
|
||||
description: Brief description of what this command does
|
||||
---
|
||||
|
||||
# Command Instructions
|
||||
|
||||
Content here...
|
||||
```
|
||||
|
||||
3. **Restart Claude Code**
|
||||
Commands are loaded at startup.
|
||||
|
||||
4. **Test directly**
|
||||
```
|
||||
/your-command-name
|
||||
```
|
||||
|
||||
### Common Causes
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| Commands in `.claude-plugin/` | Move to `commands/` at root |
|
||||
| Missing description frontmatter | Add YAML with description |
|
||||
| No restart after adding | Restart Claude Code |
|
||||
| Wrong file extension | Must be `.md` not `.txt` |
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Not Starting
|
||||
|
||||
### Symptom
|
||||
MCP server tools not available, or server fails silently.
|
||||
|
||||
### Debug Steps
|
||||
|
||||
1. **Verify path variables**
|
||||
All paths in MCP config must use `${CLAUDE_PLUGIN_ROOT}`:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-server": {
|
||||
"command": "node",
|
||||
"args": ["${CLAUDE_PLUGIN_ROOT}/server/index.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Check executable permissions**
|
||||
```bash
|
||||
chmod +x server/index.js
|
||||
# Or for shell scripts:
|
||||
chmod +x bin/server.sh
|
||||
```
|
||||
|
||||
3. **Test server independently**
|
||||
```bash
|
||||
# Run server outside Claude Code to check for errors
|
||||
node ${PLUGIN_ROOT}/server/index.js
|
||||
```
|
||||
|
||||
4. **Check logs**
|
||||
```bash
|
||||
claude --debug
|
||||
# Look for MCP server startup errors
|
||||
```
|
||||
|
||||
5. **Verify command exists**
|
||||
```bash
|
||||
which node # Or whatever command you're using
|
||||
```
|
||||
|
||||
### Common Causes
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| Hardcoded paths | Use `${CLAUDE_PLUGIN_ROOT}` |
|
||||
| Not executable | `chmod +x` on scripts |
|
||||
| Command not in PATH | Use full path or ensure command available |
|
||||
| Server crashes on startup | Test independently, check logs |
|
||||
| Missing dependencies | `npm install` or equivalent |
|
||||
|
||||
---
|
||||
|
||||
## Hooks Not Firing
|
||||
|
||||
### Symptom
|
||||
Hook scripts exist but don't execute when events occur.
|
||||
|
||||
### Debug Steps
|
||||
|
||||
1. **Check hooks.json location**
|
||||
Must be at `hooks/hooks.json` in plugin root.
|
||||
|
||||
2. **Verify JSON format**
|
||||
```bash
|
||||
cat hooks/hooks.json | jq .
|
||||
```
|
||||
|
||||
3. **Check matcher syntax**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit", // Regex - matches Write OR Edit
|
||||
"hooks": [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
4. **Verify script paths**
|
||||
```json
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
|
||||
}
|
||||
```
|
||||
|
||||
5. **Check script permissions**
|
||||
```bash
|
||||
chmod +x scripts/format.sh
|
||||
```
|
||||
|
||||
6. **Test script directly**
|
||||
```bash
|
||||
# Run the hook script manually
|
||||
./scripts/format.sh
|
||||
```
|
||||
|
||||
### Common Causes
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| Wrong hooks.json location | Move to `hooks/` at plugin root |
|
||||
| Script not executable | `chmod +x` on all scripts |
|
||||
| Invalid matcher regex | Test regex syntax |
|
||||
| Script fails silently | Add error handling, test independently |
|
||||
| Hardcoded paths | Use `${CLAUDE_PLUGIN_ROOT}` |
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow Issues
|
||||
|
||||
### Can't Install Plugin Locally
|
||||
|
||||
**Problem:** `/plugin install my-plugin@my-dev` fails
|
||||
|
||||
**Solutions:**
|
||||
1. Check marketplace.json exists in `.claude-plugin/`
|
||||
2. Verify marketplace is added:
|
||||
```bash
|
||||
/plugin marketplace add /full/path/to/plugin
|
||||
/plugin marketplace list # Should show your marketplace
|
||||
```
|
||||
3. Check marketplace.json format:
|
||||
```json
|
||||
{
|
||||
"name": "my-dev",
|
||||
"plugins": [{
|
||||
"name": "my-plugin",
|
||||
"source": "./" // Points to plugin root
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### Changes Not Taking Effect
|
||||
|
||||
**Problem:** Modified plugin but changes don't appear
|
||||
|
||||
**Solutions:**
|
||||
1. Uninstall → modify → reinstall → restart:
|
||||
```bash
|
||||
/plugin uninstall my-plugin@my-dev
|
||||
# Make your changes
|
||||
/plugin install my-plugin@my-dev
|
||||
# Restart Claude Code
|
||||
```
|
||||
2. For hook/MCP changes, restart is mandatory
|
||||
3. For skill/command content changes, sometimes works without restart (but safer to restart)
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls Summary
|
||||
|
||||
| Mistake | Why It Fails | How to Fix |
|
||||
|---------|-------------|------------|
|
||||
| Skills in `.claude-plugin/skills/` | Claude looks in `skills/` at root | Move to plugin root |
|
||||
| Hardcoded absolute paths | Breaks on other systems | Use `${CLAUDE_PLUGIN_ROOT}` |
|
||||
| Forgot to restart | Changes load at startup | Always restart after changes |
|
||||
| Script not executable | Shell can't run it | `chmod +x script.sh` |
|
||||
| Invalid JSON | Parser fails silently | Validate with `jq` or linter |
|
||||
| Vague skill description | Claude doesn't know when to use it | Be specific about triggers |
|
||||
| Missing YAML frontmatter | Metadata not parsed | Add `---` delimiters and fields |
|
||||
| Testing without uninstall | Old version still cached | Uninstall before reinstalling |
|
||||
|
||||
---
|
||||
|
||||
## Debugging Workflow
|
||||
|
||||
When something isn't working:
|
||||
|
||||
1. **Validate all JSON files**
|
||||
```bash
|
||||
jq . .claude-plugin/plugin.json
|
||||
jq . .claude-plugin/marketplace.json
|
||||
jq . hooks/hooks.json
|
||||
```
|
||||
|
||||
2. **Check all paths use variables**
|
||||
```bash
|
||||
grep -r "Users/" .
|
||||
# Should return nothing in config files
|
||||
```
|
||||
|
||||
3. **Verify permissions**
|
||||
```bash
|
||||
find . -name "*.sh" -o -name "*.js" | xargs ls -l
|
||||
# Check executable bit (x) is set
|
||||
```
|
||||
|
||||
4. **Test components independently**
|
||||
- Run MCP servers directly
|
||||
- Execute hook scripts manually
|
||||
- Validate YAML frontmatter with a parser
|
||||
|
||||
5. **Clean reinstall**
|
||||
```bash
|
||||
/plugin uninstall my-plugin@my-dev
|
||||
/plugin marketplace remove /path/to/plugin
|
||||
# Fix issues
|
||||
/plugin marketplace add /path/to/plugin
|
||||
/plugin install my-plugin@my-dev
|
||||
# Restart Claude Code
|
||||
```
|
||||
|
||||
6. **Check logs**
|
||||
```bash
|
||||
claude --debug
|
||||
# Look for error messages during startup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you're still stuck:
|
||||
|
||||
1. **Read official docs** via `working-with-claude-code` skill
|
||||
2. **Check example plugins** in this repo and `~/.claude/plugins/`
|
||||
3. **Simplify** - Remove components until it works, then add back one at a time
|
||||
4. **Report issues** at https://github.com/anthropics/claude-code/issues
|
||||
|
||||
**Pro tip:** When asking for help, include:
|
||||
- Your plugin.json
|
||||
- Directory structure (`tree -L 3 -a`)
|
||||
- Exact error messages
|
||||
- What you've already tried
|
||||
Reference in New Issue
Block a user