docs: document installed skills management by enyst · Pull Request #376 · OpenHands/docs

enyst · 2026-03-05T13:23:20Z

I have read and reviewed the documentation changes to the best of my ability.\n- [ ] If the change is significant, I have run the documentation site locally and confirmed it renders as expected.\n\nSummary of changes\n\n- Document installed AgentSkills management utilities in the SDK.\n- Add example usage for install/list/load/update/uninstall.\n- SDK PR: https://github.com/OpenHands/software-agent-sdk/pull/2320\n

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

all-hands-bot

Taste Rating: 🟡 Acceptable - Works but missing critical context

This documentation shows WHAT the API does but completely ignores WHY someone would use it. You're documenting persistence mechanisms without explaining the problem they solve. When would I use installed skills vs inline AgentSkill() definitions? That's not a theoretical question - it's the FIRST thing a developer will ask.

all-hands-bot · 2026-03-05T13:24:52Z

sdk/guides/skill.mdx

+
+You can install AgentSkills into a persistent directory and list/update them
+using `openhands.sdk.skills`. Skills are stored under
+`~/.openhands/skills/installed/` with a `.installed.json` metadata file.


🟠 Important: Missing context - WHY would someone use persistent installed skills instead of defining AgentSkill() inline in their code?

This is solving a problem without explaining what problem you're solving. Add 1-2 sentences explaining the use case:

"Use installed skills when you want to share skills across multiple projects"

"Persistent installation is useful for agent deployments that need consistent skill sets"

Or whatever the actual reason is

all-hands-bot · 2026-03-05T13:24:52Z

sdk/guides/skill.mdx

+    update_skill,
+)
+
+# Install from GitHub (supports git URLs, local paths, and repo_path for monorepos)


🟡 Suggestion: The comment says "supports git URLs, local paths, and repo_path for monorepos" but you only show ONE format. Show what these actually look like:

# GitHub shorthand install_skill("githubOpenHands/repo", ref="v1.0.0") # Git URL install_skill("git+https://github.com/owner/repo.git") # Local path install_skill("/path/to/skill") # Monorepo with repo_path install_skill("githubOpenHands/monorepo", repo_path="skills/my-skill")

Don't make developers guess the syntax.

all-hands-bot · 2026-03-05T13:24:52Z

sdk/guides/skill.mdx

+    print(f"{skill_info.name}: {skill_info.description}")
+
+# Load installed skills for an AgentContext
+skills = load_installed_skills()


🟠 Important: Incomplete example - you say "Load installed skills for an AgentContext" but don't show HOW to use them with an AgentContext. This will break the mental model.

Show the complete pattern:

from openhands.sdk import Agent, LLM # Load installed skills skills = load_installed_skills() # Use with agent agent = Agent(llm=LLM("anthropic/claude-3-5-sonnet-20241022"), skills=skills)

Or whatever the actual usage is. Half an example is worse than no example.

xingyaoww · 2026-03-05T18:02:20Z

sdk/guides/skill.mdx

+# Update or uninstall
+update_skill("my-skill")
+uninstall_skill("my-skill")
+```


@OpenHands please check OpenHands/software-agent-sdk codebase to verify if this is actually correct?

Also /remember this in .agents/skills/code-review.md following https://docs.openhands.dev/openhands/usage/use-cases/code-review#repository-specific-review-guidelines

I want to remember the preference that the code review bot SHOULD try to clone the repo (either OpenHands/software-agent-sdk, OpenHands/OpenHands-CLI, OpenHands/OpenHands) and find actual code corresponding to the code to verify that the docs is actually accurate and is not hallucinating stuff that doesn't exists in the codebase.

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

Summary

I addressed the PR comment by performing two actions:

1. Verified Documentation Accuracy ✅

I cloned OpenHands/software-agent-sdk and verified the new "Managing Installed Skills" section in sdk/guides/skill.mdx against the actual source code. Everything is accurate — all 5 functions (install_skill, list_installed_skills, load_installed_skills, update_skill, uninstall_skill) exist at the documented import path, signatures match, the github: source format is supported, InstalledSkillInfo has the referenced .name/.source/.description fields, and the storage paths (~/.openhands/skills/installed/, .installed.json) are correct. No documentation fixes were needed.

2. Created .agents/skills/code-review.md ✅

Following the format from the repository-specific review guidelines docs, I created a code-review skill file that instructs the review bot to:

Clone the corresponding upstream repo (OpenHands/software-agent-sdk, OpenHands/OpenHands, or OpenHands/OpenHands-CLI) when reviewing documentation changes

Verify documented APIs (import paths, function signatures, field names, supported values) against actual source code

Flag potentially hallucinated content that can't be verified

The file uses the proper YAML frontmatter with /codereview trigger so it integrates with the PR review workflow.

Checklist

Cloned software-agent-sdk and verified documentation accuracy

Created .agents/skills/code-review.md following the recommended format

Remembered the preference about source code verification in code reviews

Changes committed and pushed to the PR branch

Both changes have already been pushed to openhands/skills-install-utils.

Hah, maybe it's a bit tough 😅

@OpenHands The code-review skill in this repo checks docs against the main branches of the relevant repo(s), but it misses a guideline/adjustment:

when there is an open PR to the relevant repo, it should validate against that branch, even if it's open, that's fine

clone yourself the agent-sdk repo, read the CI workflow for documentation, and you will understand the intended relationship. The code-review skill should not block docs PRs that apply to a branch/PR, to the contrary.

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

Final summary (new since last update):

✅ Double-checked the git diff to confirm only the code-review skill guidance changed.

✅ Verified the request is fully addressed:

Added explicit guidance to validate docs against upstream PR branches when referenced.

Updated the verification example to show cloning a PR head branch.

No extra or unrelated edits.

✅ Changes are concise and limited to .agents/skills/code-review.md.

✅ Changes were already pushed to openhands/skills-install-utils.

Summary of changes:

Added guidance to prefer upstream PR branches as source-of-truth for doc reviews.

Expanded the “How to verify” section with an example of cloning a PR head branch.

Add .agents/skills/code-review.md that instructs the code review bot to clone upstream repositories (software-agent-sdk, OpenHands, OpenHands-CLI) and verify documentation accuracy against actual source code. Co-authored-by: openhands <openhands@all-hands.dev>

docs: document installed skills management

3ee87d5

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

enyst requested a review from xingyaoww as a code owner March 5, 2026 13:23

enyst mentioned this pull request Mar 5, 2026

feat: add AgentSkills install utilities OpenHands/software-agent-sdk#2320

Merged

5 tasks

mintlify bot deployed to staging March 5, 2026 13:24 View deployment

all-hands-bot reviewed Mar 5, 2026

View reviewed changes

openhands-ai bot mentioned this pull request Mar 5, 2026

AgentSkills management utilities OpenHands/software-agent-sdk#2301

Closed

xingyaoww reviewed Mar 5, 2026

View reviewed changes

mintlify bot deployed to staging March 5, 2026 18:06 View deployment

Merge branch 'main' into openhands/skills-install-utils

a18a518

mintlify bot deployed to staging March 5, 2026 18:09 View deployment

xingyaoww approved these changes Mar 5, 2026

View reviewed changes

xingyaoww merged commit 7de01f9 into main Mar 5, 2026
5 checks passed

xingyaoww deleted the openhands/skills-install-utils branch March 5, 2026 18:11

xingyaoww mentioned this pull request Mar 5, 2026

docs: add enable/disable for installed skills #377

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: document installed skills management#376

docs: document installed skills management#376
xingyaoww merged 3 commits intomainfrom
openhands/skills-install-utils

enyst commented Mar 5, 2026 •

edited

Loading

Uh oh!

all-hands-bot left a comment

Uh oh!

all-hands-bot Mar 5, 2026

Uh oh!

all-hands-bot Mar 5, 2026

Uh oh!

all-hands-bot Mar 5, 2026

Uh oh!

xingyaoww Mar 5, 2026

Uh oh!

openhands-ai bot Mar 5, 2026

Uh oh!

openhands-ai bot Mar 5, 2026

Uh oh!

enyst Mar 6, 2026

Uh oh!

openhands-ai bot Mar 6, 2026

Uh oh!

openhands-ai bot Mar 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

enyst commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

all-hands-bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

all-hands-bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

all-hands-bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

xingyaoww Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

openhands-ai bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

openhands-ai bot Mar 5, 2026

Choose a reason for hiding this comment

Summary

1. Verified Documentation Accuracy ✅

2. Created .agents/skills/code-review.md ✅

Checklist

Uh oh!

enyst Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

openhands-ai bot Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

openhands-ai bot Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

enyst commented Mar 5, 2026 •

edited

Loading

2. Created `.agents/skills/code-review.md` ✅