a0-debug-plugin
Diagnose and fix Agent Zero plugin problems. Covers plugin not appearing, won't enable, API endpoints not responding, frontend store errors, extension point injection, settings resolution, hooks.py issues, and log inspection. Use when a plugin is not working, not loading, crashing, missing from the list, or behaving unexpectedly.
Best for Plugin developersWorks with GitHubLow risk
⌘source
- author
@agent0ai- language
- Python
★17kstars
3.6kforks
May 2, 2026
✦overview.md
Key Features
- ·Step-by-step diagnostic checks
- ·Check plugin.yaml existence and validity
- ·Inspect toggle states and scoped overrides
- ·Test API endpoint connectivity
- ·Examine frontend console errors
- ·Review logs with systematic grep
Use Cases
- →Plugin not appearing in the list after installation
- →Plugin won't enable despite correct installation
- →API endpoints from plugin returning errors
- →Frontend errors related to plugin injection
- →Unexpected behavior from hooks.py or settings
Best for
- ✓Plugin developers
- ✓Troubleshooting agent plugins
Not ideal for
- !Non-plugin general debugging
- !Hardware issues
FAQs
name
a0-debug-plugin
description
Diagnose and fix Agent Zero plugin problems. Covers plugin not appearing, won't enable, API endpoints not responding, frontend store errors, extension point injection, settings resolution, hooks.py issues, and log inspection. Use when a plugin is not working, not loading, crashing, missing from the list, or behaving unexpectedly.
version:1.0.0
tags:["plugins","debug","troubleshoot","fix","diagnose","error","broken"]
trigger_patterns:["plugin not working","plugin not loading","plugin not showing","plugin broken","plugin error","plugin missing","plugin crash","debug plugin","troubleshoot plugin","fix plugin"]
Agent Zero Plugin Debugger
Work through these checks in order. Stop at the first failure and fix it before continuing.
1. Plugin not appearing in the Plugins list
# Check plugin.yaml exists
ls /a0/usr/plugins/<name>/plugin.yaml
# Validate YAML
python3 -c "import yaml; yaml.safe_load(open('/a0/usr/plugins/<name>/plugin.yaml'))"
# Check directory name doesn't start with '.'
ls /a0/usr/plugins/
Common causes:
- Missing
plugin.yaml- plugin not discovered - Invalid YAML syntax - plugin skipped silently
- Directory name starts with
.- skipped by discovery
2. Plugin appears but won't enable
# Check toggle state
ls -la /a0/usr/plugins/<name>/.toggle-*
# Check for conflicting scoped toggles
ls -la project/.a0proj/plugins/<name>/.toggle-* 2>/dev/null
ls -la /a0/usr/agents/default/plugins/<name>/.toggle-* 2>/dev/null
3. API endpoint not responding
- Verify the handler file is in
api/and subclassesApiHandler - Route format:
POST /api/plugins/<plugin_name>/<handler_filename_without_.py> - Check for Python import errors on startup (check Agent Zero logs)
$install
1-click copynpx skills add agent0ai/agent-zero --skill a0-debug-pluginSafety assessment
★
Clarity score
How clear and easy to understand the SKILL.md instructions are, rated from 1 to 5.
5/ 5
excellentVery clear and well structured, with almost no room for misunderstanding.
◎
Actionability score
How directly an agent can act on the SKILL.md instructions, rated from 1 to 5.
5/ 5
very highHighly actionable with clear, concrete steps that an agent can follow directly.