feat: Add skills example and include skill location in agent prompt

[neubig]

Summary

This PR adds a comprehensive example demonstrating how to load and use AgentSkills with the software-agent-sdk, and fixes an issue where skill location was not being passed to the agent prompt.

Changes

1. New Example: examples/05_skills_and_plugins/01_loading_agentskills/

A concrete example showing how to:

• Create a skill directory with SKILL.md, scripts/, and references/
• Load skills from a custom directory
• Use keyword triggers to activate skills
• Access skill resources (scripts, references) from the agent

The example includes a ROT13 encryption skill that:

• Triggers on keywords: "encrypt", "decrypt", "cipher"
• Provides a scripts/encrypt.sh script for ROT13 encoding
• Includes references/examples.md with usage examples

2. Skill Location in Agent Prompt

Fixed an issue where the skill location (directory path) was not being passed to the agent prompt. Now when a skill is triggered, the agent sees:

<EXTRA_INFO>
The following information has been included based on a keyword match for "encrypt".
It may or may not be relevant to the user's request.

Skill location: /path/to/rot13-encryption
(Use this path to resolve relative file references in the skill content below)

[skill content]
</EXTRA_INFO>

This allows the agent to correctly resolve relative paths to scripts and references mentioned in the skill content.

Files Changed

• examples/05_skills_and_plugins/01_loading_agentskills/main.py - Example script
• examples/05_skills_and_plugins/01_loading_agentskills/example_skills/rot13-encryption/SKILL.md - Skill definition
• examples/05_skills_and_plugins/01_loading_agentskills/example_skills/rot13-encryption/scripts/encrypt.sh - ROT13 script
• examples/05_skills_and_plugins/01_loading_agentskills/example_skills/rot13-encryption/references/examples.md - Usage examples
• openhands-sdk/openhands/sdk/context/agent_context.py - Pass skill location to prompt
• openhands-sdk/openhands/sdk/context/prompts/templates/skill_knowledge_info.j2 - Display skill location
• openhands-sdk/openhands/sdk/context/skills/types.py - Add location field to SkillKnowledge
• tests/sdk/context/test_agent_context.py - Update tests for new prompt format

Testing

Ran the example successfully - agent encrypted "hello world" → "uryyb jbeyq" using the ROT13 skill.

All existing tests pass with updated expected outputs.

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

---

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:e6e71f4-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

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

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/context
agent_context.py	116	46	60%	87, 92, 102–103, 105–108, 110, 114–115, 117, 124–125, 127–130, 132, 136–138, 150–156, 184, 188, 204–206, 221, 229–231, 235, 238, 243, 252, 257–259, 264
TOTAL	14875	7138	52%

[neubig]

@OpenHands based on this PR, also open a PR on the OpenHands/docs repo documenting this example. Follow the best practices there, including using the "sync" command to sync the code. Make sure that the way you implement it, the check-examples workflow will pass.

[openhands-ai]

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

[openhands-ai]

I've created a PR on the OpenHands/docs repository documenting the skills example from PR #1599 on software-agent-sdk.

PR Created

OpenHands/docs#238

Changes Made

1. New Guide: sdk/guides/skill-loading.mdx

A comprehensive guide covering:

• AgentSkills directory structure (SKILL.md, scripts/, references/, assets/)
• SKILL.md format with YAML frontmatter
• Using load_skills_from_dir() and discover_skill_resources() functions
• How skill location is passed to the agent prompt for resolving relative paths
• Complete ROT13 encryption example

2. Navigation Update: docs.json

Added the new guide to the SDK Guides section, placed after the existing "Agent Skills & Context" guide.

Sync Compatibility

The guide includes a code block that references examples/05_skills_and_plugins/01_loading_agentskills/main.py using the sync format:

```python icon="python" expandable examples/05_skills_and_plugins/01_loading_agentskills/main.py

This follows the pattern used by other guides, allowing the sync-docs-code-blocks workflow to automatically keep the documentation in sync with the source code.

Verification

• ✅ Tested the sync script locally - all code blocks are in sync
• ✅ Branch name matches the software-agent-sdk PR branch (examples/skills-and-plugins)
• ✅ PR cross-references the related software-agent-sdk PR feat: Add skills example and include skill location in agent prompt #1599

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 #1599 at branch `examples/skills-and-plugins`

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

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

[juanmichelini]

assuming that "my-custom-skill" is intended instead of "rot13-encryption" LGTM !

[juanmichelini]

@graham could it be that instead of my-custom-skill it should berot13-encryption ?

[neubig]

@OpenHands fix this, I think my-custom-skill should be rot13-encryption

[openhands-ai]

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

[openhands-ai]

I've fixed the issue and pushed the changes to the PR branch.

Summary

Issue: The example code in examples/05_skills_and_plugins/01_loading_agentskills/main.py was referencing a non-existent skill directory my-custom-skill instead of the actual skill directory rot13-encryption.

Fix: Updated two lines in main.py:

• Line 45: Changed skill_subdir = example_skills_dir / "my-custom-skill" to skill_subdir = example_skills_dir / "rot13-encryption"
• Line 47: Changed the print statement from "my-custom-skill/" to "rot13-encryption/"

Checklist

• ✅ Changed my-custom-skill to rot13-encryption as requested
• ✅ Pre-commit hooks passed (ruff format, ruff lint, pycodestyle, pyright)
• ✅ Changes are minimal and focused on the fix
• ✅ Committed and pushed to the examples/skills-and-plugins branch

The PR #1599 has been updated with commit d101667c.

View full conversation