@openhands/extensions 0.13.0 → 0.15.0

package/skills/upstream-fork-sync/.plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "upstream-fork-sync",
+  "version": "1.0.0",
+  "description": "Create a cron automation that keeps a long-lived fork synchronized with its upstream. Fetches upstream changes, rebases local customizations on top, verifies the software works, and replaces the running version when the rebase is clean.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "fork",
+    "upstream",
+    "rebase",
+    "sync",
+    "cron",
+    "automation",
+    "long-lived-fork"
+  ]
+}

package/skills/upstream-fork-sync/README.md

@@ -0,0 +1,38 @@
+# Upstream Fork Sync Skill
+
+An OpenHands skill that creates a cron automation to keep a long-lived
+fork synchronized with its upstream source.
+
+## What it does
+
+1. **Fetches** the latest upstream changes for the fork on a schedule.
+2. **Rebases** the fork's local customizations on top of the newest
+   upstream HEAD.
+3. **Verifies** the software still works (using a configured command or an
+   inferred build check).
+4. **Replaces** the deployed version when verification passes, or
+   **fails safe** and reports the problem when it does not.
+
+## When to use
+
+Use this skill when a user wants to maintain customizations on top of an
+upstream project over time — the "long-lived fork" pattern — without
+manually redoing the work after every upstream release.
+
+## Files
+
+```
+upstream-fork-sync/
+├── SKILL.md   ← agent instructions (loaded automatically)
+└── README.md  ← this file
+```
+
+## Quick start
+
+Just tell OpenHands:
+
+> *"Set up an upstream fork sync for `owner/repo`"*
+
+The skill will walk through token verification, upstream-remote selection,
+local-changes description, verification command, and schedule, then create
+the automation automatically.

package/skills/upstream-fork-sync/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: upstream-fork-sync
+description: >
+  This skill should be used when the user asks to "keep a fork in sync",
+  "rebase local changes on upstream", "sync my fork nightly",
+  "long-lived fork", or "automate upstream rebases". Guides the user through
+  creating a cron automation that fetches upstream changes, rebases local
+  customizations on top, verifies the software works, and replaces the
+  running version when the rebase is clean.
+triggers:
+  - /upstream-fork-sync:setup
+---
+
+# Upstream Fork Sync Automation
+
+Create a cron automation that keeps a long-lived fork current with its
+upstream source. On every run it fetches the latest upstream changes,
+rebases the fork's local customizations on top, runs a verification check,
+and replaces the deployed version only when the software still works.
+
+This implements the "long-lived fork" pattern: instead of repeatedly
+re-deriving a customization, the local changes are preserved across
+upstream releases and kept working automatically.
+
+Windows PowerShell equivalents for the setup, packaging, upload, and API-check
+shell snippets are in `references/windows.md`.
+
+---
+
+## Prerequisites
+
+### Required secret
+
+Verify that the following secret is set in **OpenHands Settings -> Secrets**:
+
+| Secret name | Token type | Minimum permissions |
+|---|---|---|
+| `GITHUB_PERSONAL_ACCESS_TOKEN` | Classic PAT | `repo` |
+| `GITHUB_PERSONAL_ACCESS_TOKEN` | Fine-grained PAT | Contents: Read and Write, Metadata: Read |
+
+Check with:
+```bash
+curl -s https://api.github.com/user \
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
+  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))"
+```
+
+If the token is missing or invalid, inform the user and stop.
+
+---
+
+## Setup Workflow
+
+Follow these steps in order.
+
+### Step 1 - Verify `GITHUB_PERSONAL_ACCESS_TOKEN`
+
+Run the `curl` check above.
+
+- If absent: *"GITHUB_PERSONAL_ACCESS_TOKEN is not set. Please add it in
+  OpenHands Settings -> Secrets."* Stop.
+- If the API returns `{"message": "Bad credentials"}`: tell the user the
+  token is invalid and ask them to update it. Stop.
+
+### Step 2 - Collect configuration
+
+Confirm with the user:
+
+- **Repository** — the long-lived fork to keep synchronized (owner/repo).
+- **Upstream remote** (optional) — the remote the fork tracks. Defaults to
+  the repository's GitHub parent.
+- **Local changes** (optional) — a plain-language description of the
+  customizations to preserve across rebase.
+- **Verify command** (optional) — the command that confirms the software
+  works (e.g. `make test`). If blank, infer a sensible check from the
+  repository's build system.
+- **Sync schedule** — how often to run the sync. Default: nightly (`0 3 * * *`).
+
+### Step 3 - Create the automation
+
+Create the automation via the prompt preset:
+
+```bash
+curl -s -X POST "$AUTOMATION_API_URL/v1/preset/prompt" \
+  -H "Authorization: Bearer $OPENHANDS_AUTOMATION_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Upstream fork sync - '"$REPO"'",
+    "prompt": "Fetch the latest upstream changes for the fork '"$REPO"' and rebase all local changes on top of upstream. Local changes to preserve: '"$LOCAL_CHANGES"'. Check that the software works as intended; if it does, replace the current version, otherwise leave the running version untouched and report what failed.",
+    "repos": [{"url": "'"$REPO"'", "provider": "github"}],
+    "trigger": {"type": "cron", "schedule": "'"$SCHEDULE"'", "timezone": "'"$TIMEZONE"'"}
+  }'
+```
+
+Confirm the automation was created (HTTP 201) and report its ID to the user.
+
+---
+
+## Runtime behavior
+
+On each scheduled run the automation:
+
+1. Clones the fork and fetches the latest from its upstream remote.
+2. Rebases every local customization commit on top of the newest upstream
+   HEAD, resolving conflicts in favor of the local changes where the
+   description indicates intent.
+3. Runs the verification command. If none was supplied, infers one from the
+   repo's build system (e.g. `make test`, `npm test`, `pytest`).
+4. On success, force-pushes the rebased branch and replaces the currently
+   deployed version with the freshly built one.
+5. On failure, leaves the running version untouched and reports the conflict
+   or failing check so a human can intervene.
+
+---
+
+## Notes
+
+- The automation is idempotent: a clean upstream with no new commits is a
+  no-op.
+- Force-push targets the fork's working branch only, never upstream.
+- If a rebase conflict cannot be resolved automatically, the run fails safe
+  and the previously deployed version keeps running.

package/skills/upstream-fork-sync/commands/upstream-fork-sync-setup.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: This skill should be used when the user asks to "keep a fork in sync", "rebase local changes on upstream", "sync my fork nightly", "long-lived fork", or "automate upstream rebases". Guides the user through creating a cron automation that fetches upstream changes, rebases local customizations on top, verifies the software works, and replaces the running version when the rebase is clean.
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS

package/tests/fixtures/automations/upstream-fork-sync.json

@@ -0,0 +1,223 @@
+{
+  "automationId": "upstream-fork-sync",
+  "description": "Direct scheduled setup. Every create request body below is verified against the live CreatePromptAutomationRequest model in OpenHands/automation (openhands/automation/preset_router.py).",
+  "capabilities": "supported",
+  "blockedBy": [
+    "notReady"
+  ],
+  "scenarios": [
+    {
+      "id": "happy-path",
+      "description": "Defaults plus a repository, a description of the local changes, and a verify command. Preflight passes, the automation is created.",
+      "formValues": {
+        "repository": "OpenHands/agent-server-gui",
+        "upstreamRemote": "",
+        "localChanges": "high-contrast UI theme",
+        "verifyCommand": "make test",
+        "schedule": "0 3 * * *",
+        "timezone": "UTC"
+      },
+      "preflight": {
+        "request": {
+          "method": "POST",
+          "path": "/v1/validate",
+          "body": {
+            "automationId": "upstream-fork-sync",
+            "endpoint": "/v1/preset/prompt",
+            "draft": {
+              "name": "Upstream fork sync - OpenHands/agent-server-gui",
+              "prompt": "Fetch the latest upstream changes for the fork OpenHands/agent-server-gui and rebase all local changes on top of upstream. Local changes to preserve: high-contrast UI theme. Check that the software works as intended; if it does, replace the current version, otherwise leave the running version untouched and report what failed.",
+              "repos": [
+                {
+                  "url": "OpenHands/agent-server-gui",
+                  "provider": "github"
+                }
+              ],
+              "trigger": {
+                "type": "cron",
+                "schedule": "0 3 * * *",
+                "timezone": "UTC"
+              }
+            }
+          }
+        },
+        "response": {
+          "status": 200,
+          "body": {
+            "valid": true,
+            "errors": []
+          }
+        }
+      },
+      "create": {
+        "request": {
+          "method": "POST",
+          "path": "/v1/preset/prompt",
+          "body": {
+            "name": "Upstream fork sync - OpenHands/agent-server-gui",
+            "prompt": "Fetch the latest upstream changes for the fork OpenHands/agent-server-gui and rebase all local changes on top of upstream. Local changes to preserve: high-contrast UI theme. Check that the software works as intended; if it does, replace the current version, otherwise leave the running version untouched and report what failed.",
+            "repos": [
+              {
+                "url": "OpenHands/agent-server-gui",
+                "provider": "github"
+              }
+            ],
+            "trigger": {
+              "type": "cron",
+              "schedule": "0 3 * * *",
+              "timezone": "UTC"
+            }
+          }
+        },
+        "response": {
+          "status": 201,
+          "body": {
+            "id": "9a2c7b15-3c4d-4e5f-8a1b-4c9d0e1f2a33",
+            "user_id": "1a2b3c4d-0000-4000-8000-000000000001",
+            "org_id": "1a2b3c4d-0000-4000-8000-000000000002",
+            "model": null,
+            "name": "Upstream fork sync - OpenHands/agent-server-gui",
+            "prompt": "Fetch the latest upstream changes for the fork OpenHands/agent-server-gui and rebase all local changes on top of upstream. Local changes to preserve: high-contrast UI theme. Check that the software works as intended; if it does, replace the current version, otherwise leave the running version untouched and report what failed.",
+            "trigger": {
+              "type": "cron",
+              "schedule": "0 3 * * *",
+              "timezone": "UTC"
+            },
+            "tarball_path": "oh-internal://uploads/7e1b2c30-9f23-5b66-c2e3-7df1b4c5a990",
+            "setup_script_path": "setup.sh",
+            "entrypoint": ".venv/bin/python main.py",
+            "timeout": 600,
+            "keep_alive": null,
+            "enabled": true,
+            "last_triggered_at": null,
+            "created_at": "2026-08-03T12:00:00Z",
+            "updated_at": "2026-08-03T12:00:00Z"
+          }
+        }
+      }
+    },
+    {
+      "id": "interval-below-deployment-minimum",
+      "description": "A one-minute schedule. The create model accepts it, so only the deployment can reject it - this is precisely why preflight exists and why local validation is not authoritative.",
+      "formValues": {
+        "repository": "OpenHands/agent-server-gui",
+        "upstreamRemote": "",
+        "localChanges": "high-contrast UI theme",
+        "verifyCommand": "make test",
+        "schedule": "*/1 * * * *",
+        "timezone": "UTC"
+      },
+      "preflight": {
+        "request": {
+          "method": "POST",
+          "path": "/v1/validate",
+          "body": {
+            "automationId": "upstream-fork-sync",
+            "endpoint": "/v1/preset/prompt",
+            "draft": {
+              "name": "Upstream fork sync - OpenHands/agent-server-gui",
+              "prompt": "Fetch the latest upstream changes for the fork OpenHands/agent-server-gui and rebase all local changes on top of upstream. Local changes to preserve: high-contrast UI theme. Check that the software works as intended; if it does, replace the current version, otherwise leave the running version untouched and report what failed.",
+              "repos": [
+                {
+                  "url": "OpenHands/agent-server-gui",
+                  "provider": "github"
+                }
+              ],
+              "trigger": {
+                "type": "cron",
+                "schedule": "*/1 * * * *",
+                "timezone": "UTC"
+              }
+            }
+          }
+        },
+        "response": {
+          "status": 200,
+          "body": {
+            "valid": false,
+            "errors": [
+              {
+                "field": "trigger.schedule",
+                "code": "interval_too_short",
+                "message": "Minimum interval for this deployment is 5 minutes."
+              }
+            ]
+          }
+        }
+      },
+      "expectedFieldErrors": {
+        "schedule": "Minimum interval for this deployment is 5 minutes."
+      }
+    },
+    {
+      "id": "unfireable-cron-rejected-at-create",
+      "description": "31 February. Syntactically valid, so a local check passes, but the service rejects it. Shows the real 422 body: detail is a list and the loc path carries the trigger discriminator tag.",
+      "formValues": {
+        "repository": "OpenHands/agent-server-gui",
+        "upstreamRemote": "",
+        "localChanges": "high-contrast UI theme",
+        "verifyCommand": "make test",
+        "schedule": "0 0 31 2 *",
+        "timezone": "UTC"
+      },
+      "create": {
+        "request": {
+          "method": "POST",
+          "path": "/v1/preset/prompt",
+          "body": {
+            "name": "Upstream fork sync - OpenHands/agent-server-gui",
+            "prompt": "Fetch the latest upstream changes for the fork OpenHands/agent-server-gui and rebase all local changes on top of upstream. Local changes to preserve: high-contrast UI theme. Check that the software works as intended; if it does, replace the current version, otherwise leave the running version untouched and report what failed.",
+            "repos": [
+              {
+                "url": "OpenHands/agent-server-gui",
+                "provider": "github"
+              }
+            ],
+            "trigger": {
+              "type": "cron",
+              "schedule": "0 0 31 2 *",
+              "timezone": "UTC"
+            }
+          }
+        },
+        "response": {
+          "status": 422,
+          "body": {
+            "detail": [
+              {
+                "type": "value_error",
+                "loc": [
+                  "body",
+                  "trigger",
+                  "cron",
+                  "schedule"
+                ],
+                "msg": "Value error, Cron expression cannot produce any future fire times: 0 0 31 2 *"
+              }
+            ]
+          }
+        }
+      },
+      "expectedFieldErrors": {
+        "schedule": "Value error, Cron expression cannot produce any future fire times: 0 0 31 2 *"
+      }
+    },
+    {
+      "id": "fallback-conversation-when-direct-unavailable",
+      "description": "A cron-only deployment cannot run a webhook trigger, but this entry is cron-only and so runs directly; the assisted message seeds the conversation when the deployment is not ready.",
+      "formValues": {
+        "repository": "OpenHands/agent-server-gui",
+        "upstreamRemote": "",
+        "localChanges": "high-contrast UI theme",
+        "verifyCommand": "make test",
+        "schedule": "0 3 * * *",
+        "timezone": "UTC"
+      },
+      "conversation": {
+        "request": {
+          "message": "This deployment cannot run the scheduled fork-sync automation directly. Set it up in this conversation instead: confirm the fork repository, the upstream remote, the local changes to preserve, the verification command, and the nightly schedule, then create the automation."
+        }
+      }
+    }
+  ]
+}

package/tests/test_skills_catalog.py

@@ -27,6 +27,13 @@ def run_node(script: str, *, cwd: str | Path = ROOT, check: bool = True) -> subp
     )
 
 
+def empty_marketplaces(tmp_path: Path) -> Path:
+    """Isolates fixtures from the real manifests, so a fixture named after a real skill can't inherit its category."""
+    path = tmp_path / "marketplaces"
+    path.mkdir()
+    return path
+
+
 # ---------------------------------------------------------------------------
 # parseFrontmatter unit tests (via Node subprocess)
 # ---------------------------------------------------------------------------
@@ -134,9 +141,11 @@ class TestCodegenEndToEnd:
             skill_dir.mkdir()
             (skill_dir / "SKILL.md").write_text(content)
 
+        markets_dir = empty_marketplaces(tmp_path)
+
         script = textwrap.dedent(f"""\
             import {{ buildCatalog }} from './scripts/build-skills-catalog.mjs';
-            const entries = buildCatalog({json.dumps(str(skills_dir))});
+            const entries = buildCatalog({json.dumps(str(skills_dir))}, {json.dumps(str(markets_dir))});
             process.stdout.write(JSON.stringify(entries));
         """)
         result = run_node(script)
@@ -173,9 +182,11 @@ class TestCodegenEndToEnd:
         (skills_dir / "bad").mkdir()
         (skills_dir / "bad" / "SKILL.md").write_text("No frontmatter here")
 
+        markets_dir = empty_marketplaces(tmp_path)
+
         script = textwrap.dedent(f"""\
             import {{ buildCatalog }} from './scripts/build-skills-catalog.mjs';
-            buildCatalog({json.dumps(str(skills_dir))});
+            buildCatalog({json.dumps(str(skills_dir))}, {json.dumps(str(markets_dir))});
         """)
         result = run_node(script)
         assert "Warning" in result.stderr
@@ -198,11 +209,13 @@ class TestCodegenEndToEnd:
                 f"---\nname: {name}\ndescription: {name} desc\n---\nBody {name}"
             )
 
+        markets_dir = empty_marketplaces(tmp_path)
+
         output = tmp_path / "output.js"
         script = textwrap.dedent(f"""\
             import {{ writeFileSync }} from "node:fs";
             import {{ buildCatalog }} from './scripts/build-skills-catalog.mjs';
-            const entries = buildCatalog({json.dumps(str(skills_dir))});
+            const entries = buildCatalog({json.dumps(str(skills_dir))}, {json.dumps(str(markets_dir))});
             const src = "export const SKILLS_CATALOG = " + JSON.stringify(entries) + ";\\nexport default SKILLS_CATALOG;\\n";
             writeFileSync({json.dumps(str(output))}, src);
         """)
@@ -246,9 +259,11 @@ class TestCodegenEndToEnd:
         (skills_dir / "has-skill" / "SKILL.md").write_text("---\nname: ok\ndescription: d\n---\nBody")
         (skills_dir / "no-skill").mkdir()  # no SKILL.md
 
+        markets_dir = empty_marketplaces(tmp_path)
+
         script = textwrap.dedent(f"""\
             import {{ buildCatalog }} from './scripts/build-skills-catalog.mjs';
-            const entries = buildCatalog({json.dumps(str(skills_dir))});
+            const entries = buildCatalog({json.dumps(str(skills_dir))}, {json.dumps(str(markets_dir))});
             process.stdout.write(JSON.stringify(entries));
         """)
         result = run_node(script)
@@ -334,3 +349,198 @@ class TestGeneratedSkillsIndex:
         subprocess.run(["node", str(SCRIPT)], cwd=str(ROOT), check=True, capture_output=True)
         after = SKILLS_INDEX.read_text()
         assert before == after, "skills/index.js is out of date — run: node scripts/build-skills-catalog.mjs"
+
+
+# ---------------------------------------------------------------------------
+# Marketplace skill categories (consumed by the agent-canvas /skills rail)
+# ---------------------------------------------------------------------------
+
+MARKETPLACES_DIR = ROOT / "marketplaces"
+
+SKILL_CATEGORY_IDS = {
+    "automations",
+    "environment",
+    "code-hosting",
+    "agent-authoring",
+    "code-quality",
+    "integrations",
+    "writing",
+    "design",
+    "other",
+}
+
+# Skills with no marketplace entry, so they fall back to "other".
+# Adding entries would mean creating .plugin/plugin.json and vendor symlinks (see test_skill_plugin_loading.py), which publishes them as Codex/Claude Code plugins.
+SKILLS_WITHOUT_MARKETPLACE_ENTRY = {"qa-changes", "release-notes"}
+
+EXPECTED_CATEGORY_COUNTS = {
+    "environment": 10,
+    "automations": 9,
+    "code-hosting": 8,
+    "agent-authoring": 8,
+    "code-quality": 6,
+    "integrations": 6,
+    "writing": 4,
+    "design": 2,
+    "other": 1,
+}
+
+
+def _marketplace_skill_categories() -> dict[str, str]:
+    """Map skill directory name -> category, across every marketplace manifest."""
+    result: dict[str, str] = {}
+    for path in sorted(MARKETPLACES_DIR.glob("*.json")):
+        manifest = json.loads(path.read_text())
+        for entry in manifest.get("plugins", []):
+            source = entry.get("source", "")
+            if not source.startswith("./skills/"):
+                continue
+            result[source.split("/")[-1]] = entry.get("category")
+    return result
+
+
+class TestMarketplaceSkillCategories:
+    def test_every_skill_entry_uses_a_known_category(self):
+        bad = {
+            name: category
+            for name, category in _marketplace_skill_categories().items()
+            if category not in SKILL_CATEGORY_IDS
+        }
+        assert bad == {}, f"Unknown categories: {bad}"
+
+    def test_uncovered_skills_are_exactly_the_known_exceptions(self):
+        dirs = {
+            d.name
+            for d in (ROOT / "skills").iterdir()
+            if d.is_dir() and not d.name.startswith(".")
+        }
+        uncovered = dirs - set(_marketplace_skill_categories())
+        assert uncovered == SKILLS_WITHOUT_MARKETPLACE_ENTRY
+
+    def test_category_distribution_is_balanced(self):
+        from collections import Counter
+
+        counts = dict(Counter(_marketplace_skill_categories().values()))
+        assert counts == EXPECTED_CATEGORY_COUNTS
+
+    def test_plugin_entries_keep_their_own_taxonomy(self):
+        """Plugin entries are for Claude Code browsing and must not be rewritten."""
+        categories = set()
+        for path in sorted(MARKETPLACES_DIR.glob("*.json")):
+            manifest = json.loads(path.read_text())
+            for entry in manifest.get("plugins", []):
+                if entry.get("source", "").startswith("./skills/"):
+                    continue
+                categories.add(entry.get("category"))
+        assert categories - SKILL_CATEGORY_IDS, (
+            "Plugin entries appear to have been rewritten to the skill taxonomy"
+        )
+
+
+class TestCategoryJoin:
+    def _build(self, tmp_path, skills: dict[str, str], manifests: dict[str, dict], check: bool = True):
+        skills_dir = tmp_path / "skills"
+        skills_dir.mkdir()
+        for name, content in skills.items():
+            (skills_dir / name).mkdir()
+            (skills_dir / name / "SKILL.md").write_text(content)
+
+        markets_dir = tmp_path / "marketplaces"
+        markets_dir.mkdir()
+        for filename, manifest in manifests.items():
+            (markets_dir / filename).write_text(json.dumps(manifest))
+
+        script = textwrap.dedent(f"""\
+            import {{ buildCatalog }} from './scripts/build-skills-catalog.mjs';
+            const entries = buildCatalog({json.dumps(str(skills_dir))}, {json.dumps(str(markets_dir))});
+            process.stdout.write(JSON.stringify(entries));
+        """)
+        return run_node(script, check=check)
+
+    def test_category_is_joined_from_the_manifest(self, tmp_path):
+        result = self._build(
+            tmp_path,
+            {"docker": "---\nname: docker\ndescription: d\n---\nBody"},
+            {"m.json": {"plugins": [{"name": "docker", "source": "./skills/docker", "category": "environment"}]}},
+        )
+        entries = json.loads(result.stdout)
+        assert entries[0]["category"] == "environment"
+
+    def test_plugin_entries_are_ignored_when_building_the_map(self, tmp_path):
+        result = self._build(
+            tmp_path,
+            {"docker": "---\nname: docker\ndescription: d\n---\nBody"},
+            {"m.json": {"plugins": [
+                {"name": "some-plugin", "source": "./plugins/some-plugin", "category": "utilities"},
+                {"name": "docker", "source": "./skills/docker", "category": "environment"},
+            ]}},
+        )
+        entries = json.loads(result.stdout)
+        assert entries[0]["category"] == "environment"
+
+    def test_unknown_category_throws_naming_the_skill(self, tmp_path):
+        result = self._build(
+            tmp_path,
+            {"docker": "---\nname: docker\ndescription: d\n---\nBody"},
+            {"m.json": {"plugins": [{"name": "docker", "source": "./skills/docker", "category": "code-hostig"}]}},
+            check=False,
+        )
+        assert result.returncode != 0
+        assert "docker" in result.stderr
+        assert "code-hostig" in result.stderr
+        assert "environment" in result.stderr  # the legal set is printed
+
+    def test_conflicting_categories_across_manifests_throws(self, tmp_path):
+        result = self._build(
+            tmp_path,
+            {"docker": "---\nname: docker\ndescription: d\n---\nBody"},
+            {
+                "a.json": {"plugins": [{"name": "docker", "source": "./skills/docker", "category": "environment"}]},
+                "b.json": {"plugins": [{"name": "docker", "source": "./skills/docker", "category": "design"}]},
+            },
+            check=False,
+        )
+        assert result.returncode != 0
+        assert "docker" in result.stderr
+        assert "Conflicting categories" in result.stderr
+        assert "environment" in result.stderr  # the first manifest's value
+        assert "design" in result.stderr  # the second manifest's conflicting value
+
+    def test_skill_without_an_entry_gets_other_and_warns(self, tmp_path):
+        result = self._build(
+            tmp_path,
+            {"lonely": "---\nname: lonely\ndescription: d\n---\nBody"},
+            {"m.json": {"plugins": []}},
+        )
+        entries = json.loads(result.stdout)
+        assert entries[0]["category"] == "other"
+        assert "lonely" in result.stderr
+
+
+class TestGeneratedCategories:
+    def test_every_entry_has_a_known_category(self):
+        script = textwrap.dedent("""\
+            import { SKILLS_CATALOG, SKILL_CATEGORY_IDS } from './skills/index.js';
+            const legal = new Set(SKILL_CATEGORY_IDS);
+            for (const entry of SKILLS_CATALOG) {
+              if (!legal.has(entry.category)) {
+                console.error('Bad category for ' + entry.name + ': ' + entry.category);
+                process.exit(1);
+              }
+            }
+        """)
+        run_node(script)
+
+    def test_uncovered_skills_land_in_other(self):
+        # flarglebargle is the one skill whose marketplace entry sets "other" on purpose: it is a trigger-testing skill, not a real category member.
+        script = textwrap.dedent(f"""\
+            import {{ SKILLS_CATALOG }} from './skills/index.js';
+            const expected = {json.dumps(sorted(SKILLS_WITHOUT_MARKETPLACE_ENTRY))};
+            const actual = SKILLS_CATALOG.filter(e => e.category === 'other').map(e => e.name).sort();
+            const extra = actual.filter(n => !expected.includes(n) && n !== 'flarglebargle');
+            if (extra.length) {{
+              console.error('Unexpected uncategorized skills: ' + extra.join(', '));
+              process.exit(1);
+            }}
+        """)
+        run_node(script)