feat: A0 plugins skillset; update docs; add agent plugin scan endpoint

skills: offload debug from a0-manage-plugin; add a0-debug-plugin
add endpoint for agent-facing plugin security scan

Combine queue and start calls into a synchronous operation, works as the frontend modal version with the agent installing the plugin that gets returned scan results.

For the helper, if the agent had to build the prompt itself, it would need to:

Fetch plugin-scan-checks.json from the server
Fetch plugin-scan-prompt.md from the server
Interpolate all 8 template variables
Send the resulting ~3KB prompt as part of its own context
That's ~3KB of prompt template burning context window on every scan call, plus two extra HTTP requests. With helpers/prompt.py doing it server-side, the agent just sends {"git_url": "...", "checks": [...]} - a handful of tokens - and the server assembles the full prompt internally.

Author: 3clyp50

docs/agents/AGENTS.plugins.md

@@ -46,9 +46,10 @@ usr/plugins/<plugin_name>/
 
 ### plugin.yaml (runtime manifest)
 
-This is the manifest file that lives inside your plugin directory and drives runtime behavior. It is distinct from the index manifest used when publishing to the Plugin Index (see Section 7).
+This is the manifest file that lives inside your plugin directory and drives runtime behavior. It is distinct from the index manifest (`index.yaml`) used when publishing to the Plugin Index (see Section 7).
 
 ```yaml
+name: my_plugin              # required for community plugins (^[a-z0-9_]+$, must match dir name)
 title: My Plugin
 description: What this plugin does.
 version: 1.0.0
@@ -61,6 +62,7 @@ always_enabled: false
 ```
 
 Field reference:
+- `name`: Plugin identifier. Required by CI when submitting to the Plugin Index. Must be `^[a-z0-9_]+$` and match the index folder name exactly.
 - `title`: UI display name
 - `description`: Short plugin summary
 - `version`: Plugin version string
@@ -200,12 +202,13 @@ embedding:
 
 The **Plugin Index** is a community-maintained repository at https://github.com/agent0ai/a0-plugins that lists plugins available to the Agent Zero community. Plugins listed there can be discovered and installed by other users.
 
-### Two Distinct plugin.yaml Files
+### Two Distinct Manifest Files
 
-There are two completely different `plugin.yaml` schemas used at different stages. They must not be confused:
+There are two completely different manifest files used at different stages. They must not be confused:
 
-**Runtime manifest** (inside your plugin repo/directory, drives Agent Zero behavior):
+**Runtime manifest** (`plugin.yaml`, inside your plugin repo/directory — drives Agent Zero behavior):
 ```yaml
+name: my_plugin              # REQUIRED for index submission; must match index folder name
 title: My Plugin
 description: What this plugin does.
 version: 1.0.0
@@ -216,17 +219,19 @@ per_agent_config: false
 always_enabled: false
 ```
 
-**Index manifest** (submitted to the `a0-plugins` repo under `plugins/<your-plugin-name>/`, drives discoverability only):
+**Index manifest** (`index.yaml`, submitted to the `a0-plugins` repo under `plugins/<your_plugin_name>/` — drives discoverability only):
 ```yaml
 title: My Plugin
 description: What this plugin does.
 github: https://github.com/yourname/your-plugin-repo
 tags:
   - tools
   - example
+screenshots:                    # optional, up to 5 full image URLs
+  - https://raw.githubusercontent.com/yourname/your-plugin-repo/main/docs/screen.png
 ```
 
-The index manifest contains only four fields (`title`, `description`, `github`, `tags`) and must not include runtime fields. The `github` field must point to the root of a GitHub repository that itself contains a runtime `plugin.yaml` at the repository root.
+The index manifest is named `index.yaml` (not `plugin.yaml`). Required fields: `title`, `description`, `github`. Optional: `tags` (up to 5), `screenshots` (up to 5 URLs). The `github` field must point to the root of a GitHub repository that contains a runtime `plugin.yaml` at the repository root, and that `plugin.yaml` must include a `name` field matching the index folder name exactly.
 
 ### Repository Structure for Community Plugins
 
@@ -248,19 +253,22 @@ Users install it locally by cloning (or downloading) the repo contents into `/a0
 
 ### Submitting to the Plugin Index
 
-1. Create a GitHub repository for your plugin with the runtime `plugin.yaml` at the repo root.
+1. Create a GitHub repository for your plugin with the runtime `plugin.yaml` (including the `name` field) at the repo root.
 2. Fork `https://github.com/agent0ai/a0-plugins`.
-3. Create a folder `plugins/<your-plugin-name>/` containing only an index `plugin.yaml` (and optionally a square thumbnail image ≤ 20 KB).
+3. Create a folder `plugins/<your_plugin_name>/` containing only an `index.yaml` (and optionally a square thumbnail image ≤ 20 KB).
 4. Open a Pull Request with exactly one new plugin folder.
 5. CI validates the submission automatically. A maintainer reviews and merges.
 
 Index submission rules:
 - One plugin per PR
-- Folder name must be unique, stable, lowercase, kebab-case
+- Folder name: unique, stable, `^[a-z0-9_]+$` (lowercase, numbers, underscores — no hyphens)
+- Folder name must exactly match the `name` field in your remote `plugin.yaml`
 - Folders starting with `_` are reserved for internal use
-- `github` must point to a public repo that contains `plugin.yaml` at its root
+- `github` must point to a public repo that contains `plugin.yaml` at its root with a matching `name` field
 - `title` max 50 characters, `description` max 500 characters
+- `index.yaml` total max 2000 characters
 - `tags`: optional, up to 5, use recommended tags from https://github.com/agent0ai/a0-plugins/blob/main/TAGS.md
+- `screenshots`: optional, up to 5 full image URLs (png/jpg/webp, each ≤ 2 MB)
 
 ### Plugin Marketplace
 

docs/developer/plugins.md

@@ -24,6 +24,7 @@ On name collisions, user plugins take precedence.
 Every plugin must contain `plugin.yaml`. This is the **runtime manifest** — it drives Agent Zero behavior. It is distinct from the index manifest used when publishing to the Plugin Index (see [Publishing to the Plugin Index](#publishing-to-the-plugin-index) below).
 
 ```yaml
+name: my_plugin              # required for community plugins (^[a-z0-9_]+$, must match dir name)
 title: My Plugin
 description: What this plugin does.
 version: 1.0.0
@@ -36,6 +37,7 @@ always_enabled: false
 
 Field reference:
 
+- `name`: plugin identifier; required by CI for index submission; must be `^[a-z0-9_]+$` and match the index folder name exactly
 - `title`: UI display name
 - `description`: short plugin summary
 - `version`: plugin version string
@@ -189,12 +191,13 @@ Supported actions:
 
 The **Plugin Index** is a community-maintained repository at https://github.com/agent0ai/a0-plugins. Plugins listed there are discoverable by all Agent Zero users.
 
-### Two Distinct plugin.yaml Files
+### Two Distinct Manifest Files
 
-There are two completely different `plugin.yaml` schemas — they must not be confused:
+There are two completely different manifest files — they must not be confused:
 
-**Runtime manifest** (inside your plugin's own repo, drives Agent Zero behavior):
+**Runtime manifest** (`plugin.yaml`, inside your plugin's own repo — drives Agent Zero behavior):
 ```yaml
+name: my_plugin              # REQUIRED for index submission; must match index folder name
 title: My Plugin
 description: What this plugin does.
 version: 1.0.0
@@ -205,25 +208,27 @@ per_agent_config: false
 always_enabled: false
 ```
 
-**Index manifest** (submitted to `a0-plugins` under `plugins/<your-plugin-name>/`, drives discoverability only):
+**Index manifest** (`index.yaml`, submitted to `a0-plugins` under `plugins/<your_plugin_name>/` — drives discoverability only):
 ```yaml
 title: My Plugin
 description: What this plugin does.
 github: https://github.com/yourname/your-plugin-repo
 tags:
   - tools
   - example
+screenshots:                    # optional, up to 5 full image URLs
+  - https://raw.githubusercontent.com/yourname/your-plugin-repo/main/docs/screen.png
 ```
 
-The index manifest has only four fields (`title`, `description`, `github`, `tags`). The `github` URL must point to a public GitHub repository that contains a runtime `plugin.yaml` at the **repository root**.
+The index manifest file is named `index.yaml` (not `plugin.yaml`). Required fields: `title`, `description`, `github`. Optional: `tags` (up to 5), `screenshots` (up to 5 URLs). The `github` URL must point to a public GitHub repository that contains a runtime `plugin.yaml` at the **repository root**, and that `plugin.yaml` must include a `name` field matching the index folder name exactly.
 
 ### Repository Structure for Community Plugins
 
 Plugin repos should expose the plugin contents at the repo root, so they can be cloned directly into `usr/plugins/<name>/`:
 
 ```text
 your-plugin-repo/          ← GitHub repository root
-├── plugin.yaml            ← runtime manifest
+├── plugin.yaml            ← runtime manifest (must include name field)
 ├── default_config.yaml
 ├── README.md
 ├── LICENSE
@@ -235,18 +240,21 @@ your-plugin-repo/          ← GitHub repository root
 
 ### Submission Process
 
-1. Create a GitHub repository with the runtime `plugin.yaml` at the repo root.
+1. Create a GitHub repository with the runtime `plugin.yaml` (including the `name` field) at the repo root.
 2. Fork `https://github.com/agent0ai/a0-plugins`.
-3. Add `plugins/<your-plugin-name>/plugin.yaml` (index manifest) to your fork, and optionally a square thumbnail image (≤ 20 KB, named `thumbnail.png|jpg|webp`).
+3. Create folder `plugins/<your_plugin_name>/` and add `index.yaml` (the index manifest, not `plugin.yaml`). Optionally add a square thumbnail image (≤ 20 KB, named `thumbnail.png|jpg|webp`).
 4. Open a Pull Request. One PR must add exactly one new plugin folder.
 5. CI validates automatically. A maintainer reviews and merges.
 
 Submission rules:
-- Folder name: unique, stable, lowercase, kebab-case
+- Folder name: unique, stable, `^[a-z0-9_]+$` (lowercase, numbers, underscores — no hyphens)
+- Folder name must exactly match the `name` field in your remote `plugin.yaml`
 - Folders starting with `_` are reserved for internal use
 - `title`: max 50 characters
 - `description`: max 500 characters
+- `index.yaml` total: max 2000 characters
 - `tags`: optional, up to 5, see https://github.com/agent0ai/a0-plugins/blob/main/TAGS.md
+- `screenshots`: optional, up to 5 full image URLs (png/jpg/webp, each ≤ 2 MB)
 
 ### Plugin Marketplace
 

plugins/README.md

@@ -68,8 +68,8 @@ The **Plugin Index** at https://github.com/agent0ai/a0-plugins is the community-
 
 To share a plugin with the community:
 
-1. Create a standalone GitHub repository with the plugin contents at the repo root and the runtime `plugin.yaml` there.
-2. Fork `https://github.com/agent0ai/a0-plugins` and add a folder `plugins/<your-plugin-name>/` containing a separate index `plugin.yaml`:
+1. Create a standalone GitHub repository with the plugin contents at the repo root. The runtime `plugin.yaml` must include a `name` field matching the intended index folder name.
+2. Fork `https://github.com/agent0ai/a0-plugins` and add a folder `plugins/<your_plugin_name>/` containing a separate index manifest named `index.yaml` (not `plugin.yaml`):
 
 ```yaml
 title: My Plugin
@@ -79,9 +79,11 @@ tags:
   - tools
 ```
 
+Optional additional fields: `screenshots` (up to 5 image URLs).
+
 3. Open a Pull Request. CI validates the submission; a maintainer reviews and merges.
 
-Note: The index `plugin.yaml` is a **different schema** from the runtime manifest — it contains only `title`, `description`, `github`, and optional `tags`. Do not mix them up.
+Note: The index `index.yaml` is a **different file with a different schema** from the runtime `plugin.yaml`. Folder names use `^[a-z0-9_]+$` (underscores, no hyphens) and must match the `name` field in the remote `plugin.yaml` exactly.
 
 ## Plugin Marketplace
 

plugins/_plugin_scan/api/plugin_scan_run.py

@@ -0,0 +1,41 @@
+from agent import AgentContext, UserMessage
+from helpers.api import ApiHandler, Input, Output, Request, Response
+from helpers import guids, message_queue as mq
+from plugins._plugin_scan.helpers.prompt import build_prompt
+
+
+class PluginScanRun(ApiHandler):
+    """
+    POST /api/plugins/_plugin_scan/plugin_scan_run
+    Body:    { "git_url": "https://github.com/...", "checks": [...] }  # checks optional, defaults to all
+    Returns: { "ok": true, "verdict": "safe|caution|dangerous|unknown", "report": "<markdown>" }
+
+    Combines plugin_scan_queue + plugin_scan_start into one synchronous call and awaits the result.
+    No server-side timeout - set an appropriate client-side timeout (repos can take 5+ min to scan).
+    """
+
+    async def process(self, input: Input, request: Request) -> Output:
+        git_url: str = input.get("git_url", "").strip()
+        if not git_url:
+            return Response("Missing 'git_url'.", 400)
+
+        ctxid = guids.generate_id()
+        try:
+            context = self.use_context(ctxid)
+            prompt = build_prompt(git_url, input.get("checks"))
+            mq.log_user_message(context, prompt, [])
+            task = context.communicate(UserMessage(prompt, []))
+            report: str = await task.result()
+        except Exception as e:
+            return Response(f"Scan failed: {e}", 500)
+        finally:
+            try:
+                AgentContext.remove(ctxid)
+            except Exception:
+                pass
+
+        return {
+            "ok": True,
+            "git_url": git_url,
+            "report": report or "",
+        }

plugins/_plugin_scan/helpers/__init__.py

@@ -0,0 +1,30 @@
+import json
+from pathlib import Path
+
+_DIR  = Path(__file__).parent.parent
+_CFG  = json.loads((_DIR / "webui" / "plugin-scan-checks.json").read_text())
+_TMPL = (_DIR / "webui" / "plugin-scan-prompt.md").read_text()
+
+
+def build_prompt(git_url: str, checks: list | None = None) -> str:
+    ratings, all_checks = _CFG["ratings"], _CFG["checks"]
+    keys = [k for k in (checks or all_checks) if k in all_checks]
+
+    subs = {
+        "GIT_URL": git_url,
+        "SELECTED_CHECKS": "\n".join(f"- **{all_checks[k]['label']}**" for k in keys),
+        "CHECK_DETAILS": "\n\n".join(
+            f"#### {c['label']}\n{c['detail']}\n\nCriteria:\n"
+            + "\n".join(f"  - {ratings[l]['icon']} {d}" for l, d in c["criteria"].items())
+            for c in (all_checks[k] for k in keys)
+        ),
+        "STATUS_LEGEND": "\n".join(f"- {r['icon']} **{r['label']}**" for r in ratings.values()),
+        "RATING_ICONS":   "/".join(r["icon"] for r in ratings.values()),
+        "RATING_PASS":    ratings["pass"]["icon"],
+        "RATING_WARNING": ratings["warning"]["icon"],
+        "RATING_FAIL":    ratings["fail"]["icon"],
+    }
+    prompt = _TMPL
+    for key, val in subs.items():
+        prompt = prompt.replace(f"{{{{{key}}}}}", val)
+    return prompt

plugins/_plugin_scan/helpers/prompt.py

@@ -41,7 +41,7 @@ Verify all of the following. If any is false, go back and fix it:
 
 ## Output Format
 
-Your ENTIRE response must be a single markdown document with EXACTLY this structure. No preamble, no commentary, no extra sections. Start your response directly with the `#` heading.
+Submit your final report using the **`response` tool**. The `text` argument must be a single markdown document with EXACTLY this structure. No preamble, no commentary, no extra sections. Start your response directly with the `#` heading.
 
 **Section 1** — Title line: `# 🛡️ Security Scan Report: {plugin title}`
 
@@ -65,7 +65,7 @@ Status icons: {{STATUS_LEGEND}}
 
 ## Constraints
 
-- Do NOT output any text before the `#` title heading
+- The `text` argument of the `response` tool must start directly with the `#` title heading — no text before it
 - Do NOT include your internal analysis process in the report
 - Do NOT add checks beyond the list above
 - Do NOT summarize multiple files into one finding