docs: add Docker instructions for loading user skills

[xingyaoww]

Problem

Fixes OpenHands/software-agent-sdk#2417

Users running OpenHands via Docker report that custom skills placed in ~/.openhands/skills/ are not loaded. The skill loader logs show 'user': 0 skills.

The root cause is not a code bug — the SDK correctly looks for skills in ~/.agents/skills/ and ~/.openhands/skills/. The issue is that Docker containers cannot see the host filesystem by default, so the user's local skills directory is invisible to the agent-server inside the container.

The existing documentation noted this limitation ("It does not work out of the box when running OpenHands using the docker command") but did not explain how to work around it.

Changes

overview/skills/org.mdx

• Replaced the brief note with tabbed instructions (CLI vs Docker)
• Added a complete Docker command example using SUBVOLUME_MOUNT
• Added a warning about mounting into ~/.agents/skills (not ~/.openhands/skills, which would overwrite public skills cache)
• Documented the pattern of storing skills on the host in any directory and mounting to ~/.agents/skills in the container

openhands/usage/troubleshooting/troubleshooting.mdx

• Added a "User Skills Not Loading in Docker" troubleshooting entry with description, resolution, and link to the full guide

---

This PR was created by an AI assistant (OpenHands) on behalf of @xingyaoww.

@xingyaoww can click here to continue refining the PR

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
all-hands-ai	🟢 Ready	View Preview	Apr 6, 2026, 8:23 AM

[all-hands-bot]

Documentation structure is solid, but SUBVOLUME_MOUNT appears to be undocumented/non-functional. See inline comments for critical issues and suggestions.

[all-hands-bot]

LINUS-STYLE CODE REVIEW

🔴 Needs improvement - Documenting features that don't exist is worse than no documentation

[CRITICAL ISSUES]

Data Structure Problem: This entire PR is built on SUBVOLUME_MOUNT, an environment variable that appears nowhere in the OpenHands codebase. I searched the Python code, shell scripts, Dockerfiles, entrypoint scripts, git history, and environment variable documentation. Nothing. Zero. Nada.

You know what this reminds me of? Someone once sent me a patch that fixed a bug by adding code to handle a case that could never happen. When I asked them to show me how to trigger it, they couldn't. That patch didn't get merged. This is the documentation equivalent.

Pragmatism Violation: Instead of verifying that SUBVOLUME_MOUNT actually works, we're documenting it as the solution to a real problem (users can't load skills in Docker). Users will follow this, waste their time, and still have broken skills. That's worse than having no documentation at all.

[WHAT SHOULD HAVE HAPPENED]

1. Verify the actual mechanism: Test that SUBVOLUME_MOUNT works, or find the REAL way to do this
2. Use existing, documented features: There's a SANDBOX_VOLUMES env var right in the docs. Did anyone check if that works? Or just use the battle-tested -v flag that's been in Docker since forever
3. Don't trust random GitHub comments: Even if @cbagwell suggested this (and they might know something I don't), verify it before documenting it

[THE REAL SOLUTION]

This is almost certainly one of two things:

Option A: Just use Docker's -v flag like a normal person:

-v $HOME/.agents/skills:/home/openhands/.agents/skills:ro

No magic env vars. No surprises. Works exactly like every other Docker container since 2013.

Option B: Find out what ACTUALLY works in OpenHands and document that.

[SECONDARY ISSUES]

Unverified Claims: "Mounting into ~/.openhands/skills would overwrite the public skills cache" - really? Show me where in the code. I see that skills are loaded from multiple directories in priority order. How does a mount "overwrite" a cache?

VERDICT:
❌ Needs rework: You can't document a feature that doesn't exist. Either prove SUBVOLUME_MOUNT works, or use something that actually does.

KEY INSIGHT:
Documenting non-existent features creates technical debt and user frustration. The correct approach is: test it works, THEN document it. Not the other way around.

[cbagwell]

Here is what I'm currently using to make skills visible inside local openhands runs:

    -e SANDBOX_VOLUMES=${HOME}/.agents:/home/openhands/.agent

I must have been trying to type from memory when I posted that previous comment in github issue. Sorry for the confusion.

[xingyaoww]

Updated in 84a3a1b: replaced SUBVOLUME_MOUNT with the documented SANDBOX_VOLUMES environment variable throughout both files. Also added :ro mode for read-only skills mount, a comma-separated multi-mount example, and a link to the SANDBOX_VOLUMES docs. Review requested from @all-hands-bot.

This comment was generated by an AI assistant (OpenHands).

[all-hands-bot]

🟢 Acceptable - Solid documentation addressing a real problem

VERDICT: ✅ Worth merging - Technical details verified against source code

KEY INSIGHT: This solves a real user pain point with the correct mechanism. All critical technical claims (SANDBOX_VOLUMES format, mount paths, skill loading directories) verified against OpenHands and agent-sdk source code. The comma-separated multi-mount format is confirmed in test_config.py. Mount path /home/openhands/.agents/skills matches the container user and SDK's USER_SKILLS_DIRS priority order.

Minor observation: PR lacks concrete evidence (logs showing 'user': N skills loaded after mounting), but the approach is sound and previous review rounds caught the critical issues (SUBVOLUME_MOUNT → SANDBOX_VOLUMES). For documentation addressing a reported user problem, this is sufficient.

[all-hands-bot]

🟢 Good taste - Pragmatic documentation that solves a real user problem.

VERDICT: ✅ Approved - All technical details verified in previous reviews, SANDBOX_VOLUMES correctly documented, clear examples provided.

KEY INSIGHT: This is how documentation should work - identifies real problem (Docker container isolation), uses existing mechanism (SANDBOX_VOLUMES), provides complete working examples with appropriate warnings.