docs: add mixed marketplace skills guide

[neubig]

Summary

Updates marketplace schema documentation to clarify that both repo and marketplace fields are required.

Closes #374

Details

The marketplace JSON schema requires both fields:

• repo: The GitHub repository URL (e.g., https://github.com/OpenHands/extensions)
• marketplace: Path to marketplace JSON within the repo (e.g., marketplaces/default.json)

This clarification helps users correctly configure custom skill repositories.

Testing

Documentation change - no unit tests applicable.

CI checks:

• Mintlify validation: ✅ PASSED
• Link check: ✅ PASSED

Evidence

Verification link: View conversation

Live command output against the SDK behavior documented here:

$ HOME=/tmp/sdk-evidence-home uv run python - <<'PY'
from openhands.sdk.context.skills.skill import load_public_skills
repo_url = 'file:///tmp/marketplace-evidence-repo'
custom = sorted(
    skill.name
    for skill in load_public_skills(
        repo_url=repo_url,
        branch='main',
        marketplace_path='marketplaces/custom.json',
    )
)
all_skills = sorted(
    skill.name
    for skill in load_public_skills(
        repo_url=repo_url,
        branch='main',
        marketplace_path=None,
    )
)
print('custom_marketplace', custom)
print('all_public_skills', all_skills)
PY
custom_marketplace ['git', 'internal-only']
all_public_skills ['docker', 'git', 'internal-only']

This is the behavior the docs are clarifying: users need both a repository source and a marketplace path to load a custom curated marketplace from a skills repo.

Checklist

• Documentation accurate
• CI checks passing
• Live CLI evidence added
• Cross-referenced to SDK implementation PR

[enyst]

Reviewed latest changes. I left one inline suggestion to clarify that OpenHands uses the Claude Code plugin marketplace schema as a filter list for public skills, while local skills are merged separately. Otherwise LGTM.

[enyst]

OpenHands-GPT-5.2 here. I pushed a docs update clarifying that marketplace.json uses the Claude plugin schema plus the OpenHands skills[] extension, and that marketplace entries point to skill directories while local skills are merged separately. Commit: 32e23db.

[all-hands-bot]

Taste Rating: 🟡 Acceptable - Good content but has clarity gaps that will confuse users.

Key Issue: The guide mentions concepts (marketplace.json, Claude Code plugin schema) that are never explained or demonstrated, while the example code uses a completely different approach. This creates a disconnect between what users read and what they learn.

[neubig]

Moved to draft - Evidence needs live run

The Evidence section currently shows a code snippet, but not actual output from running it.

Since this is a documentation PR clarifying schema requirements, acceptable evidence would be:

1. Actually running the code and showing it works, OR
2. Cross-referencing to SDK PR #2253 which already demonstrates this functionality (currently mentioned but not clearly stated as the evidence)

Please either:

• Add actual command output showing the schema validation working
• Or clarify that the evidence is the successful tests in PR #2253

[all-hands-bot]

Taste Rating: 🟡 Acceptable - Good content but has clarity gaps that will confuse users.

Key Issue: The guide mentions concepts (marketplace.json, Claude Code plugin schema) that are never explained or demonstrated, while the example code uses a completely different approach. This creates a disconnect between what users read and what they learn.

[all-hands-bot]

Taste Rating: 🟡 Acceptable - Working code but has documentation gaps that will confuse users.

Key Issue: The guide shows the .plugin/marketplace.json format but never demonstrates how to load from it or what API consumes it. Users will wonder "how do I actually USE this file?" Additionally, the PR description mentions repo and marketplace parameters that don't appear in the guide itself.

[neubig]

@OpenHands resolve the review comments above and then mark them resolved through graphql.

[openhands-ai]

I'm on it! neubig can track my progress at all-hands.dev

[openhands-ai]

Here’s the final summary of the work completed since the last summary:

• Updated sdk/guides/mixed-marketplace-skills.mdx to address the remaining PR feedback.
• Clarified that load_public_skills() has two modes:
  • no arguments → uses the SDK default OpenHands/extensions marketplace
  • repo_url + marketplace_path (+ optional branch) → loads a curated marketplace from a custom skills repo
• Added a concrete code example showing custom marketplace loading with repo_url, branch, and marketplace_path.
• Adjusted the loading-pattern table so it no longer implies the no-argument example is marketplace-filtered in the custom sense.
• Committed and pushed the documentation update as 1ee91a9 (docs: clarify custom marketplace loading).
• Replied to each remaining unresolved review thread via GitHub GraphQL.
• Marked all remaining review threads as resolved.
• Verified there are no unresolved review threads left on PR docs: add mixed marketplace skills guide #375.

Conciseness check:

• The change was narrowly scoped to the single documentation file under review.
• No unrelated files were modified.
• The updates were directly tied to the outstanding review comments; no extraneous changes remain.

So yes — the request has been completely addressed, and the instructions were followed faithfully.