feat(skills): add shell command execution in frontmatter for dynamic context by VascoSch92 · Pull Request #2582 · OpenHands/software-agent-sdk

VascoSch92 · 2026-03-26T12:28:12Z

Summary

Closes #2045

Inline command syntax: Skills can embed dynamic shell output in markdown using !command`` — the command is executed at render time and replaced with its stdout.
Code-block safety: Fenced () and inline (`) code blocks are never executed. Unclosed fenced blocks (odd number of delimiters) extend to EOF, preventing accidental execution of trailing content.
Escape hatch: !cmd produces the literal text !cmd without execution, letting authors document the syntax itself. - Error handling: Failed commands and timeouts return inline [Error: ...] markers. Large outputs are truncated at 50KB.

Test Plan

_execute_inline_command: success, failure, timeout, working directory, output truncation
render_content_with_commands: plain text passthrough, single/multiple commands, empty backticks
Code-block preservation: inline code, fenced blocks, inline code adjacent to commands
Unclosed fenced blocks don't leak commands
Escaped !cmd`` produces literal output
Skill.render_content integration and Skill.load round-trip

Checklist

If the PR is changing/adding functionality, are there tests to reflect this?
If there is an example, have you run the example to make sure that it works?
If there are instructions on how to run the code, have you followed the instructions and made sure that it works?
If the feature is significant enough to require documentation, is there a PR open on the OpenHands/docs repository with the same branch name?
Is the github CI passing?

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-slim`	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:e104e74-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

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

…injection Add support for dynamic context injection via shell commands in skill frontmatter. Commands are executed before skill content is processed, and their outputs are available as {{name}} template variables. New features: - CommandSpec model with name, command, timeout, and on_error fields - commands field in Skill frontmatter schema - Skill.render_content() method for command execution and substitution - Graceful error handling (fail/empty/message modes) Closes #2045 Co-authored-by: openhands <openhands@all-hands.dev>

github-actions · 2026-03-26T12:28:39Z

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

github-actions · 2026-03-26T12:29:01Z

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

github-actions · 2026-03-26T12:30:40Z

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/context/skills
execute.py	39	4	89%	92–95
skill.py	430	33	92%	94–95, 249–250, 436–442, 445, 562–565, 809–810, 869–870, 938–939, 1007, 1035, 1058, 1065–1066, 1110–1111, 1117–1118, 1124–1125
TOTAL	21295	6207	70%

all-hands-bot

🟡 Acceptable - Pragmatic feature with solid implementation. One comment needs clarification.

This PR changes agent behavior (skill loading/rendering) and should not be approved without running evals to verify no benchmark impact. Posting as COMMENT per repo policy on eval-risk changes.

enyst

Could we please see how exactly an Agentskill with commands looks like? Sorry if it’s obvious 🙊

VascoSch92 · 2026-03-27T13:30:35Z

@enyst

Could we please see how exactly an Agentskill with commands looks like? Sorry if it’s obvious 🙊

This is not part of the AgentSkill spec — it's an extension we're adding on our side. The commands field is a new frontmatter field specific to our Skill model (which extends the AgentSkill base with additional fields like resources, allowed_tools, etc.).

The idea is to allow skill authors to declare shell commands in frontmatter that produce dynamic context at render time. For example, a skill could inject the output of git status or date into its content via {{var_name}} template variables.

A concrete SKILL.md with commands looks like this:

  ---                                                                                                                                                                                                                                    
  name: my-skill             
  description: A skill with dynamic context
  commands:                                                                                                                                                                                                                              
    - name: git_status
      command: "git status --short"                                                                                                                                                                                                      
      timeout: 5             
      on_error: message                                                                                                                                                                                                                  
    - name: current_branch
      command: "git branch --show-current"                                                                                                                                                                                               
  ---                        

  Current branch: {{current_branch}}                                                                                                                                                                                                     
  Status: {{git_status}}                                                                                                                                                                                                                         
                             
  Rest of the skill content...

So the commands field this PR adds is not part of the AgentSkills standard, it's an addition to the Skill model on top of the standard fields.

enyst

How does Anthropic do this? I mean, please correct me if wrong, I think I saw they announced something like this

VascoSch92 · 2026-03-27T14:04:25Z

They have the special carachter ! that you can use.

For example:

They don't have a field in the frontmatter

enyst · 2026-03-27T14:11:26Z

What do you think, is there a reason why we don’t support that format? We were trying to support Anthropic formats in the measure of possible, to ease migration for users. That is, users shouldn’t have to change their skills in order to try OpenHands.

VascoSch92 · 2026-03-27T14:17:06Z

What do you think, is there a reason why we don’t support that format? We were trying to support Anthropic formats in the measure of possible, to ease migration for users. That is, users shouldn’t have to change their skills in order to try OpenHands.

actually this is True. I implemented the format explained in the issue. But what you say makes sense.

VascoSch92 · 2026-03-27T14:35:03Z

Or actually we can support both

enyst · 2026-03-27T14:48:46Z

I think maybe we should start with the one that people are using, Anthropic’s. And add extensions when we see an actual need?

neubig

Agree on trying to match the anthropic format!

all-hands-bot

🟢 Good taste - Clean implementation of a pragmatic feature.

This PR changes skill loading/rendering and should not be approved without running evals to verify no benchmark impact. Posting as COMMENT per repo policy on eval-risk changes.

The implementation is solid:

Regex pattern correctly separates code blocks from executable commands
Error handling is appropriate (timeouts, failures, output truncation)
Security warnings are present and match the existing trust model
Tests exercise real code paths rather than mocks

One minor documentation issue noted inline.

VascoSch92 · 2026-03-31T09:54:04Z

@enyst @neubig Now it follows the Claude convention

Example:

---
name: my-skill
description: A skill with dynamic context
---

Current branch: !`git branch --show-current`
Status: !`git status --short`

Rest of the skill content...

docs: OpenHands/docs#426

Document the new inline shell command execution feature (! syntax) for skills that enables dynamic context injection at render time. - Add 'Dynamic Command Execution' section to SDK skills guide - Update skill architecture with Dynamic Content Rendering capability - Update architecture diagram to show dynamic commands flow - Add render_content_with_commands to key components table Related to: OpenHands/software-agent-sdk#2582 Co-authored-by: openhands <openhands@all-hands.dev>

neubig

LGTM, thanks!

* docs: add dynamic command execution for skills Document the new inline shell command execution feature (! syntax) for skills that enables dynamic context injection at render time. - Add 'Dynamic Command Execution' section to SDK skills guide - Update skill architecture with Dynamic Content Rendering capability - Update architecture diagram to show dynamic commands flow - Add render_content_with_commands to key components table Related to: OpenHands/software-agent-sdk#2582 Co-authored-by: openhands <openhands@all-hands.dev> * update docs because of rendering of code blocks * adress feedbacks in review * adress feedbacks in review --------- Co-authored-by: openhands <openhands@all-hands.dev>

openhands-agent and others added 2 commits March 26, 2026 11:55

add command to skill

b3314bf

VascoSch92 requested a review from all-hands-bot March 26, 2026 12:28

This comment was marked as outdated.

Sign in to view

feedbacks

191e967

VascoSch92 requested a review from all-hands-bot March 26, 2026 12:40

This comment was marked as outdated.

Sign in to view

adress comments

72a5951

VascoSch92 requested a review from all-hands-bot March 26, 2026 12:48

all-hands-bot reviewed Mar 26, 2026

View reviewed changes

Comment thread openhands-sdk/openhands/sdk/context/skills/skill.py Outdated

VascoSch92 marked this pull request as ready for review March 26, 2026 12:51

VascoSch92 requested review from jpelletier1 and neubig March 26, 2026 12:52

This comment was marked as outdated.

Sign in to view

enyst reviewed Mar 26, 2026

View reviewed changes

Comment thread openhands-sdk/openhands/sdk/context/skills/skill.py Outdated

enyst reviewed Mar 26, 2026

View reviewed changes

enyst reviewed Mar 27, 2026

View reviewed changes

enyst mentioned this pull request Mar 27, 2026

feat(skills): Shell command execution in frontmatter for context injection #2045

Closed

5 tasks

neubig reviewed Mar 30, 2026

View reviewed changes

refactor after discussion

f7485f5

VascoSch92 requested a review from all-hands-bot March 31, 2026 09:44

all-hands-bot reviewed Mar 31, 2026

View reviewed changes

Comment thread openhands-sdk/openhands/sdk/context/skills/execute.py

add docstring as promised

216e827

VascoSch92 mentioned this pull request Mar 31, 2026

docs: add dynamic command execution for skills OpenHands/docs#426

Merged

VascoSch92 requested review from enyst and neubig March 31, 2026 10:27

neubig approved these changes Apr 3, 2026

View reviewed changes

VascoSch92 merged commit 807369c into main Apr 3, 2026
33 of 34 checks passed

VascoSch92 deleted the vasco/skill-command branch April 3, 2026 18:50

This was referenced Apr 14, 2026

[Feature] Make progressive-disclosure skill invocation explicit and observable #2824

Closed

feat(sdk/tools): add explicit invoke_skill tool for progressive-disclosure skills #2835

Merged

Conversation

VascoSch92 commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test Plan

Checklist

Uh oh!

github-actions bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python API breakage checks — ✅ PASSED

Uh oh!

github-actions bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

REST API breakage checks (OpenAPI) — ✅ PASSED

Uh oh!

This comment was marked as outdated.

Uh oh!

github-actions bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

enyst left a comment

Choose a reason for hiding this comment

Uh oh!

VascoSch92 commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

enyst left a comment

Choose a reason for hiding this comment

Uh oh!

VascoSch92 commented Mar 27, 2026

Uh oh!

enyst commented Mar 27, 2026

Uh oh!

VascoSch92 commented Mar 27, 2026

Uh oh!

VascoSch92 commented Mar 27, 2026

Uh oh!

enyst commented Mar 27, 2026

Uh oh!

neubig left a comment

Choose a reason for hiding this comment

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

VascoSch92 commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

neubig left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

VascoSch92 commented Mar 26, 2026 •

edited

Loading

github-actions bot commented Mar 26, 2026 •

edited

Loading

github-actions bot commented Mar 26, 2026 •

edited

Loading

github-actions bot commented Mar 26, 2026 •

edited

Loading

VascoSch92 commented Mar 27, 2026 •

edited

Loading

VascoSch92 commented Mar 31, 2026 •

edited

Loading