A0 Plugin Router

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// - user plugins (your custom plugins go here)
2. plugins// - 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// and extensions/python/_functions//// | Backend lifecycle hooks and implicit @extensible hooks | | extensions/webui// | 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, 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//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////. The older flattened extensions/python/__/ 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//plugins//config.json
2. project/.a0proj/plugins//config.json
3. usr/agents//plugins//config.json
4. usr/plugins//config.json
5. plugins//default_config.yaml

Key API Routes

| Route | Purpose | |---|---| | GET /plugins// | Serve static plugin assets | | POST /api/plugins// | Call plugin API endpoint | | POST /api/plugins | Management (toggle, config, docs) |

Deep-Dive References

• Architecture + extension points: /a0/docs/agents/AGENTS.plugins.md
• Developer guide: /a0/docs/developer/plugins.md
• Component system: /a0/docs/agents/AGENTS.components.md
• Modal system: /a0/docs/agents/AGENTS.modals.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Gen-Verse
• Source: Gen-Verse/PAST-Bench
• License: Apache-2.0
• Homepage: https://arxiv.org/abs/2608.04003

Install and usage instructions live in the source repository linked above.