feat: add configurable marketplace_path setting for public skills loading (#2253)

Co-authored-by: openhands <openhands@all-hands.dev>

Author: neubig

openhands-agent-server/openhands/agent_server/skills_router.py

@@ -14,6 +14,7 @@
     load_all_skills,
     sync_public_skills,
 )
+from openhands.sdk.context.skills.skill import DEFAULT_MARKETPLACE_PATH
 
 
 skills_router = APIRouter(prefix="/skills", tags=["Skills"])
@@ -63,6 +64,13 @@ class SkillsRequest(BaseModel):
         default=True, description="Load project skills from workspace"
     )
     load_org: bool = Field(default=True, description="Load organization-level skills")
+    marketplace_path: str | None = Field(
+        default=DEFAULT_MARKETPLACE_PATH,
+        description=(
+            "Relative marketplace JSON path for public skills. "
+            "Set to null to load all public skills."
+        ),
+    )
     project_dir: str | None = Field(
         default=None, description="Workspace directory path for project skills"
     )
@@ -145,6 +153,7 @@ def get_skills(request: SkillsRequest) -> SkillsResponse:
         org_repo_url=org_repo_url,
         org_name=org_name,
         sandbox_exposed_urls=sandbox_urls,
+        marketplace_path=request.marketplace_path,
     )
 
     # Convert Skill objects to SkillInfo for response

openhands-agent-server/openhands/agent_server/skills_service.py

@@ -25,6 +25,7 @@
     load_available_skills,
 )
 from openhands.sdk.context.skills.skill import (
+    DEFAULT_MARKETPLACE_PATH,
     PUBLIC_SKILLS_BRANCH,
     PUBLIC_SKILLS_REPO,
     load_skills_from_dir,
@@ -284,6 +285,7 @@ def load_all_skills(
     org_repo_url: str | None = None,
     org_name: str | None = None,
     sandbox_exposed_urls: list[ExposedUrlData] | None = None,
+    marketplace_path: str | None = DEFAULT_MARKETPLACE_PATH,
 ) -> SkillLoadResult:
     """Load and merge skills from all configured sources.
 
@@ -304,6 +306,8 @@ def load_all_skills(
         org_repo_url: Pre-authenticated Git URL for org skills.
         org_name: Organization name for org skills.
         sandbox_exposed_urls: List of exposed URLs from sandbox.
+        marketplace_path: Relative marketplace JSON path for public skills.
+            Pass None to load all public skills without marketplace filtering.
 
     Returns:
         SkillLoadResult containing merged skills and source counts.
@@ -326,6 +330,7 @@ def load_all_skills(
         include_user=load_user,
         include_project=False,
         include_public=load_public,
+        marketplace_path=marketplace_path,
     )
     sources["sdk_base"] = len(sdk_base)
     skill_lists.append(list(sdk_base.values()))

openhands-sdk/openhands/sdk/context/agent_context.py

@@ -13,6 +13,7 @@
     load_available_skills,
     to_prompt,
 )
+from openhands.sdk.context.skills.skill import DEFAULT_MARKETPLACE_PATH
 from openhands.sdk.llm import Message, TextContent
 from openhands.sdk.llm.utils.model_prompt_spec import get_model_prompt_spec
 from openhands.sdk.logger import get_logger
@@ -71,6 +72,13 @@ class AgentContext(BaseModel):
             "This allows you to get the latest skills without SDK updates."
         ),
     )
+    marketplace_path: str | None = Field(
+        default=DEFAULT_MARKETPLACE_PATH,
+        description=(
+            "Relative marketplace JSON path within the public skills repository. "
+            "Set to None to load all public skills without marketplace filtering."
+        ),
+    )
     secrets: Mapping[str, SecretValue] | None = Field(
         default=None,
         description=(
@@ -115,6 +123,7 @@ def _load_auto_skills(self):
             include_user=self.load_user_skills,
             include_project=False,
             include_public=self.load_public_skills,
+            marketplace_path=self.marketplace_path,
         )
 
         existing_names = {skill.name for skill in self.skills}

openhands-sdk/openhands/sdk/context/skills/skill.py

@@ -897,6 +897,7 @@ def load_marketplace_skill_names(
 def load_public_skills(
     repo_url: str = PUBLIC_SKILLS_REPO,
     branch: str = PUBLIC_SKILLS_BRANCH,
+    marketplace_path: str | None = DEFAULT_MARKETPLACE_PATH,
 ) -> list[Skill]:
     """Load skills from the public OpenHands skills repository.
 
@@ -906,9 +907,10 @@ def load_public_skills(
     to keep the skills up-to-date. This approach is more efficient than fetching
     individual files via HTTP.
 
-    Only skills listed in the default marketplace (marketplaces/default.json) are
-    loaded. This allows the OpenHands extensions repository to contain additional
-    skills that are not included by default.
+    By default, only skills listed in the default marketplace
+    (marketplaces/default.json) are loaded. Pass a different relative
+    marketplace_path to load another marketplace, or None to load all public
+    skills without marketplace filtering.
 
     Note: When a skill directory contains a SKILL.md file (AgentSkills format),
     any other markdown files in that directory or its subdirectories are treated
@@ -918,6 +920,8 @@ def load_public_skills(
         repo_url: URL of the skills repository. Defaults to the official
             OpenHands skills repository.
         branch: Branch name to load skills from. Defaults to 'main'.
+        marketplace_path: Relative path to the marketplace JSON file within the
+            repository. Pass None to load all public skills without filtering.
 
     Returns:
         List of Skill objects loaded from the public repository.
@@ -950,34 +954,42 @@ def load_public_skills(
             logger.warning(f"Skills directory not found in repository: {skills_dir}")
             return all_skills
 
-        # Load the default marketplace to determine which skills to include
-        marketplace_skill_names = load_marketplace_skill_names(
-            repo_path, DEFAULT_MARKETPLACE_PATH
-        )
-
         # Determine which skill files to load
+        if marketplace_path is None:
+            marketplace_skill_names = None
+        else:
+            marketplace_skill_names = load_marketplace_skill_names(
+                repo_path, marketplace_path
+            )
+            if (
+                marketplace_skill_names is None
+                and marketplace_path != DEFAULT_MARKETPLACE_PATH
+            ):
+                logger.warning(
+                    "Configured marketplace path could not be loaded: %s",
+                    marketplace_path,
+                )
+                return all_skills
+
         if marketplace_skill_names is not None:
-            # Marketplace exists: only load skills listed in marketplace
             all_skill_files: list[Path] = []
             for skill_name in marketplace_skill_names:
-                # Check for AgentSkills format (directory with SKILL.md)
                 skill_md = skills_dir / skill_name / "SKILL.md"
                 if skill_md.exists():
                     all_skill_files.append(skill_md)
                     continue
-                # Check for legacy format (skill_name.md file)
+
                 legacy_md = skills_dir / f"{skill_name}.md"
                 if legacy_md.exists():
                     all_skill_files.append(legacy_md)
                     continue
+
                 logger.debug(
-                    f"Skill '{skill_name}' from marketplace not found in skills dir"
+                    "Skill '%s' from marketplace '%s' not found in skills dir",
+                    skill_name,
+                    marketplace_path,
                 )
         else:
-            # No marketplace: load all skills (backward compatible)
-            # Find SKILL.md directories (AgentSkills format) and regular .md files
-            # This ensures that markdown files in SKILL.md directories are NOT
-            # loaded as separate skills - they are reference materials.
             skill_md_files = find_skill_md_directories(skills_dir)
             skill_md_dirs = {skill_md.parent for skill_md in skill_md_files}
             regular_md_files = find_regular_md_files(skills_dir, skill_md_dirs)
@@ -1017,6 +1029,7 @@ def load_available_skills(
     include_user: bool = False,
     include_project: bool = False,
     include_public: bool = False,
+    marketplace_path: str | None = DEFAULT_MARKETPLACE_PATH,
 ) -> dict[str, Skill]:
     """Load and merge skills from SDK-level sources with consistent precedence.
 
@@ -1033,6 +1046,8 @@ def load_available_skills(
         include_user: Load user-level skills (~/.agents/skills, etc.).
         include_project: Load project-level skills (requires *work_dir*).
         include_public: Load public skills from the OpenHands extensions repo.
+        marketplace_path: Relative marketplace JSON path to use for public skills.
+            Pass None to load all public skills without marketplace filtering.
 
     Returns:
         Dict mapping skill name → Skill, with higher-precedence sources
@@ -1042,7 +1057,7 @@ def load_available_skills(
 
     if include_public:
         try:
-            for s in load_public_skills():
+            for s in load_public_skills(marketplace_path=marketplace_path):
                 available[s.name] = s
         except Exception as e:
             logger.warning(f"Failed to load public skills: {e}")

tests/agent_server/test_skills_service.py

@@ -256,6 +256,24 @@ def test_load_all_skills_sources_tracking(self):
             assert result.sources["org"] == 0
             assert result.sources["project"] == 0
 
+    def test_load_all_skills_passes_marketplace_path_to_sdk_base(self):
+        """Test that marketplace_path is forwarded to SDK public skill loading."""
+        with patch(self._PATCH_TARGET, side_effect=[{}, {}]) as mock_avail:
+            load_all_skills(
+                load_public=True,
+                load_user=True,
+                load_project=False,
+                load_org=False,
+                marketplace_path="marketplaces/custom.json",
+            )
+
+        sdk_base_call = mock_avail.call_args_list[0]
+        assert sdk_base_call.kwargs["include_public"] is True
+        assert sdk_base_call.kwargs["marketplace_path"] == "marketplaces/custom.json"
+
+        project_call = mock_avail.call_args_list[1]
+        assert project_call.kwargs["include_public"] is False
+
     def test_load_all_skills_disabled_sources(self):
         """Test that disabled sources are not loaded."""
         with patch(self._PATCH_TARGET, return_value={}) as mock_avail:

tests/sdk/context/skill/test_load_public_skills.py

@@ -386,6 +386,33 @@ def mock_update_repo(repo_url, branch, cache_dir):
         assert "testing" in skill_names
 
 
+def test_agent_context_uses_custom_marketplace_path(
+    mock_repo_with_marketplace, tmp_path
+):
+    """Test that AgentContext forwards marketplace_path to public skill loading."""
+
+    def mock_update_repo(repo_url, branch, cache_dir):
+        return mock_repo_with_marketplace
+
+    with (
+        patch(
+            "openhands.sdk.context.skills.skill.update_skills_repository",
+            side_effect=mock_update_repo,
+        ),
+        patch(
+            "openhands.sdk.context.skills.skill.get_skills_cache_dir",
+            return_value=tmp_path,
+        ),
+    ):
+        context = AgentContext(
+            load_public_skills=True,
+            marketplace_path="marketplaces/custom.json",
+        )
+
+    skill_names = {s.name for s in context.skills}
+    assert skill_names == {"git", "internal-only"}
+
+
 def test_agent_context_can_disable_public_skills_loading():
     """Test that public skills loading can be disabled."""
     context = AgentContext(load_public_skills=False)
@@ -626,6 +653,21 @@ def mock_repo_with_marketplace(tmp_path):
     }
     (marketplaces_dir / "default.json").write_text(json.dumps(marketplace))
 
+    custom_marketplace = {
+        "name": "custom",
+        "owner": {"name": "OpenHands", "email": "test@test.com"},
+        "metadata": {"description": "Custom test marketplace", "version": "1.0.0"},
+        "plugins": [
+            {"name": "git", "source": "./git", "description": "Git skill"},
+            {
+                "name": "internal-only",
+                "source": "./internal-only",
+                "description": "Internal skill",
+            },
+        ],
+    }
+    (marketplaces_dir / "custom.json").write_text(json.dumps(custom_marketplace))
+
     # Create .git directory to simulate a git repo
     (repo_dir / ".git").mkdir()
 
@@ -695,11 +737,56 @@ def mock_update_repo(repo_url, branch, cache_dir):
     ):
         skills = load_public_skills()
 
-        # Should only have git and docker (from marketplace), not internal-only
-        skill_names = {s.name for s in skills}
-        assert skill_names == {"git", "docker"}
-        assert "internal-only" not in skill_names
-        assert "experimental" not in skill_names
+    skill_names = {skill.name for skill in skills}
+    assert skill_names == {"git", "docker"}
+    assert "internal-only" not in skill_names
+    assert "experimental" not in skill_names
+
+
+def test_load_public_skills_uses_custom_marketplace_path(
+    mock_repo_with_marketplace, tmp_path
+):
+    """Test that a custom marketplace_path selects a different skill set."""
+
+    def mock_update_repo(repo_url, branch, cache_dir):
+        return mock_repo_with_marketplace
+
+    with (
+        patch(
+            "openhands.sdk.context.skills.skill.update_skills_repository",
+            side_effect=mock_update_repo,
+        ),
+        patch(
+            "openhands.sdk.context.skills.skill.get_skills_cache_dir",
+            return_value=tmp_path,
+        ),
+    ):
+        skills = load_public_skills(marketplace_path="marketplaces/custom.json")
+
+    assert {skill.name for skill in skills} == {"git", "internal-only"}
+
+
+def test_load_public_skills_returns_empty_for_invalid_custom_marketplace_path(
+    mock_repo_with_marketplace, tmp_path
+):
+    """Test that an invalid custom marketplace_path does not broaden skill loading."""
+
+    def mock_update_repo(repo_url, branch, cache_dir):
+        return mock_repo_with_marketplace
+
+    with (
+        patch(
+            "openhands.sdk.context.skills.skill.update_skills_repository",
+            side_effect=mock_update_repo,
+        ),
+        patch(
+            "openhands.sdk.context.skills.skill.get_skills_cache_dir",
+            return_value=tmp_path,
+        ),
+    ):
+        skills = load_public_skills(marketplace_path="marketplaces/missing.json")
+
+    assert skills == []
 
 
 def test_load_public_skills_loads_all_when_no_marketplace(tmp_path):