feat: implement progressive disclosure for skills

[neubig]

Summary

Implement progressive disclosure for skills following the Codex CLI approach and AgentSkills standard.

Key Changes

1. Agent-Triggered Skills (Codex CLI Style)

Skills can now be triggered by the agent based on description matching, not just keyword matching in user messages:

• User names a skill → skill is triggered
• Task matches skill description → agent decides to use the skill

This follows the Codex CLI trigger rules:

"If the user names a skill (with $SkillName or plain text) OR the task clearly matches a skill's description, you must use that skill for that turn."

2. Progressive Disclosure

Skills use a three-level progressive disclosure model:

1. Metadata (~100 tokens): Name and description loaded at startup for all skills
2. Instructions (< 5000 tokens): Full SKILL.md body loaded when skill is activated
3. Resources (as needed): scripts/, references/, assets/ loaded only when required

3. System Prompt Updates

The <SKILLS> section in system prompts now includes Codex-style usage rules:

• Trigger rules for when to use skills
• Progressive disclosure instructions
• Context hygiene guidelines
• Coordination rules for multiple skills

4. New Exports

Added to openhands.sdk.context:

• SkillResources - Resource directories for skills
• to_prompt() - Generate <available_skills> XML for prompts
• validate_skill() - Validate skill directories

5. Example

Added examples/01_standalone_sdk/33_skill_formats_compatibility.py demonstrating:

• Codex-style agent-triggered skills
• Backward compatibility with OpenHands keyword-triggered skills
• Both formats working together

Backward Compatibility

• Existing OpenHands skills (without description/resources) continue to work
• Keyword-triggered skills still function as before
• New AgentSkills-standard skills work alongside existing skills

References

• Codex CLI Skills Documentation
• AgentSkills Specification
• Codex CLI render.rs - Source of skill prompt template

---

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:6bd5cd0-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

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

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/context
agent_context.py	120	47	60%	88, 93, 103–104, 106–109, 111, 115–116, 118, 125–126, 128–131, 133, 137–139, 151–157, 192, 196, 208, 228–230, 245, 253–255, 259, 262, 267, 275, 280–282, 287
openhands-sdk/openhands/sdk/context/skills
exceptions.py	9	5	44%	15–17, 19–20
skill.py	520	423	18%	64, 68–69, 73–74, 78–79, 91–96, 113, 115–119, 121, 137–140, 142–146, 159, 161–163, 165–166, 168–169, 174–175, 177, 189–194, 214–215, 218, 221, 223–225, 228–233, 235, 237–238, 257, 259–265, 267–268, 273–275, 278, 281–284, 286, 303–304, 307–309, 312–315, 318–320, 323–326, 329–330, 333–335, 340–342, 345–347, 350–352, 354–355, 358–363, 365, 394–395, 397–398, 400–401, 403–404, 406–409, 411–413, 416–417, 420–427, 430–433, 435, 437–438, 443, 558–564, 570–574, 580–587, 615, 617–618, 620–621, 623, 634, 636–639, 642, 645–647, 651, 665–667, 670–671, 675, 677–680, 683, 685, 701, 704, 712, 717–719, 725, 727–733, 736, 745–746, 755–758, 774, 776–777, 789–790, 795, 802, 812–813, 815, 821–822, 824, 833–836, 838–841, 849–851, 859–861, 873–878, 891, 893–895, 897–898, 900–901, 906–907, 909, 924–925, 928, 930–933, 935–937, 942–944, 956–964, 977–986, 1007, 1011–1015, 1017, 1040–1041, 1043–1046, 1049–1053, 1056–1057, 1062–1063, 1068–1069, 1073–1074, 1080, 1101–1102, 1104–1107, 1109–1111, 1116–1120, 1122, 1126–1127, 1129, 1132, 1150–1151, 1153–1154, 1157, 1162–1164, 1167, 1169–1171, 1176–1180, 1182, 1187–1188, 1192, 1195, 1209–1211, 1229, 1231–1235, 1242, 1249–1253, 1258–1260, 1262, 1277, 1279, 1281–1285, 1288–1291, 1325, 1327, 1329–1330, 1332–1334, 1337–1340, 1343, 1345, 1348–1350, 1354–1360, 1362–1363, 1365, 1368
TOTAL	14636	6999	52%

[neubig]

@OpenHands resolve merge conflicts with main

[openhands-ai]

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

[openhands-ai]

I've successfully resolved the merge conflicts with main and pushed the changes to the feat/progressive-disclosure-skills branch.

Summary

Conflicts resolved in 2 files:

1. openhands-sdk/openhands/sdk/context/agent_context.py:

   • Merged the new llm_model and llm_model_canonical parameters from main into get_system_message_suffix()
   • Kept the model family filtering logic from main (filters vendor-specific skills like "claude" and "gemini" based on the LLM model being used)
   • Preserved the progressive disclosure features from the feature branch (triggered_skills, available_skills_xml generation)

2. openhands-sdk/openhands/sdk/context/skills/skill.py:

   • Kept all new AgentSkills features from the feature branch (SkillResources, to_prompt, validate_skill, etc.)
   • Main had removed these features, so the resolution kept the feature branch's additions

Verification:

• ✅ All pre-commit checks passed (Ruff format, Ruff lint, pycodestyle, pyright, import rules)
• ✅ All 234 context tests passed
• ✅ Changes pushed to origin/feat/progressive-disclosure-skills

The PR is now up-to-date with main and ready for further review.

View full conversation

[openhands-ai]

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 #1484 at branch `feat/progressive-disclosure-skills`

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

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