feat: support resource directories (scripts/, references/, assets/) #1482

neubig · 2025-12-22T16:15:19Z

Summary

This PR adds support for resource directories in skill packages, following the AgentSkills standard.

Depends on PR #1481 (.mcp.json support)

Changes

1. New `SkillResources` Model

Tracks resource directories for a skill:

from openhands.sdk.context.skills import SkillResources

resources = SkillResources(
    skill_root="/path/to/skill",
    scripts=["run.sh", "setup.py"],
    references=["guide.md", "api.md"],
    assets=["logo.png", "data.json"],
)

# Check if any resources exist
if resources.has_resources():
    print("Skill has resources")

# Get directory paths
scripts_dir = resources.get_scripts_dir()  # Path or None
refs_dir = resources.get_references_dir()  # Path or None
assets_dir = resources.get_assets_dir()    # Path or None

2. New `discover_skill_resources()` Function

Scans a skill directory for resource directories:

from openhands.sdk.context.skills import discover_skill_resources

resources = discover_skill_resources(Path("skills/my-skill"))
print(resources.scripts)     # ["run.sh", "utils/helper.py"]
print(resources.references)  # ["guide.md"]
print(resources.assets)      # ["logo.png"]

Features:

Discovers files recursively in each resource directory
Returns relative paths from the resource directory
Files are sorted alphabetically

3. New `RESOURCE_DIRECTORIES` Constant

Standard resource directory names per AgentSkills spec:

from openhands.sdk.context.skills import RESOURCE_DIRECTORIES

print(RESOURCE_DIRECTORIES)  # ("scripts", "references", "assets")

4. New `resources` Field on Skill

Tracks discovered resources:

skill = Skill.load(skill_md, skill_dir, directory_name="my-skill")
if skill.resources:
    print(f"Scripts: {skill.resources.scripts}")
    print(f"References: {skill.resources.references}")
    print(f"Assets: {skill.resources.assets}")

5. Updated `Skill.load()`

Now automatically discovers resources when loading SKILL.md directories:

skills/
└── my-skill/
    ├── SKILL.md
    ├── scripts/
    │   └── run.sh
    ├── references/
    │   └── guide.md
    └── assets/
        └── logo.png

Resource Directory Purposes

Per the AgentSkills specification:

Directory	Purpose
`scripts/`	Executable scripts the agent can run
`references/`	Reference documentation and examples
`assets/`	Static assets (images, data files, etc.)

Backward Compatibility

All changes are backward compatible
resources is None for flat skill files (non-directory format)
resources is None when no resource directories exist

Testing

Added 21 new tests covering:

SkillResources model methods
discover_skill_resources() functionality
Skill.load() integration with resources
Serialization of resources

Related Issues

Closes #1477

Part of #1473 (Support AgentSkills standard)

Diff from Previous PR

View changes from PR #1481

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	`eclipse-temurin:17-jdk`	Link
python	amd64, arm64	`nikolaik/python-nodejs:python3.12-nodejs22`	Link
golang	amd64, arm64	`golang:1.21-bookworm`	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:14cc6db-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-14cc6db-python \
  ghcr.io/openhands/agent-server:14cc6db-python

All tags pushed for this build

ghcr.io/openhands/agent-server:14cc6db-golang-amd64
ghcr.io/openhands/agent-server:14cc6db-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:14cc6db-golang-arm64
ghcr.io/openhands/agent-server:14cc6db-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:14cc6db-java-amd64
ghcr.io/openhands/agent-server:14cc6db-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:14cc6db-java-arm64
ghcr.io/openhands/agent-server:14cc6db-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:14cc6db-python-amd64
ghcr.io/openhands/agent-server:14cc6db-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-amd64
ghcr.io/openhands/agent-server:14cc6db-python-arm64
ghcr.io/openhands/agent-server:14cc6db-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-arm64
ghcr.io/openhands/agent-server:14cc6db-golang
ghcr.io/openhands/agent-server:14cc6db-java
ghcr.io/openhands/agent-server:14cc6db-python

About Multi-Architecture Support

Each variant tag (e.g., 14cc6db-python) is a multi-arch manifest supporting both amd64 and arm64
Docker automatically pulls the correct architecture for your platform
Individual architecture tags (e.g., 14cc6db-python-amd64) are also available if needed

Add support for AgentSkills standard fields (https://agentskills.io/specification): - description: Brief description of what the skill does - license: License under which the skill is distributed - compatibility: Environment requirements or compatibility notes - metadata: Arbitrary key-value metadata for extensibility - allowed_tools: List of pre-approved tools for the skill Also adds skills-ref as an optional dependency for future validation and prompt generation utilities. Closes #1474 Co-authored-by: openhands <openhands@all-hands.dev>

The skills-ref library will be added when validation and prompt generation utilities are implemented (issue #1478). Co-authored-by: openhands <openhands@all-hands.dev>

- Add find_skill_md() function to locate SKILL.md files (case-insensitive) - Add validate_skill_name() function for AgentSkills spec validation - Update load_skills_from_dir() to support skill-name/SKILL.md directories - Add directory_name and validate_name parameters to Skill.load() - Export new functions from __init__.py - Add 27 unit tests for new functionality Closes #1475 Co-authored-by: openhands <openhands@all-hands.dev>

- Add find_mcp_config() function to locate .mcp.json files - Add expand_mcp_variables() for variable expansion (, default) - Add load_mcp_config() to parse and validate .mcp.json files - Add mcp_config_path field to Skill model - Update Skill.load() to auto-load .mcp.json from SKILL.md directories - .mcp.json takes precedence over mcp_tools frontmatter - Support variable expansion - Export new functions from __init__.py - Add 19 unit tests for new functionality Closes #1476 Co-authored-by: openhands <openhands@all-hands.dev>

- Add SkillResources model to track resource directories - Add discover_skill_resources() function to scan for resources - Add RESOURCE_DIRECTORIES constant for standard directory names - Add resources field to Skill model - Update Skill.load() to auto-discover resources from SKILL.md directories - Export new classes and functions from __init__.py - Add 21 unit tests for new functionality Closes #1477 Co-authored-by: openhands <openhands@all-hands.dev>

github-actions · 2025-12-22T16:18:04Z

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/context/skills
skill.py	442	346	21%	66, 70–71, 75–76, 80–81, 93–98, 115, 117–121, 123, 139–142, 144–148, 161, 163–165, 167–168, 170–171, 176–177, 179, 191–196, 218, 221, 223–225, 228–233, 235, 237–238, 258–264, 266–267, 272–274, 277, 280–283, 285, 394–400, 406–410, 416–423, 451, 453–454, 456–457, 459, 470–471, 473–476, 479, 482–484, 490–495, 497–498, 505, 508–511, 513, 535–537, 540–541, 545, 547–550, 553, 555, 581, 584, 592, 597–599, 602–605, 611, 613–619, 622, 634–635, 647, 665, 667–668, 680–681, 686, 693, 703–704, 706, 712–713, 715, 724–727, 729–732, 740–742, 750–752, 772–773, 776, 778–781, 783–785, 790–792, 804–812, 825–834, 855, 859–863, 865, 888–889, 891–894, 897–901, 904–905, 910–911, 916–917, 921–922, 928, 949–950, 952–955, 957–959, 964–968, 970, 974–975, 977, 980, 998–999, 1001–1002, 1005, 1010–1012, 1015, 1017–1019, 1024–1028, 1030, 1035–1036, 1040, 1043, 1057–1059, 1077, 1079–1083, 1090, 1097–1101, 1106–1108, 1110, 1125, 1127, 1129–1133, 1136–1139, 1173, 1175, 1177–1178, 1180–1182, 1185–1188, 1191, 1193, 1196–1198, 1202–1208, 1210–1211, 1213, 1216
TOTAL	14550	6917	52%

Reduce test code while maintaining essential coverage. Co-authored-by: openhands <openhands@all-hands.dev>

Resolved merge conflicts in: - openhands-sdk/openhands/sdk/context/skills/skill.py - tests/sdk/context/skill/test_agentskills_fields.py The resolution keeps both: 1. Pydantic field validators for allowed_tools and metadata from main 2. Skill name validation logic from this branch 3. SKILL.md convention support from this branch Co-authored-by: openhands <openhands@all-hands.dev>

Extract helper functions to simplify the load_skills_from_dir function: - _find_third_party_files: Find .cursorrules, AGENTS.md, etc. in repo root - _find_skill_md_directories: Find AgentSkills-style SKILL.md directories - _find_regular_md_files: Find regular .md files excluding SKILL.md dirs - _load_skill_safe: Load skills with consistent error handling This improves code readability and maintainability by following the single responsibility principle. Each helper function handles one specific aspect of skill discovery or loading. Co-authored-by: openhands <openhands@all-hands.dev>

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

- Remove redundant tuple element from _find_skill_md_directories (directory_path can be derived from skill_md.parent) - Replace _load_skill_safe wrapper with _load_and_categorize that combines loading and categorization in one function - Auto-validate skill name when directory_name is provided (removed separate validate_name parameter) - Fix case-insensitive search for third-party files to iterate over all files instead of checking specific variants - Update tests to check for specific error messages instead of magic number assertions Co-authored-by: openhands <openhands@all-hands.dev>

SKILL.md directories should always be categorized as knowledge_skills (progressive loading), not repo_skills (permanent context), even when they have no triggers defined. This addresses enyst's feedback that AgentSkills are fundamentally different from permanent OH skills like repo.md - they should use progressive loading while permanent skills should use AGENTS.md. Changes: - Modified _load_and_categorize to always put SKILL.md files in knowledge_skills when directory_name is provided - Added test_skill_md_always_knowledge_skill to verify the behavior Co-authored-by: openhands <openhands@all-hands.dev>

The file_content parameter was only used in unit tests. Tests have been updated to use pytest's tmp_path fixture and write content to actual temp files instead. Co-authored-by: openhands <openhands@all-hands.dev>

…gacy formats Split load() into: - _load_agentskills_skill(): For SKILL.md files (AgentSkills format) - _load_legacy_openhands_skill(): For legacy OpenHands skill files - _create_skill_from_metadata(): Shared helper for Skill object creation Co-authored-by: openhands <openhands@all-hands.dev>

- load_skills_from_dir() now returns 3 dictionaries: repo_skills, knowledge_skills, agent_skills - AgentSkills (SKILL.md directories) are categorized into agent_skills (separate from OpenHands skills) - Updated all callers to handle the new return type - Updated tests to verify the new categorization This addresses enyst's review comment about keeping AgentSkills separate from OpenHands skills, as they follow different standards and loading patterns. Co-authored-by: openhands <openhands@all-hands.dev>

Add support for .mcp.json files in AgentSkills directories (SKILL.md format), following the AgentSkills standard for MCP server configuration. Changes: - Add _find_mcp_config() to locate .mcp.json files in skill directories - Add _expand_mcp_variables() for variable expansion (${VAR}, ${VAR:-default}) - Add _load_mcp_config() to load and validate .mcp.json files - Update _load_agentskills_skill() to load .mcp.json (agent_skills only) - Update _load_legacy_openhands_skill() to load mcp_tools from frontmatter MCP loading rules: - AgentSkills (SKILL.md): ONLY use .mcp.json, ignore mcp_tools frontmatter - Legacy skills (.md): ONLY use mcp_tools frontmatter, no .mcp.json support Co-authored-by: openhands <openhands@all-hands.dev>

neubig · 2025-12-31T13:18:26Z

@OpenHands resolve merge conflicts with main

openhands-ai · 2025-12-31T13:18:35Z

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

Resolved merge conflicts: - openhands-sdk/openhands/sdk/context/skills/skill.py: Integrated resource directories and MCP config support with main's refactored Skill.load() API - tests/sdk/context/skill/test_agentskills_fields.py: Used main's test structure - tests/sdk/context/skill/test_skill_md_convention.py: Updated imports to use public functions (find_skill_md, validate_skill_name) - tests/sdk/context/skill/test_mcp_json_config.py: Updated to use new API - tests/sdk/context/skill/test_resource_directories.py: Updated to use new API Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2025-12-31T13:25:12Z

I've successfully resolved the merge conflicts between the feat/resource-directories branch and main. Here's a summary of what was done:

Merge Conflict Resolution Summary

Files with Conflicts Resolved:

openhands-sdk/openhands/sdk/context/skills/skill.py
- Integrated the resource directories feature (from the feature branch) with main's refactored Skill.load() API
- Main branch had refactored Skill.load() to split into _load_agentskills_skill() and _load_legacy_openhands_skill() methods
- Added the SkillResources model, discover_skill_resources(), MCP config functions, and new fields (mcp_config_path, resources) to the Skill model
- Updated _load_agentskills_skill() to discover resources and load MCP config
- Created aliases for backward compatibility (_find_skill_md = find_skill_md, _validate_skill_name = validate_skill_name)
tests/sdk/context/skill/test_agentskills_fields.py
- Used main's test structure (using tmp_path fixture and writing files to disk)
tests/sdk/context/skill/test_skill_md_convention.py
- Updated imports to use public functions (find_skill_md, validate_skill_name) from the package exports
tests/sdk/context/skill/test_mcp_json_config.py
- Updated to use the new API (removed directory_name parameter since SKILL.md files auto-detect it)
tests/sdk/context/skill/test_resource_directories.py
- Updated to use the new API (removed directory_name parameter)

Verification:

All 82 tests in tests/sdk/context/skill/ pass
Pre-commit hooks pass on all modified files

The changes have been pushed to the feat/resource-directories branch and PR #1482 is now updated with the merge from main.

View full conversation

Resolved merge conflicts by keeping the .mcp.json loading functionality from this branch while incorporating main's changes (PR #1480). Key changes preserved: - AgentSkills (SKILL.md) load .mcp.json with variable expansion - Legacy skills load mcp_tools from frontmatter only - _find_mcp_config, _expand_mcp_variables, _load_mcp_config functions Co-authored-by: openhands <openhands@all-hands.dev>

Use directory_name consistently as in main branch. Co-authored-by: openhands <openhands@all-hands.dev>

Resolved merge conflicts: - openhands-sdk/openhands/sdk/context/skills/__init__.py: Combined exports - openhands-sdk/openhands/sdk/context/skills/skill.py: Integrated MCP config and resource directories - tests/sdk/context/skill/test_skill_md_convention.py: Use public API imports Co-authored-by: openhands <openhands@all-hands.dev>

openhands-agent added 5 commits December 22, 2025 15:55

chore: remove unused agentskills optional dependency

c033966

The skills-ref library will be added when validation and prompt generation utilities are implemented (issue #1478). Co-authored-by: openhands <openhands@all-hands.dev>

neubig mentioned this pull request Dec 22, 2025

feat: add validation and prompt generation utilities #1483

Draft

openhands-agent and others added 14 commits December 22, 2025 16:25

refactor: consolidate AgentSkills tests

fed0593

Reduce test code while maintaining essential coverage. Co-authored-by: openhands <openhands@all-hands.dev>

refactor: consolidate AgentSkills tests

b5e571f

Reduce test code while maintaining essential coverage. Co-authored-by: openhands <openhands@all-hands.dev>

Merge main into feat/skill-md-convention

b33afe8

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

Merge branch 'main' into feat/skill-md-convention

5649c81

Update organization

feb7a2d

Remove file_content parameter from Skill.load()

e86afb8

The file_content parameter was only used in unit tests. Tests have been updated to use pytest's tmp_path fixture and write content to actual temp files instead. Co-authored-by: openhands <openhands@all-hands.dev>

Merge remote-tracking branch 'origin/main' into feat/skill-md-convention

821f5b5

openhands-agent and others added 4 commits December 31, 2025 13:48

fix: remove duplicate path.parent.name assignment

bba56fa

Use directory_name consistently as in main branch. Co-authored-by: openhands <openhands@all-hands.dev>

Merge branch 'main' into feat/resource-directories

e34051e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: support resource directories (scripts/, references/, assets/) #1482

feat: support resource directories (scripts/, references/, assets/) #1482

Uh oh!

neubig commented Dec 22, 2025 •

edited by github-actions bot

Loading

Uh oh!

github-actions bot commented Dec 22, 2025 •

edited

Loading

Uh oh!

neubig commented Dec 31, 2025

Uh oh!

openhands-ai bot commented Dec 31, 2025

Uh oh!

openhands-ai bot commented Dec 31, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: support resource directories (scripts/, references/, assets/) #1482

Are you sure you want to change the base?

feat: support resource directories (scripts/, references/, assets/) #1482

Uh oh!

Conversation

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

Uh oh!

Summary

Changes

1. New SkillResources Model

2. New discover_skill_resources() Function

3. New RESOURCE_DIRECTORIES Constant

4. New resources Field on Skill

5. Updated Skill.load()

Resource Directory Purposes

Backward Compatibility

Testing

Related Issues

Diff from Previous PR

Uh oh!

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

Uh oh!

Uh oh!

neubig commented Dec 31, 2025

Uh oh!

openhands-ai bot commented Dec 31, 2025

Uh oh!

openhands-ai bot commented Dec 31, 2025

Merge Conflict Resolution Summary

Files with Conflicts Resolved:

Verification:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

neubig commented Dec 22, 2025 •

edited by github-actions bot

Loading

1. New `SkillResources` Model

2. New `discover_skill_resources()` Function

3. New `RESOURCE_DIRECTORIES` Constant

4. New `resources` Field on Skill

5. Updated `Skill.load()`

github-actions bot commented Dec 22, 2025 •

edited

Loading