feat(skills): support .agents/skills directory

[enyst]

Summary

• add .agents/skills to project skill discovery with highest priority
• update loader documentation/comment to mention .agents/skills

Testing

• uv run pre-commit run --files openhands-sdk/openhands/sdk/context/skills/skill.py

Context

• Call to standardize on .agents/skills on X

---

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.13-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:305f559-python

Run

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

All tags pushed for this build

ghcr.io/openhands/agent-server:305f559-golang-amd64
ghcr.io/openhands/agent-server:305f559-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:305f559-golang-arm64
ghcr.io/openhands/agent-server:305f559-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:305f559-java-amd64
ghcr.io/openhands/agent-server:305f559-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:305f559-java-arm64
ghcr.io/openhands/agent-server:305f559-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:305f559-python-amd64
ghcr.io/openhands/agent-server:305f559-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-amd64
ghcr.io/openhands/agent-server:305f559-python-arm64
ghcr.io/openhands/agent-server:305f559-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-arm64
ghcr.io/openhands/agent-server:305f559-golang
ghcr.io/openhands/agent-server:305f559-java
ghcr.io/openhands/agent-server:305f559-python

About Multi-Architecture Support

• Each variant tag (e.g., 305f559-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., 305f559-python-amd64) are also available if needed

[all-hands-bot]

Review Summary

The change is well-structured and maintains backward compatibility. However, there are a few areas that could be improved:

1. Testing coverage: No tests added to verify the new directory priority logic
2. Documentation scope: May need updates beyond the docstring
3. Implementation clarity: The precedence mechanism could be more explicit

Overall: ✅ Good change, but needs test coverage before merging.

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/context/skills
skill.py	347	21	93%	90–91, 246–247, 433–439, 442, 531–534, 751–752, 864, 871–872
TOTAL	16915	4965	70%

[all-hands-bot]

Review Summary

This PR cleanly implements support for .agents/skills directory with proper priority ordering. The implementation is solid and well-tested. I have a few suggestions for enhancement:

🟡 Suggestions

1. Add debug logging - Consider logging which directory skills are loaded from to help with troubleshooting
2. Migration nudge - Add an info log when both .agents/skills and .openhands/skills exist to encourage migration to the new standard
3. Test coverage - Add a test for loading different (non-duplicate) skills from multiple directories

✅ Positive Feedback

• Excellent documentation with clear precedence examples
• Clean, minimal implementation
• Comprehensive duplicate-handling tests
• Proper priority ordering in the code

Overall, this is a well-executed feature addition. The suggestions above are optional enhancements that could improve user experience.

[all-hands-bot]

🟡 Suggestion: Consider adding debug logging to help users understand which directory skills are being loaded from. This would make troubleshooting easier.

Example: Add a comment or logging in the loop that loads from these directories.

[all-hands-bot]

🟡 Suggestion: Consider adding an info/warning log when both .agents/skills and .openhands/skills directories exist, to encourage users to migrate to the new standard location. This would help with the transition mentioned in the X post.

Example:

agents_skills_dir = work_dir / ".agents" / "skills"
openhands_skills_dir = work_dir / ".openhands" / "skills"
if agents_skills_dir.exists() and openhands_skills_dir.exists():
    logger.info("Both .agents/skills and .openhands/skills found. Consider migrating to .agents/skills as the standard location.")

[all-hands-bot]

🟡 Suggestion: Consider adding a test that verifies loading different (non-duplicate) skills from multiple directories works correctly. The current tests cover duplicates well, but not the merge behavior when skills have different names.

Example test case:

def test_load_project_skills_merges_from_multiple_dirs(tmp_path):
    """Test skills from different directories are merged correctly."""
    agents_dir = tmp_path / ".agents" / "skills"
    skills_dir = tmp_path / ".openhands" / "skills"
    agents_dir.mkdir(parents=True)
    skills_dir.mkdir(parents=True)
    
    (agents_dir / "skill1.md").write_text("---\nname: skill1\n---\nContent 1.")
    (skills_dir / "skill2.md").write_text("---\nname: skill2\n---\nContent 2.")
    
    skills = load_project_skills(tmp_path)
    assert len(skills) == 2
    skill_names = {s.name for s in skills}
    assert skill_names == {"skill1", "skill2"}

[all-hands-bot]

🟢 Nit: Excellent documentation! The example clearly illustrates the precedence behavior. This will help users understand the priority system.