POC: support for Python package-based plugin loading #1399

jpshackelford · 2025-12-15T21:40:12Z

Description

This PR provides initial proof-of-concept support for distributing OpenHands plugins as Python packages with a manifest.json descriptor. This implementation enables early experimentation with package-based plugin distribution but is expected to be superseded by a more comprehensive implementation that fully aligns with the broader plugin architecture vision outlined in #1440, #1452, and OpenHands#12085.

Plugin Distribution Context

OpenHands supports two complementary forms of plugin distribution, each with distinct advantages:

Bare Git Repository Marketplaces (See [TODO: add PR/issue reference])
- Easy to setup without formal build processes
- No SDLC overhead or complex versioning requirements
- Ideal for simple markdown-only plugins
- Quick iteration and sharing within teams
Python Package Distribution (This PR - POC: support for Python package-based plugin loading #1399)
- Formal versioning and release controls
- Better suited for plugins containing code alongside markdown
- Integration with existing Python packaging ecosystem (PyPI, etc.)
- Dependency management and installation tooling

Status & Future Work

Important: This PR implements an initial proof of concept that:

Uses manifest.json format aligned with Claude Desktop Extensions
Supports basic package loading and skill discovery
Provides a foundation for experimentation

Expected to be superseded by: A future PR that implements the full plugin architecture from #1440 and #1452, including:

Support for .plugin/ directory structure with plugin.json manifests
AgentSkills-compatible SKILL.md format with frontmatter validation
Progressive disclosure and resource directory support (scripts/, references/, assets/)
Full compatibility with Claude Code Plugins and AgentSpec standards

Key Changes in This PR

manifest.json Support: Claude Code-aligned JSON format for skill packages
Simplified package_loader.py: Reads manifest.json format (removed YAML support)
Updated Tests: All tests use manifest.json format
Documentation: Migration guide and usage examples

Type of Change

New feature (proof of concept)
Documentation update
Test updates

manifest.json Format Example

{
  "name": "simple-code-review",
  "version": "1.0.0",
  "displayName": "Simple Code Review",
  "description": "Basic code review skills",
  "author": {
    "name": "OpenHands Team",
    "email": "team@openhands.ai"
  },
  "keywords": ["code-review", "security"],
  "license": "MIT",
  "skills": [
    {
      "name": "code-review",
      "description": "Guidelines for thorough code review",
      "path": "skills/code_review.md",
      "type": "keyword-triggered",
      "triggers": ["codereview", "review-code"]
    }
  ]
}

Testing

✅ All 13 package loader tests passing
✅ Ruff format and lint checks passing

This commit adds the ability to load skills from installed OpenHands skill packages, enabling reusable skill distribution across projects. Features: - Package discovery using Python entry points - Configuration via .openhands/packages.yaml - Functions to list, load, and inspect skill packages - Integration with existing skill loading infrastructure - Comprehensive tests and documentation - Example demonstrating all features New files: - openhands-sdk/openhands/sdk/context/skills/package_loader.py - tests/sdk/context/skill/test_package_loader.py - examples/01_standalone_sdk/04_use_skill_packages.py - docs/skill-packages.md - .openhands/packages.yaml (template) Related to: https://github.com/OpenHands/package-poc

Update the OpenHands SDK package loader to support both manifest.json (Claude Desktop Extensions-aligned) and skill-package.yaml (legacy) formats. Key Changes: - Add _load_descriptor() helper that tries JSON first, falls back to YAML - Update list_skill_packages() to use new descriptor loader - Update get_skill_package() to use new descriptor loader - Update load_skills_from_package() to handle both descriptor formats - Add comprehensive documentation on Claude Code alignment Features: - Full backwards compatibility with existing YAML packages - Cross-platform package support (OpenHands + Claude Desktop) - Automatic format detection and handling - No changes required to existing code using package_loader Documentation: - New claude-code-alignment.md guide - Usage examples for both formats - Migration strategies for existing packages - Integration guidelines This change aligns with OpenHands/package-poc PR #17 which implements the manifest.json format in the ohp package management tool. Related to OpenHands/package-poc#16 Co-authored-by: openhands <openhands@all-hands.dev>

- Removed YAML fallback logic from _load_descriptor() - Updated docstrings to reflect JSON-only support - Simplified load_skills_from_package() to handle only flat JSON structure - Removed dual-format handling code This is a clean break for Scenario 1 - packages must use manifest.json. Co-authored-by: openhands <openhands@all-hands.dev>

- Removed backwards compatibility mentions - Updated usage examples to show flat JSON structure - Clarified manifest.json is required for Scenario 1 - Updated migration section - Simplified benefits section Co-authored-by: openhands <openhands@all-hands.dev>

- Convert test fixtures from YAML to JSON format - Update descriptor access to use flat structure (no metadata/spec nesting) - Fix mock setup for manifest.json instead of skill-package.yaml - Keep yaml import for packages.yaml configuration support - Fix line length issues for ruff compliance - All 13 tests passing Co-authored-by: openhands <openhands@all-hands.dev>

github-actions · 2025-12-16T16:25:19Z

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/context/skills
package_loader.py	117	101	13%	38–39, 60, 62, 64–65, 67, 70, 72, 75, 77, 79, 96, 98–100, 102, 105, 107, 112–114, 116, 142–144, 146–147, 149–150, 154, 156, 158–160, 162–163, 166, 168, 170, 174, 179, 181, 183–185, 188–190, 192–194, 197, 202–203, 205, 207, 209–210, 213, 215, 220, 239–240, 242–250, 252, 270, 272–273, 275–278, 280–281, 283, 285–287, 289–291, 293–295, 297–299, 315, 317–319, 321
TOTAL	12991	5903	54%

…ll_packages.py - Updated example code to access flat manifest.json structure instead of nested metadata/spec - Fixed descriptor access patterns: descriptor['displayName'] instead of descriptor['metadata']['displayName'] - Renamed from 04_use_skill_packages.py to 31_use_skill_packages.py to match PR #1378 - Updated documentation reference to point to new filename - Added defensive handling for author and repository fields that can be string or object Co-authored-by: openhands <openhands@all-hands.dev>

Add isinstance check before passing triggers to KeywordTrigger to handle untyped frontmatter metadata. This ensures type safety and prevents passing non-list objects. Co-authored-by: openhands <openhands@all-hands.dev>

Automated formatting by yamlfmt to add standard YAML document delimiter. Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2025-12-19T03:08:50Z

Looks like there are a few issues preventing this PR from being merged!

GitHub Actions are failing:
- [Optional] Docs example

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #1399 at branch `openhands/align-package-loader-with-claude-code`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

This adds comprehensive documentation for the new skill packages feature, covering installation, loading, configuration, and package creation. Related to: OpenHands/software-agent-sdk#1399 Co-authored-by: openhands <openhands@all-hands.dev>

jpshackelford · 2025-12-19T03:19:40Z

📚 Documentation PR Created

The documentation for the skill packages example has been added to the docs repository:

Docs PR: Add documentation for skill packages docs#197

This resolves the failing check requiring documentation for examples/01_standalone_sdk/31_use_skill_packages.py.

The documentation covers:

Installing skill packages
Discovering and inspecting packages
Loading skills (configuration-based and programmatic)
Package manifest format
Creating custom packages
Integration with AgentContext

jpshackelford · 2025-12-19T06:41:12Z

Note that this PR needs additional work to bring into closer alignment with the vision for #1440 and related issues. We will leave this as is since it is currently supporting a working demo and we will carry on the work in #1457, closing this one when we are done.

all-hands-bot · 2026-01-03T12:16:59Z

[Automatic Post]: It has been a while since there was any activity on this PR. @jpshackelford, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

openhands-agent added 2 commits December 10, 2025 17:20

neubig mentioned this pull request Dec 15, 2025

PR information is not current, even after pressing refresh OpenHands/community-pr-dashboard#19

Closed

openhands-agent added 3 commits December 16, 2025 13:23

jpshackelford and others added 2 commits December 18, 2025 21:51

Fix pyright type error for triggers metadata

b882da8

Add isinstance check before passing triggers to KeywordTrigger to handle untyped frontmatter metadata. This ensures type safety and prevents passing non-list objects. Co-authored-by: openhands <openhands@all-hands.dev>

jpshackelford mentioned this pull request Dec 19, 2025

Skill package loading experiment #1378

Closed

Add YAML document delimiter to packages.yaml

dadf959

Automated formatting by yamlfmt to add standard YAML document delimiter. Co-authored-by: openhands <openhands@all-hands.dev>

jpshackelford mentioned this pull request Dec 19, 2025

Add documentation for skill packages OpenHands/docs#197

Open

jpshackelford mentioned this pull request Dec 19, 2025

Plugin 1.0 Definition #1440

Open

jpshackelford changed the title ~~Align package_loader with Claude Code manifest.json format~~ POC: support for Python package-based plugin loading Dec 19, 2025

This was referenced Dec 19, 2025

Support for bare git repository plugin marketplaces #1453

Open

Support for bare git repository plugin marketplaces #1454

Closed

Plugin Marketplace Compatibility: Align with Claude Code & AgentSpec #1457

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

POC: support for Python package-based plugin loading #1399

POC: support for Python package-based plugin loading #1399

Uh oh!

jpshackelford commented Dec 15, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Dec 16, 2025 •

edited

Loading

Uh oh!

openhands-ai bot commented Dec 19, 2025

Uh oh!

jpshackelford commented Dec 19, 2025

Uh oh!

jpshackelford commented Dec 19, 2025 •

edited

Loading

Uh oh!

all-hands-bot commented Jan 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

POC: support for Python package-based plugin loading #1399

Are you sure you want to change the base?

POC: support for Python package-based plugin loading #1399

Uh oh!

Conversation

jpshackelford commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Plugin Distribution Context

Status & Future Work

Key Changes in This PR

Type of Change

manifest.json Format Example

Testing

Related

Uh oh!

github-actions bot commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openhands-ai bot commented Dec 19, 2025

Uh oh!

jpshackelford commented Dec 19, 2025

Uh oh!

jpshackelford commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

all-hands-bot commented Jan 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jpshackelford commented Dec 15, 2025 •

edited

Loading

github-actions bot commented Dec 16, 2025 •

edited

Loading

jpshackelford commented Dec 19, 2025 •

edited

Loading