agent0ai/a0-debug-plugin
skills/a0-debug-plugin/SKILL.md
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.
$ install --global
skillsauthnpx skillsauth add agent0ai/agent-zero a0-debug-pluginInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 29, 2026, 6:34 AM346.2s1 file scanned
SKILL.md
- 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"]
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)
- Verify correct import paths:
from agent import AgentContextnotfrom helpers.context import AgentContext
# Check for syntax errors in handler
python3 -m py_compile /a0/usr/plugins/<name>/api/my_handler.py
4. Frontend component not rendering / store errors
- Check browser console for Alpine.js errors
- Verify the store file is imported in HTML
<head>via<script type="module"> - Confirm Store Gate pattern is used (missing gate = undefined error if store not yet loaded)
- Verify store name in
createStore(...)matches$store.<name>in templates
5. Extension point not injecting
- Check the HTML file is in
extensions/webui/<correct_breakpoint_name>/ - Verify the breakpoint name exists in core UI (check
webui/index.htmlor component files for<x-extension id="...">) - Common breakpoints:
sidebar-quick-actions-main-start,plugins-list-header-buttons,chat-input-bottom-actions-end - Confirm the HTML file has a root element with
x-dataand anx-move-*directive
For backend extension hooks:
- Named lifecycle hooks must live under
extensions/python/<point>/ - Implicit
@extensiblehooks must live underextensions/python/_functions/<module>/<qualname>/<start|end>/ - The retired flattened form
extensions/python/<module>_<qualname>_<start|end>/no longer loads
6. Settings not saving / loading wrong values
Config resolution order (highest priority first):
project/.a0proj/agents/<profile>/plugins/<name>/config.jsonproject/.a0proj/plugins/<name>/config.jsonusr/agents/<profile>/plugins/<name>/config.jsonusr/plugins/<name>/config.jsonplugins/<name>/default_config.yaml
# Find which config file is actually being loaded
find /a0 -path "*/plugins/<name>/config.json" 2>/dev/null
7. hooks.py install hook not running
The install() hook is called automatically by the plugin installer after placement. If it didn't run:
- Check the function is named exactly
install(noton_installor similar) - Check for exceptions in the function (add try/except with print for debugging)
- Manually trigger in the framework runtime (not via
code_execution_toolpython - that uses/opt/venv, not/opt/venv-a0):
cd /a0 && /opt/venv-a0/bin/python -c "
import asyncio
from helpers.plugins import call_plugin_hook
asyncio.run(call_plugin_hook('<plugin_name>', 'install'))
print('Done')
"
If the pre_update() hook is not running before plugin updates:
- Check the function is named exactly
pre_update - Check for exceptions in the function
- Manually trigger it in the framework runtime the same way:
cd /a0 && /opt/venv-a0/bin/python -c "
import asyncio
from helpers.plugins import call_plugin_hook
asyncio.run(call_plugin_hook('<plugin_name>', 'pre_update'))
print('Done')
"
If the uninstall() hook is not running when the plugin is removed:
- Check the function is named exactly
uninstall(noton_uninstallor similar) - Check for exceptions in the function
- The
uninstall()hook is called byuninstall_plugin()inhelpers/plugins.pybefore the plugin directory is deleted. If the user removed the plugin manually (rm -rf), the hook was bypassed — always use the API or UI to uninstall. - Manually trigger it in the framework runtime the same way:
cd /a0 && /opt/venv-a0/bin/python -c "
import asyncio
from helpers.plugins import call_plugin_hook
asyncio.run(call_plugin_hook('<plugin_name>', 'uninstall'))
print('Done')
"
8. Check Agent Zero logs
# Find recent log files
ls -lt /a0/logs/*.html | head -5
Plugin-related errors appear as Python tracebacks mentioning the plugin path.
How Plugin Discovery Works
- Agent Zero walks
usr/plugins/thenplugins/at startup - Any directory containing
plugin.yamlis treated as a plugin usr/plugins/<name>takes priority overplugins/<name>when both exist (user overrides core)- Toggle state is evaluated:
.toggle-0disables,.toggle-1enables, no file = enabled by default - Enabled plugins have their
extensions/,api/,tools/, etc. registered into the runtime, including both named extension points and implicit_functions/...extensible hooks
Plugins are re-scanned when:
- Agent Zero restarts
- A plugin is installed/removed via the installer
- The "Refresh" action is triggered in the Plugins UI
References
- Plugin architecture:
/a0/docs/agents/AGENTS.plugins.md - Manage (install/update/uninstall): read
/a0/skills/a0-manage-plugin/SKILL.md
Related Skills
agent0ai/writer-documents
testing
VerifiedTrustedCommunity
Use when creating, opening, or editing LibreOffice Writer ODT documents, or DOCX documents only when Microsoft Word compatibility is explicitly required.
17,774SKILL.mdUpdated May 16, 2026
agent0ai/impress-presentations
testing
VerifiedTrustedCommunity
Use when creating, opening, or editing LibreOffice Impress ODP presentations, or PPTX decks only when PowerPoint compatibility is explicitly required.
17,774SKILL.mdUpdated May 16, 2026
agent0ai/calc-spreadsheets
testing
VerifiedTrustedCommunity
Use when creating, opening, or editing LibreOffice Calc ODS spreadsheets, or XLSX workbooks only when Excel compatibility is explicitly required.
17,774SKILL.mdUpdated May 16, 2026
agent0ai/linux-desktop
data-ai
VerifiedTrustedCommunity
Use when the user asks Agent Zero to operate the built-in Linux Desktop, XFCE apps, LibreOffice GUI apps, file manager, terminal, or visual desktop workflows.
17,774SKILL.mdUpdated May 16, 2026