Extended debugging guide for plugin development.
| Problem | Cause | Solution |
|---|---|---|
| Plugin not loading | Wrong directory path | Use plugins/plugin-dev, not root |
| Skill not triggering | Weak trigger phrases | Add specific user queries to description |
| Hook not firing | Incorrect matcher pattern | Check regex syntax, test with test-hook.sh |
| Validation script fails | Missing dependencies (jq) |
Install required tools (see README.md) |
| Shell execution in skills | Using ! backtick pattern |
Replace with [BANG] placeholder |
Run Claude Code with debug output:
claude --debug --plugin-dir plugins/plugin-devIf components fail validation:
- Run the specific validator for the component type
- Check frontmatter - ensure all required fields are present
- Verify file location - components must be in correct directories
- Check naming - use kebab-case for names (e.g.,
my-agent, notmyAgent)
Paths relative to plugins/plugin-dev/:
# Agent development
./skills/agent-development/scripts/validate-agent.sh agents/agent-name.md
./skills/agent-development/scripts/test-agent-trigger.sh agents/agent-name.md
# Command development
./skills/command-development/scripts/validate-command.sh .claude/commands/my-command.md
./skills/command-development/scripts/check-frontmatter.sh .claude/commands/my-command.md
# Hook development
./skills/hook-development/scripts/validate-hook-schema.sh hooks/hooks.json
./skills/hook-development/scripts/test-hook.sh hooks/my-hook.sh input.json
# Plugin settings
./skills/plugin-settings/scripts/validate-settings.sh .claude/plugin.local.md- Check README.md FAQ for common questions
- Review CONTRIBUTING.md for common mistakes
- Open an issue if you're stuck