Skip to content

docs: document installed skills management #376

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xingyaoww merged 3 commits into from
Mar 5, 2026
Merged

docs: document installed skills management #376

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3ee87d5
docs: document installed skills management
openhands-agent Mar 5, 2026
fb67486
chore: add code-review skill with source verification guidelines
openhands-agent Mar 5, 2026
a18a518
Merge branch 'main' into openhands/skills-install-utils
xingyaoww Mar 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions .agents/skills/code-review.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
---
name: code-review
description: Code review guidelines for the OpenHands documentation repository
triggers:
- /codereview
---

# Documentation Repository Code Review Guidelines

You are reviewing changes to the OpenHands documentation site (Mintlify). This repository documents
multiple source-of-truth codebases. Accuracy is critical.

## Source Code Verification (Required for SDK/CLI/App docs)

When reviewing documentation that references APIs, function signatures, class names, or code examples
from an upstream repository, you **MUST** clone the corresponding repository and verify the documentation
against the actual source code. Do not trust that code examples or API descriptions are accurate without
checking.

### Repositories to clone for verification

| Documentation path | Source repository |
|--------------------|-------------------|
| `sdk/` | `OpenHands/software-agent-sdk` |
| `openhands/` | `OpenHands/OpenHands` |
| CLI-related docs | `OpenHands/OpenHands-CLI` |

### What to verify

- **Import paths** exist and export the documented symbols
- **Function/class signatures** match (parameter names, types, defaults, return types)
- **Field/attribute names** on data classes and models are correct
- **Supported values** (e.g., format strings like `"github:owner/repo"`) are actually handled in code
- **Behavioral descriptions** match the implementation logic
- **Example code** would actually run without errors

### How to verify

```bash
# Clone the relevant repo (use --depth=1 for speed)
git clone --depth=1 https://github.com/OpenHands/software-agent-sdk.git /tmp/agent-sdk

# Search for the documented symbols
grep -rn "function_name" /tmp/agent-sdk/
```

## Review Decisions

### When to APPROVE
- Documentation-only style/formatting changes
- Accurate content verified against source code
- Changes that correctly sync with upstream code changes

### When to COMMENT
- Documentation claims that cannot be verified against source code
- Potentially hallucinated API surfaces (functions, parameters, classes that don't exist)
- Inaccurate signatures, return types, or field names
- Missing context that could mislead users

## General Guidelines

- Follow the conventions in `/openhands/DOC_STYLE_GUIDE.md`
- Ensure MDX frontmatter is present and well-formed
- Check that internal links use absolute doc paths (e.g., `/overview/quickstart`)
- Verify code blocks with file references use the correct sync format (see `sdk-guidelines.md`)
31 changes: 31 additions & 0 deletions sdk/guides/skill.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,37 @@ Skills are listed in the system prompt:
Add `triggers` to a SKILL.md for **both** progressive disclosure AND automatic injection when keywords match.
</Tip>

## Managing Installed Skills

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.
Copy link
Contributor

@all-hands-bot all-hands-bot Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 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


```python icon="python"
from openhands.sdk.skills import (
install_skill,
list_installed_skills,
load_installed_skills,
uninstall_skill,
update_skill,
)

# Install from GitHub (supports git URLs, local paths, and repo_path for monorepos)
Copy link
Contributor

@all-hands-bot all-hands-bot Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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.

info = install_skill("github:owner/my-skill", ref="v1.0.0")
print(f"Installed {info.name} from {info.source}")

# List installed skills
for skill_info in list_installed_skills():
print(f"{skill_info.name}: {skill_info.description}")

# Load installed skills for an AgentContext
skills = load_installed_skills()
Copy link
Contributor

@all-hands-bot all-hands-bot Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 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.


# Update or uninstall
update_skill("my-skill")
uninstall_skill("my-skill")
```
Copy link
Contributor

@xingyaoww xingyaoww Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link

@openhands-ai openhands-ai bot Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

@openhands-ai openhands-ai bot Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

@enyst enyst Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hah, maybe it's a bit tough 😅
image

@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.

Copy link

@openhands-ai openhands-ai bot Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

@openhands-ai openhands-ai bot Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


---

## Full Example
Expand Down
Loading