a0-plugin-router

name	a0-plugin-router
description	Main entry point for all Agent Zero plugin tasks. Routes to specialist skills for creating, reviewing, contributing, managing, or debugging plugins. Use when the user mentions plugins, asks how the plugin system works, wants to build/install/uninstall/publish/debug a plugin, or asks about the Plugin Hub.
version	1.0.0
tags	["plugins","router","meta","create","review","contribute","manage","plugin-hub"]
trigger_patterns	["plugin","create plugin","build plugin","review plugin","contribute plugin","publish plugin","install plugin","manage plugin","plugin hub","plugin index","how does the plugin system work"]

Agent Zero Plugin Router

Routing Decision

Classify the user's request and read the appropriate specialist skill immediately.

User intent	Skill to read
Create / build / develop / write a new plugin	Read /a0/skills/a0-create-plugin/SKILL.md
Review / audit / validate / check a plugin	Read /a0/skills/a0-review-plugin/SKILL.md
Contribute / publish / submit / share to community	Read /a0/skills/a0-contribute-plugin/SKILL.md
Install / update / uninstall / remove / browse / scan	Read /a0/skills/a0-manage-plugin/SKILL.md
Plugin not working / crashing / missing / debug / troubleshoot	Read /a0/skills/a0-debug-plugin/SKILL.md
Explain / how does it work / architecture	Answer inline using the overview below

If intent is ambiguous, ask one question before routing:

"Are you trying to create a new plugin, review one, contribute it to the community, manage (install/update/uninstall) plugins, or debug a plugin that isn't working?"

If the user says "make a plugin for the community" - start with a0-create-plugin, then note that a0-contribute-plugin handles the publishing step after the plugin is built and tested.

---

Plugin System Overview (for explain/explore queries)

Roots and Discovery

Agent Zero discovers plugins from two roots, in priority order:

1. usr/plugins/<name>/ - user plugins (your custom plugins go here)
2. plugins/<name>/ - core system plugins (framework-bundled, do not modify)

A plugin is valid when its directory contains a plugin.yaml. Directories starting with . are skipped.

Runtime Manifest (plugin.yaml)

Every plugin requires a plugin.yaml at its root:

name: my_plugin              # required by CI for community plugins (^[a-z0-9_]+$)
title: My Plugin             # UI display name
description: What it does.
version: 1.0.0
settings_sections: [agent]   # which Settings tabs show a subsection
per_project_config: false    # enables project-scoped settings/toggle
per_agent_config: false      # enables agent-profile-scoped settings/toggle
always_enabled: false        # forces ON, disables toggle (framework use only)

settings_sections valid values: agent, external, mcp, developer, backup. Use [] for none.

What a Plugin Can Provide

Directory/File	Purpose
api/	API handlers (ApiHandler subclasses)
tools/	Agent tools (Tool subclasses)
extensions/python/<point>/ and extensions/python/_functions/<module>/<qualname>/<start_or_end>/	Backend lifecycle hooks and implicit @extensible hooks
extensions/webui/<point>/	HTML/JS injected into UI breakpoints
webui/config.html	Plugin settings UI
webui/*.html, webui/*.js	Full plugin pages and Alpine stores
hooks.py	Framework runtime hooks (install, uninstall, pre_update, cache, registration)
execute.py	User-triggered script (setup, maintenance, repair)
default_config.yaml	Settings defaults
README.md	Optional locally; strongly recommended for community plugins so Plugin Hub users can inspect the plugin
agents/<profile>/agent.yaml	Plugin-distributed agent profiles
conf/model_providers.yaml	Add/override model providers
LICENSE	Optional under usr/plugins/; required at the root of a plugin GitHub repo before submitting to the Plugin Index

For @extensible targets, the only valid implicit hook layout is extensions/python/_functions/<module>/<qualname>/<start|end>/. The older flattened extensions/python/<module>_<qualname>_<start|end>/ folders are obsolete.

Activation

• Global toggle: .toggle-1 (ON) / .toggle-0 (OFF) files in the plugin dir
• Scoped toggles (project/agent) available when per_project_config or per_agent_config is true
• Default: enabled when no toggle file exists
• always_enabled: true forces ON and hides controls (reserved for framework)

Settings Resolution (highest priority first)

1. project/.a0proj/agents/<profile>/plugins/<name>/config.json
2. project/.a0proj/plugins/<name>/config.json
3. usr/agents/<profile>/plugins/<name>/config.json
4. usr/plugins/<name>/config.json
5. plugins/<name>/default_config.yaml

Key API Routes

Route	Purpose
GET /plugins/<name>/<path>	Serve static plugin assets
POST /api/plugins/<name>/<handler>	Call plugin API endpoint
POST /api/plugins	Management (toggle, config, docs)

Deep-Dive References

• Architecture + extension points: /a0/plugins/AGENTS.md
• Developer guide: /a0/docs/developer/plugins.md
• Component system: /a0/webui/components/AGENTS.md
• Modal system: /a0/webui/js/AGENTS.md and /a0/webui/css/AGENTS.md