fix(apps): preserve legacy CLI app skills

docs/architecture.md

@@ -202,7 +202,7 @@ When changing tools, channels, file access, WebUI workspace behavior, or network
 | Channel | Export a `ChannelPlugin` descriptor, keep its runtime and optional setup surfaces in one package, and follow [`channel-package-guide.md`](./channel-package-guide.md) |
 | Tool | Implement a tool under `agent/tools/` or expose a plugin entry point |
 | MCP | Add `tools.mcpServers` config |
-| Skill | Add workspace skill files under `<workspace>/skills/` or built-in skills under `nanobot/skills/` |
+| Skill | Add workspace skills under `<workspace>/skills/`, Agent Plugins v1 under `<workspace>/plugins/`, or built-in skills under `nanobot/skills/` |
 
 Prefer existing registry/discovery patterns over ad hoc wiring.
 

docs/configuration.md

@@ -2306,6 +2306,36 @@ Disabled skills are excluded from the main agent's skill summary, from always-on
 |--------|---------|-------------|
 | `agents.defaults.disabledSkills` | `[]` | List of skill directory names to exclude from loading. Applies to both built-in skills and workspace skills. |
 
+### Agent Plugins v1 skills
+
+nanobot also discovers portable [Agent Plugins](https://agent-plugins.org/) placed under
+`<workspace>/plugins/<plugin>/`. A supported package has a root `plugin.json` that targets
+Agent Plugins v1 and one or more direct-child skills:
+
+```text
+plugins/
+└── release-tools/
+    ├── plugin.json
+    └── skills/
+        └── release-notes/
+            └── SKILL.md
+```
+
+Plugin skills use the same progressive loading and `$skill-name` invocation as workspace
+skills. A workspace skill wins when it has the same name as a plugin skill; plugin skills win
+over built-in skills. Invalid manifests, invalid Agent Skills, nested skill directories, and
+paths that resolve outside the plugin root are ignored.
+
+This initial compatibility layer loads the portable `skills/` component only. Agent Plugins
+`mcp.json` is not started automatically: local MCP servers execute third-party processes and
+need an explicit trust and approval flow. Configure a reviewed MCP server through **Apps** or
+`tools.mcpServers` for now.
+
+CLI Apps installed from the WebUI use the same package layout. nanobot installs the CLI through
+its catalog adapter, then writes a skills-only Agent Plugin under `<workspace>/plugins/`; updates
+refresh that package and uninstall removes it. The external executable remains managed by the
+CLI Apps installer rather than by the Agent Plugins manifest.
+
 ## Tool Hint Max Length
 
 Tool hints are the short progress messages shown when the agent calls tools (e.g. `$ cd …/project && npm test`). By default, these are truncated at 40 characters, which can make long commands hard to read.

nanobot/agent/agent_plugins.py

@@ -0,0 +1,210 @@
+"""Discover portable Agent Plugins from the agent workspace."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+from loguru import logger
+
+AGENT_PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"
+
+_PLUGIN_NAME = re.compile(r"^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$")
+_SKILL_NAME = re.compile(r"^(?!.*--)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$")
+_SKILL_FRONTMATTER = re.compile(r"^---\s*\r?\n(.*?)\r?\n---\s*\r?\n?", re.DOTALL)
+_MANIFEST_FIELDS = {
+    "$schema",
+    "name",
+    "version",
+    "description",
+    "author",
+    "homepage",
+    "repository",
+    "license",
+    "keywords",
+    "extensions",
+}
+_STRING_FIELDS = {"version", "description", "homepage", "repository", "license"}
+_AUTHOR_FIELDS = {"name", "email", "url"}
+
+
+@dataclass(frozen=True)
+class AgentPluginSkill:
+    """One skill supplied by a valid Agent Plugins v1 package."""
+
+    name: str
+    path: Path
+    plugin: str
+
+
+def discover_agent_plugin_skills(workspace: Path) -> list[AgentPluginSkill]:
+    """Discover direct-child skills under ``<workspace>/plugins/*``.
+
+    Agent Plugins does not prescribe an install location. nanobot uses the
+    workspace ``plugins`` directory so packages stay explicit and portable
+    with the rest of the agent workspace.
+    """
+    workspace = workspace.expanduser().resolve()
+    plugins_root = workspace / "plugins"
+    if not plugins_root.is_dir():
+        return []
+    try:
+        resolved_plugins_root = plugins_root.resolve(strict=True)
+    except OSError:
+        return []
+    if not resolved_plugins_root.is_relative_to(workspace):
+        logger.warning("Ignoring Agent Plugins directory outside the workspace")
+        return []
+
+    try:
+        candidates = sorted(plugins_root.iterdir(), key=lambda path: path.name)
+    except OSError as exc:
+        logger.warning("Could not inspect Agent Plugins directory: {}", exc)
+        return []
+
+    skills: list[AgentPluginSkill] = []
+    for candidate in candidates:
+        plugin_root = _contained_directory(candidate, resolved_plugins_root)
+        if plugin_root is None:
+            continue
+        plugin_name = _load_manifest_name(plugin_root)
+        if plugin_name is None:
+            continue
+        skills.extend(_discover_plugin_skills(plugin_name, plugin_root))
+    return skills
+
+
+def _load_manifest_name(plugin_root: Path) -> str | None:
+    manifest = _contained_file(plugin_root / "plugin.json", plugin_root)
+    if manifest is None:
+        return None
+    try:
+        value = cast(object, json.loads(manifest.read_text(encoding="utf-8")))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        logger.warning("Ignoring invalid Agent Plugin manifest '{}': {}", manifest, exc)
+        return None
+    if not isinstance(value, dict):
+        logger.warning("Ignoring Agent Plugin manifest '{}': expected a JSON object", manifest)
+        return None
+
+    payload = cast(dict[str, Any], value)
+    if payload.get("$schema") != AGENT_PLUGIN_SCHEMA:
+        return None
+    name = payload.get("name")
+    if (
+        not isinstance(name, str)
+        or len(name) > 64
+        or _PLUGIN_NAME.fullmatch(name) is None
+    ):
+        logger.warning("Ignoring Agent Plugin manifest '{}': invalid name", manifest)
+        return None
+    if not _valid_optional_fields(payload):
+        logger.warning("Ignoring Agent Plugin manifest '{}': invalid metadata", manifest)
+        return None
+
+    for field in payload.keys() - _MANIFEST_FIELDS:
+        logger.warning("Ignoring unknown Agent Plugin manifest field '{}' in '{}'", field, manifest)
+    if "extensions" in payload and not isinstance(payload["extensions"], dict):
+        logger.warning("Ignoring non-object Agent Plugin extensions in '{}'", manifest)
+    return name
+
+
+def _valid_optional_fields(payload: dict[str, Any]) -> bool:
+    if any(field in payload and not isinstance(payload[field], str) for field in _STRING_FIELDS):
+        return False
+    keywords = payload.get("keywords")
+    if "keywords" in payload and (
+        not isinstance(keywords, list)
+        or not all(isinstance(keyword, str) for keyword in cast(list[object], keywords))
+    ):
+        return False
+    author = payload.get("author")
+    if "author" not in payload:
+        return True
+    if not isinstance(author, dict):
+        return False
+    author_payload = cast(dict[str, object], author)
+    return not (author_payload.keys() - _AUTHOR_FIELDS) and all(
+        isinstance(value, str) for value in author_payload.values()
+    )
+
+
+def _discover_plugin_skills(plugin_name: str, plugin_root: Path) -> list[AgentPluginSkill]:
+    skills_root = plugin_root / "skills"
+    if not skills_root.exists():
+        return []
+    resolved_skills_root = _contained_directory(skills_root, plugin_root)
+    if resolved_skills_root is None:
+        logger.warning("Ignoring invalid skills component in Agent Plugin '{}'", plugin_name)
+        return []
+
+    try:
+        candidates = sorted(skills_root.iterdir(), key=lambda path: path.name)
+    except OSError as exc:
+        logger.warning("Could not inspect Agent Plugin '{}' skills: {}", plugin_name, exc)
+        return []
+
+    skills: list[AgentPluginSkill] = []
+    for candidate in candidates:
+        skill_root = _contained_directory(candidate, resolved_skills_root)
+        if skill_root is None:
+            continue
+        skill_file = _contained_file(skill_root / "SKILL.md", plugin_root)
+        if skill_file is None or not _valid_skill(skill_file, candidate.name, plugin_name):
+            continue
+        skills.append(
+            AgentPluginSkill(name=candidate.name, path=skill_file, plugin=plugin_name)
+        )
+    return skills
+
+
+def _valid_skill(path: Path, directory_name: str, plugin_name: str) -> bool:
+    try:
+        content = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError):
+        return False
+    match = _SKILL_FRONTMATTER.match(content)
+    if match is None:
+        logger.warning("Ignoring Agent Plugin '{}' skill '{}': invalid frontmatter", plugin_name, directory_name)
+        return False
+    try:
+        metadata = cast(object, yaml.safe_load(match.group(1)))
+    except yaml.YAMLError:
+        metadata = None
+    if not isinstance(metadata, dict):
+        logger.warning("Ignoring Agent Plugin '{}' skill '{}': invalid frontmatter", plugin_name, directory_name)
+        return False
+    payload = cast(dict[object, object], metadata)
+    name = payload.get("name")
+    description = payload.get("description")
+    valid = (
+        name == directory_name
+        and isinstance(name, str)
+        and len(name) <= 64
+        and _SKILL_NAME.fullmatch(name) is not None
+        and isinstance(description, str)
+        and 1 <= len(description.strip()) <= 1024
+    )
+    if not valid:
+        logger.warning("Ignoring Agent Plugin '{}' skill '{}': invalid metadata", plugin_name, directory_name)
+    return valid
+
+
+def _contained_directory(path: Path, root: Path) -> Path | None:
+    try:
+        resolved = path.resolve(strict=True)
+    except OSError:
+        return None
+    return resolved if resolved.is_dir() and resolved.is_relative_to(root) else None
+
+
+def _contained_file(path: Path, root: Path) -> Path | None:
+    try:
+        resolved = path.resolve(strict=True)
+    except OSError:
+        return None
+    return resolved if resolved.is_file() and resolved.is_relative_to(root) else None

nanobot/agent/skills.py

@@ -9,6 +9,8 @@ from typing import Any, cast
 
 import yaml
 
+from nanobot.agent.agent_plugins import discover_agent_plugin_skills
+
 # Default builtin skills directory (relative to this file)
 BUILTIN_SKILLS_DIR = Path(__file__).parent.parent / "skills"
 
@@ -33,6 +35,7 @@ class SkillsLoader:
         self.workspace_skills = workspace / "skills"
         self.builtin_skills = builtin_skills_dir or BUILTIN_SKILLS_DIR
         self.disabled_skills = disabled_skills or set()
+        self.plugin_skills = discover_agent_plugin_skills(workspace)
 
     def _skill_entries_from_dir(self, base: Path, source: str, *, skip_names: set[str] | None = None) -> list[dict[str, str]]:
         if not base.exists():
@@ -60,11 +63,24 @@ class SkillsLoader:
         Returns:
             List of skill info dicts with 'name', 'path', 'source'.
         """
+        self.plugin_skills = discover_agent_plugin_skills(self.workspace)
         skills = self._skill_entries_from_dir(self.workspace_skills, "workspace")
-        workspace_names = {entry["name"] for entry in skills}
+        seen_names = {entry["name"] for entry in skills}
+        for plugin_skill in self.plugin_skills:
+            if plugin_skill.name in seen_names:
+                continue
+            skills.append(
+                {
+                    "name": plugin_skill.name,
+                    "path": str(plugin_skill.path),
+                    "source": "plugin",
+                    "plugin": plugin_skill.plugin,
+                }
+            )
+            seen_names.add(plugin_skill.name)
         if self.builtin_skills and self.builtin_skills.exists():
             skills.extend(
-                self._skill_entries_from_dir(self.builtin_skills, "builtin", skip_names=workspace_names)
+                self._skill_entries_from_dir(self.builtin_skills, "builtin", skip_names=seen_names)
             )
 
         if self.disabled_skills:
@@ -84,13 +100,16 @@ class SkillsLoader:
         Returns:
             Skill content or None if not found.
         """
-        roots = [self.workspace_skills]
+        workspace_path = self.workspace_skills / name / "SKILL.md"
+        if workspace_path.exists():
+            return workspace_path.read_text(encoding="utf-8")
+        for plugin_skill in self.plugin_skills:
+            if plugin_skill.name == name:
+                return plugin_skill.path.read_text(encoding="utf-8")
         if self.builtin_skills:
-            roots.append(self.builtin_skills)
-        for root in roots:
-            path = root / name / "SKILL.md"
-            if path.exists():
-                return path.read_text(encoding="utf-8")
+            builtin_path = self.builtin_skills / name / "SKILL.md"
+            if builtin_path.exists():
+                return builtin_path.read_text(encoding="utf-8")
         return None
 
     def load_skills_for_context(self, skill_names: list[str]) -> str:
@@ -145,6 +164,7 @@ class SkillsLoader:
         sections: list[str] = []
         groups = (
             ("Workspace skills", "workspace", self.workspace_skills),
+            ("Agent Plugin skills", "plugin", self.workspace / "plugins"),
             ("Built-in skills", "builtin", self.builtin_skills),
         )
         for label, source, root in groups:

nanobot/apps/cli/service.py

@@ -18,6 +18,7 @@ from typing import Any, cast
 from urllib.parse import urlparse
 
 import httpx
+import yaml
 from loguru import logger
 
 from nanobot.apps.protocol import app_manifest, compact_dict
@@ -27,6 +28,7 @@ from nanobot.security.workspace_policy import is_path_within
 CLI_ANYTHING_REGISTRY_URL = "https://hkuds.github.io/CLI-Anything/registry.json"
 CLI_ANYTHING_PUBLIC_REGISTRY_URL = "https://hkuds.github.io/CLI-Anything/public_registry.json"
 CLI_ANYTHING_RAW_BASE = "https://raw.githubusercontent.com/HKUDS/CLI-Anything/main"
+AGENT_PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"
 NANOBOT_EXTENSION_REGISTRY_URL = "https://raw.githubusercontent.com/Re-bin/nanobot-extension/main/registry.json"
 NANOBOT_EXTENSION_RAW_BASE = "https://raw.githubusercontent.com/Re-bin/nanobot-extension/main"
 _CATALOG_SOURCES = (
@@ -41,6 +43,8 @@ _MAX_ARTIFACT_REPORT = 12
 _SAFE_NAME_RE = re.compile(r"[^a-z0-9_-]+")
 _SAFE_NPM_DIR_RE = re.compile(r"^[a-z0-9._-]+$", re.IGNORECASE)
 _MENTION_RE = re.compile(r"(^|[\s([{])@([a-z0-9_-]+)\b", re.IGNORECASE)
+_SKILL_FRONTMATTER_RE = re.compile(r"^---\s*\r?\n(.*?)\r?\n---\s*\r?\n?", re.DOTALL)
+_SKILL_NAME_LINE_RE = re.compile(r"^name\s*:.*$", re.MULTILINE)
 _SHELL_META_CHARS = ("|", "&&", "||", ";", "$(", "`", ">", "<")
 _ENDORSEMENT_WORD_RE = re.compile(r"\bofficial\s+", re.IGNORECASE)
 _ARTIFACT_EXTENSIONS = frozenset({
@@ -211,10 +215,21 @@ def _as_object_dict(value: object) -> dict[str, Any] | None:
 
 
 def _safe_skill_name(name: str) -> str:
+    clean = _SAFE_NAME_RE.sub("-", name.lower()).replace("_", "-").strip("-")
+    return f"cli-app-{clean or 'app'}"
+
+
+def _legacy_skill_name(name: str) -> str:
+    """Return the workspace skill name emitted before Agent Plugins support."""
     clean = _SAFE_NAME_RE.sub("-", name.lower()).strip("-")
     return f"cli-app-{clean or 'app'}"
 
 
+def _plugin_skill_relative_path(name: str) -> str:
+    skill_name = _safe_skill_name(name)
+    return f"plugins/{skill_name}/skills/{skill_name}/SKILL.md"
+
+
 def _has_shell_meta(command: str) -> bool:
     return any(char in command for char in _SHELL_META_CHARS)
 
@@ -613,7 +628,7 @@ class CliAppManager:
                     "name": installed_name,
                     "entry_point": entry_point,
                     "source": str(data.get("source") or ""),
-                    "skill": f"skills/{_safe_skill_name(installed_name)}/SKILL.md",
+                    "skill": self.skill_relative_path(installed_name),
                     "tool": "run_cli_app",
                 }
             )
@@ -640,7 +655,20 @@ class CliAppManager:
         return not _has_shell_meta(install_cmd)
 
     def _skill_path(self, name: str) -> Path:
-        return self.workspace / "skills" / _safe_skill_name(name) / "SKILL.md"
+        skill_name = _safe_skill_name(name)
+        return self.workspace / "plugins" / skill_name / "skills" / skill_name / "SKILL.md"
+
+    def _legacy_skill_path(self, name: str) -> Path:
+        return self.workspace / "skills" / _legacy_skill_name(name) / "SKILL.md"
+
+    def _installed_skill_path(self, name: str) -> Path:
+        path = self._skill_path(name)
+        legacy_path = self._legacy_skill_path(name)
+        return legacy_path if not path.is_file() and legacy_path.is_file() else path
+
+    def skill_relative_path(self, name: str) -> str:
+        """Return the existing skill path, falling back to the canonical plugin path."""
+        return self._installed_skill_path(name).relative_to(self.workspace).as_posix()
 
     def _app_payload(
         self,
@@ -677,7 +705,7 @@ class CliAppManager:
             "status": status,
             "logo_url": logo_url,
             "brand_color": brand_color,
-            "skill_installed": self._skill_path(name).is_file(),
+            "skill_installed": self._installed_skill_path(name).is_file(),
             "manifest": self._manifest_payload(app, logo_url=logo_url, brand_color=brand_color),
         }
 
@@ -713,7 +741,8 @@ class CliAppManager:
         name = str(app["name"])
         entry_point = str(app.get("entry_point") or "")
         strategy = self._strategy(app)
-        skill_path = f"skills/{_safe_skill_name(name)}/SKILL.md"
+        skill_path = _plugin_skill_relative_path(name)
+        plugin_path = f"plugins/{_safe_skill_name(name)}"
         capabilities = [
             compact_dict({
                 "type": "cli",
@@ -726,13 +755,13 @@ class CliAppManager:
         install = compact_dict({
             "supported": install_supported,
             "strategy": strategy,
-            "managed_paths": [skill_path],
+            "managed_paths": [plugin_path],
             "verification": ["entry_point_available"] if entry_point else [],
         })
         remove = compact_dict({
             "supported": strategy != "unsupported",
             "strategy": strategy,
-            "managed_paths": [skill_path],
+            "managed_paths": [plugin_path],
             "verification": (
                 ["package_manager_ok", "entry_point_absent", "managed_paths_absent"]
                 if strategy not in {"bundled", "unsupported"}
@@ -1032,11 +1061,10 @@ class CliAppManager:
         name = str(app.get("name") or "unknown")
         display = str(app.get("display_name") or name)
         entry = str(app.get("entry_point") or f"cli-anything-{name}")
-        description = _catalog_description(app) or f"Use {display} from nanobot."
+        description = (_catalog_description(app) or f"Use {display} from nanobot.")[:1024]
         return f"""---
 name: {_safe_skill_name(name)}
-description: >-
-  {description}
+description: {json.dumps(description, ensure_ascii=False)}
 ---
 
 # {display}
@@ -1072,18 +1100,53 @@ Use the `run_cli_app` tool with `name="{name}"` for command execution. Do not in
                     return "".join(lines[: index + 1]) + "\n" + note + "\n" + "".join(lines[index + 1 :])
         return note + "\n" + content
 
+    def _normalise_skill(self, content: str, app: dict[str, Any]) -> str:
+        """Give a catalog skill the identity required by its plugin directory."""
+        match = _SKILL_FRONTMATTER_RE.match(content)
+        if match is None:
+            return self._fallback_skill(app)
+        try:
+            metadata = _as_object_dict(cast(object, yaml.safe_load(match.group(1))))
+        except yaml.YAMLError:
+            return self._fallback_skill(app)
+        description = metadata.get("description") if metadata is not None else None
+        if not isinstance(description, str) or not 1 <= len(description.strip()) <= 1024:
+            return self._fallback_skill(app)
+
+        name = _safe_skill_name(str(app["name"]))
+        frontmatter, replaced = _SKILL_NAME_LINE_RE.subn(f"name: {name}", match.group(1), count=1)
+        if not replaced:
+            frontmatter = f"name: {name}\n{frontmatter}"
+        body = content[match.end():].lstrip()
+        return f"---\n{frontmatter.strip()}\n---\n\n{body}"
+
     def install_skill(self, app: dict[str, Any]) -> Path:
         path = self._skill_path(str(app["name"]))
         path.parent.mkdir(parents=True, exist_ok=True)
         content = self._fetch_skill_content(app) or self._fallback_skill(app)
+        content = self._normalise_skill(content, app)
         content = self._with_nanobot_skill_note(content, app)
         path.write_text(content, encoding="utf-8")
+        plugin_root = path.parents[2]
+        manifest = compact_dict({
+            "$schema": AGENT_PLUGIN_SCHEMA,
+            "name": _safe_skill_name(str(app["name"])),
+            "version": str(app.get("version") or ""),
+            "description": _catalog_description(app),
+        })
+        _write_json(plugin_root / "plugin.json", manifest)
+        legacy_dir = self._legacy_skill_path(str(app["name"])).parent
+        if legacy_dir.is_dir():
+            shutil.rmtree(legacy_dir)
         return path
 
     def remove_skill(self, name: str) -> None:
-        skill_dir = self._skill_path(name).parent
-        if skill_dir.is_dir():
-            shutil.rmtree(skill_dir)
+        plugin_root = self._skill_path(name).parents[2]
+        if plugin_root.is_dir():
+            shutil.rmtree(plugin_root)
+        legacy_dir = self._legacy_skill_path(name).parent
+        if legacy_dir.is_dir():
+            shutil.rmtree(legacy_dir)
 
     def _record_installed(self, app: dict[str, Any]) -> dict[str, Any]:
         installed = self._load_installed()

nanobot/apps/cli/utils.py

@@ -29,6 +29,9 @@ def runtime_lines_for_request(
     """Return CLI App annotations from an immutable request snapshot."""
     structured = metadata.get("cli_apps") if isinstance(metadata, Mapping) else None
     if isinstance(structured, list):
+        from nanobot.apps.cli import CliAppManager
+
+        manager = CliAppManager(workspace=workspace)
         structured_items = cast(list[Any], structured)
         mentions = [
             cast(Mapping[str, Any], item) for item in structured_items
@@ -41,7 +44,7 @@ def runtime_lines_for_request(
                 f"@{str(item['name']).strip().lower()} "
                 f"(installed; tool=run_cli_app; "
                 f"entry_point={str(item.get('entry_point') or 'unknown')}; "
-                f"skill=skills/cli-app-{str(item['name']).strip().lower()}/SKILL.md). "
+                f"skill={manager.skill_relative_path(str(item['name']))}). "
                 "Read the skill when useful, then run this app with `run_cli_app`; do not bypass it with shell."
                 for item in mentions
                 if str(item.get("name") or "").strip()

tests/agent/test_agent_plugins.py

@@ -0,0 +1,172 @@
+import json
+import shutil
+from pathlib import Path
+
+import pytest
+
+from nanobot.agent.agent_plugins import AGENT_PLUGIN_SCHEMA, discover_agent_plugin_skills
+from nanobot.agent.skills import SkillsLoader
+
+
+def _write_skill(root: Path, name: str, *, description: str = "Plugin skill.") -> Path:
+    skill = root / "skills" / name
+    skill.mkdir(parents=True)
+    (skill / "SKILL.md").write_text(
+        f"---\nname: {name}\ndescription: {description}\n---\n\n# {name}\n",
+        encoding="utf-8",
+    )
+    return skill
+
+
+def _write_plugin(
+    workspace: Path,
+    directory: str,
+    *,
+    name: str | None = None,
+    manifest: dict[str, object] | None = None,
+) -> Path:
+    root = workspace / "plugins" / directory
+    root.mkdir(parents=True)
+    payload = manifest or {
+        "$schema": AGENT_PLUGIN_SCHEMA,
+        "name": name or directory,
+    }
+    (root / "plugin.json").write_text(json.dumps(payload), encoding="utf-8")
+    return root
+
+
+def test_skills_loader_discovers_agent_plugin_skill(tmp_path: Path) -> None:
+    plugin = _write_plugin(tmp_path, "acme-tools")
+    _write_skill(plugin, "release-notes", description="Draft release notes from changes.")
+
+    loader = SkillsLoader(tmp_path, builtin_skills_dir=tmp_path / "builtin")
+
+    assert loader.list_skills() == [
+        {
+            "name": "release-notes",
+            "path": str(plugin / "skills" / "release-notes" / "SKILL.md"),
+            "source": "plugin",
+            "plugin": "acme-tools",
+        }
+    ]
+    assert loader.get_explicitly_invoked_skills("Use $release-notes") == ["release-notes"]
+    assert "Draft release notes" in (loader.load_skill("release-notes") or "")
+    assert "### Agent Plugin skills" in loader.build_skills_summary()
+    assert "`acme-tools/skills/release-notes/SKILL.md`" in loader.build_skills_summary()
+
+
+def test_skills_loader_sees_plugin_installed_after_startup(tmp_path: Path) -> None:
+    loader = SkillsLoader(tmp_path, builtin_skills_dir=tmp_path / "builtin")
+    assert loader.list_skills() == []
+
+    plugin = _write_plugin(tmp_path, "acme-tools")
+    _write_skill(plugin, "release-notes")
+
+    assert [entry["name"] for entry in loader.list_skills()] == ["release-notes"]
+
+    shutil.rmtree(plugin)
+
+    assert loader.list_skills() == []
+    assert loader.build_skills_summary() == ""
+
+
+def test_agent_plugin_skills_are_direct_children_only(tmp_path: Path) -> None:
+    plugin = _write_plugin(tmp_path, "acme-tools")
+    _write_skill(plugin, "direct")
+    nested = plugin / "skills" / "group" / "nested"
+    nested.mkdir(parents=True)
+    (nested / "SKILL.md").write_text(
+        "---\nname: nested\ndescription: Nested skill.\n---\n",
+        encoding="utf-8",
+    )
+
+    assert [skill.name for skill in discover_agent_plugin_skills(tmp_path)] == ["direct"]
+
+
+@pytest.mark.parametrize(
+    "manifest",
+    [
+        {"$schema": "https://agent-plugins.org/schemas/2.0.0/plugin.schema.json", "name": "demo"},
+        {"$schema": AGENT_PLUGIN_SCHEMA, "name": "Bad-Name"},
+        {"$schema": AGENT_PLUGIN_SCHEMA, "name": "demo", "author": None},
+        {"$schema": AGENT_PLUGIN_SCHEMA, "name": "demo", "keywords": None},
+    ],
+)
+def test_invalid_agent_plugin_manifest_is_skipped(
+    tmp_path: Path,
+    manifest: dict[str, object],
+) -> None:
+    plugin = _write_plugin(tmp_path, "demo", manifest=manifest)
+    _write_skill(plugin, "example")
+
+    assert discover_agent_plugin_skills(tmp_path) == []
+
+
+def test_unknown_manifest_fields_and_non_object_extensions_are_ignored(tmp_path: Path) -> None:
+    plugin = _write_plugin(
+        tmp_path,
+        "demo",
+        manifest={
+            "$schema": AGENT_PLUGIN_SCHEMA,
+            "name": "demo",
+            "futureField": True,
+            "extensions": "invalid but non-fatal",
+        },
+    )
+    _write_skill(plugin, "example")
+
+    assert [skill.name for skill in discover_agent_plugin_skills(tmp_path)] == ["example"]
+
+
+@pytest.mark.parametrize(
+    ("skill_name", "frontmatter"),
+    [
+        ("wrong-directory", "name: another\ndescription: Mismatch."),
+        ("missing-description", "name: missing-description"),
+        ("Bad-Name", "name: Bad-Name\ndescription: Invalid name."),
+    ],
+)
+def test_invalid_agent_skill_is_skipped(
+    tmp_path: Path,
+    skill_name: str,
+    frontmatter: str,
+) -> None:
+    plugin = _write_plugin(tmp_path, "demo")
+    skill = plugin / "skills" / skill_name
+    skill.mkdir(parents=True)
+    (skill / "SKILL.md").write_text(f"---\n{frontmatter}\n---\n", encoding="utf-8")
+
+    assert discover_agent_plugin_skills(tmp_path) == []
+
+
+def test_workspace_skill_overrides_plugin_skill(tmp_path: Path) -> None:
+    plugin = _write_plugin(tmp_path, "demo")
+    _write_skill(plugin, "shared", description="Plugin version.")
+    workspace_skill = tmp_path / "skills" / "shared"
+    workspace_skill.mkdir(parents=True)
+    (workspace_skill / "SKILL.md").write_text(
+        "---\nname: shared\ndescription: Workspace version.\n---\n",
+        encoding="utf-8",
+    )
+
+    loader = SkillsLoader(tmp_path, builtin_skills_dir=tmp_path / "builtin")
+
+    assert [entry["source"] for entry in loader.list_skills()] == ["workspace"]
+    assert "Workspace version" in (loader.load_skill("shared") or "")
+
+
+def test_plugin_skill_symlink_cannot_escape_plugin_root(tmp_path: Path) -> None:
+    plugin = _write_plugin(tmp_path, "demo")
+    outside = tmp_path / "outside"
+    _write_skill(outside, "escaped")
+    skills_root = plugin / "skills"
+    skills_root.mkdir()
+    try:
+        (skills_root / "escaped").symlink_to(
+            outside / "skills" / "escaped",
+            target_is_directory=True,
+        )
+    except OSError as exc:
+        pytest.skip(f"directory symlink unavailable: {exc}")
+
+    assert discover_agent_plugin_skills(tmp_path) == []

tests/cli_apps/test_service.py

@@ -9,6 +9,7 @@ from types import SimpleNamespace
 
 import pytest
 
+from nanobot.agent.agent_plugins import discover_agent_plugin_skills
 from nanobot.apps.cli.service import CliAppError, CliAppManager, CliAppsRuntimeConfig
 
 
@@ -391,6 +392,9 @@ def test_install_dispatches_safe_pip_and_installs_skill(
         "_fetch_skill_content",
         lambda app: "---\nname: cli-anything-gimp\ndescription: GIMP\n---\n# GIMP\n",
     )
+    legacy = manager.workspace / "skills" / "cli-app-gimp" / "SKILL.md"
+    legacy.parent.mkdir(parents=True)
+    legacy.write_text("legacy", encoding="utf-8")
 
     payload = manager.install("gimp")
 
@@ -400,9 +404,21 @@ def test_install_dispatches_safe_pip_and_installs_skill(
     assert "state_recorded" in payload["last_action"]["verification"]
     installed = json.loads(manager.installed_path.read_text(encoding="utf-8"))["apps"]
     assert installed["gimp"]["entry_point"] == "cli-anything-gimp"
-    skill = manager.workspace / "skills" / "cli-app-gimp" / "SKILL.md"
+    plugin = manager.workspace / "plugins" / "cli-app-gimp"
+    skill = plugin / "skills" / "cli-app-gimp" / "SKILL.md"
     assert skill.is_file()
+    assert json.loads((plugin / "plugin.json").read_text(encoding="utf-8")) == {
+        "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+        "name": "cli-app-gimp",
+        "version": "1.0.0",
+        "description": "Public duplicate entry",
+    }
+    assert "name: cli-app-gimp" in skill.read_text(encoding="utf-8")
     assert 'run_cli_app` tool with `name="gimp"' in skill.read_text(encoding="utf-8")
+    assert [item.name for item in discover_agent_plugin_skills(manager.workspace)] == [
+        "cli-app-gimp"
+    ]
+    assert not legacy.exists()
 
 
 def test_run_argv_logs_command_exit_and_output(
@@ -487,7 +503,14 @@ def test_install_records_available_cli_without_reinstalling(
     assert "entry_point_available" in payload["last_action"]["verification"]
     installed = json.loads(manager.installed_path.read_text(encoding="utf-8"))["apps"]
     assert installed["feishu"]["entry_point_path"] == str(resolved)
-    skill = manager.workspace / "skills" / "cli-app-feishu" / "SKILL.md"
+    skill = (
+        manager.workspace
+        / "plugins"
+        / "cli-app-feishu"
+        / "skills"
+        / "cli-app-feishu"
+        / "SKILL.md"
+    )
     assert skill.is_file()
     assert 'run_cli_app` tool with `name="feishu"' in skill.read_text(encoding="utf-8")
 
@@ -704,7 +727,8 @@ def test_uninstall_removes_installed_state_and_generated_skill(
     manager = _manager(tmp_path)
     _seed_catalog(manager)
     manager._save_installed({"gimp": {"entry_point": "cli-anything-gimp"}})
-    skill_dir = manager.workspace / "skills" / "cli-app-gimp"
+    plugin_dir = manager.workspace / "plugins" / "cli-app-gimp"
+    skill_dir = plugin_dir / "skills" / "cli-app-gimp"
     skill_dir.mkdir(parents=True)
     (skill_dir / "SKILL.md").write_text("# GIMP\n", encoding="utf-8")
     monkeypatch.setattr(
@@ -717,7 +741,7 @@ def test_uninstall_removes_installed_state_and_generated_skill(
 
     assert payload["last_action"]["ok"] is True
     assert "gimp" not in json.loads(manager.installed_path.read_text(encoding="utf-8"))["apps"]
-    assert not skill_dir.exists()
+    assert not plugin_dir.exists()
 
 
 def test_uninstall_uses_safe_python_m_pip_uninstall_command(
@@ -845,19 +869,47 @@ def test_mentioned_installed_apps_only_returns_installed_mentions(tmp_path: Path
             "name": "zoom",
             "entry_point": "cli-anything-zoom",
             "source": "public",
-            "skill": "skills/cli-app-zoom/SKILL.md",
+            "skill": "plugins/cli-app-zoom/skills/cli-app-zoom/SKILL.md",
             "tool": "run_cli_app",
         },
         {
             "name": "gimp",
             "entry_point": "cli-anything-gimp",
             "source": "harness",
-            "skill": "skills/cli-app-gimp/SKILL.md",
+            "skill": "plugins/cli-app-gimp/skills/cli-app-gimp/SKILL.md",
             "tool": "run_cli_app",
         },
     ]
 
 
+def test_legacy_underscored_skill_remains_visible_and_removable(tmp_path: Path) -> None:
+    manager = _manager(tmp_path)
+    legacy = manager.workspace / "skills" / "cli-app-unimol_tools" / "SKILL.md"
+    legacy.parent.mkdir(parents=True)
+    legacy.write_text(
+        "---\nname: cli-app-unimol_tools\ndescription: Legacy Uni-Mol app.\n---\n",
+        encoding="utf-8",
+    )
+    manager._save_installed(
+        {"unimol_tools": {"entry_point": "cli-anything-unimol-tools", "source": "harness"}}
+    )
+
+    app = {
+        "name": "unimol_tools",
+        "entry_point": "cli-anything-unimol-tools",
+        "install_cmd": "pip install cli-anything-unimol-tools",
+    }
+
+    assert manager._app_payload(app, manager._load_installed())["skill_installed"] is True
+    assert manager.mentioned_installed_apps("use @unimol_tools")[0]["skill"] == (
+        "skills/cli-app-unimol_tools/SKILL.md"
+    )
+
+    manager.remove_skill("unimol_tools")
+
+    assert not legacy.exists()
+
+
 def test_install_rejects_unknown_and_script_strategy(tmp_path: Path) -> None:
     manager = _manager(tmp_path)
     _seed_catalog(manager)

tests/cli_apps/test_utils.py

@@ -39,7 +39,7 @@ def test_cli_app_mentions_inject_runtime_metadata(tmp_path, monkeypatch):
     assert "CLI App Mention: @zoom" in joined
     assert "tool=run_cli_app" in joined
     assert "entry_point=cli-anything-zoom" in joined
-    assert "skill=skills/cli-app-zoom/SKILL.md" in joined
+    assert "skill=plugins/cli-app-zoom/skills/cli-app-zoom/SKILL.md" in joined
 
 
 def test_structured_cli_app_attachment_injects_runtime_metadata(tmp_path):
@@ -61,4 +61,25 @@ def test_structured_cli_app_attachment_injects_runtime_metadata(tmp_path):
     assert "CLI App Attachment: @zoom" in joined
     assert "tool=run_cli_app" in joined
     assert "entry_point=cli-anything-zoom" in joined
-    assert "skill=skills/cli-app-zoom/SKILL.md" in joined
+    assert "skill=plugins/cli-app-zoom/skills/cli-app-zoom/SKILL.md" in joined
+
+
+def test_structured_cli_app_attachment_uses_existing_legacy_skill(tmp_path):
+    legacy = tmp_path / "skills" / "cli-app-unimol_tools" / "SKILL.md"
+    legacy.parent.mkdir(parents=True)
+    legacy.write_text("# Legacy Uni-Mol\n", encoding="utf-8")
+
+    lines = runtime_lines(
+        SimpleNamespace(
+            content="please use @unimol_tools",
+            metadata={
+                "cli_apps": [{
+                    "name": "unimol_tools",
+                    "entry_point": "cli-anything-unimol-tools",
+                }],
+            },
+        ),
+        tmp_path,
+    )
+
+    assert "skill=skills/cli-app-unimol_tools/SKILL.md" in "\n".join(lines)

webui/src/components/MessageBubble.tsx

@@ -724,7 +724,8 @@ function UserImageCell({
         aria-label={image.name ? `${openLabel}: ${image.name}` : openLabel}
         className={cn(
           tileClasses,
-          "block cursor-zoom-in p-0",
+          "block cursor-zoom-in p-0 transition-transform duration-150 motion-reduce:transition-none",
+          "hover:scale-[1.01] hover:ring-2 hover:ring-primary/25",
           "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50",
         )}
       >

webui/src/tests/message-bubble.test.tsx

@@ -916,14 +916,6 @@ describe("MessageBubble", () => {
 
     const imageButton = screen.getByRole("button", { name: /view image/i });
     expect(imageButton).toHaveClass("w-[min(100%,34rem)]", "rounded-[20px]");
-    expect(imageButton).toHaveClass(
-      "border",
-      "border-border/60",
-      "focus-visible:ring-2",
-    );
-    expect(imageButton).not.toHaveClass("hover:scale-[1.01]");
-    expect(imageButton).not.toHaveClass("hover:ring-2");
-    expect(imageButton).not.toHaveClass("hover:ring-primary/25");
     expect(imageButton).not.toHaveAttribute("title");
     expect(container.querySelector("img")).toHaveClass("h-auto", "w-full", "object-contain");
   });