docs: Add guide for using skills in AgentSkills/Claude format #238

neubig · 2026-01-06T13:19:41Z

Summary

This PR adds documentation for the new example in software-agent-sdk that demonstrates how to use skills following the AgentSkills standard (compatible with Claude's format).

Changes

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

A comprehensive guide covering:

AgentSkills Directory Structure: How to organize skills with SKILL.md, scripts/, references/, and assets/ directories
SKILL.md Format: YAML frontmatter with name, description, triggers, license, compatibility, and metadata
Loading Skills: Using load_skills_from_dir() and discover_skill_resources() functions
Skill Location in Prompts: How the agent receives the skill's location path to resolve relative file references
Complete Example: ROT13 encryption skill demonstrating the full workflow

Navigation Update

Added the new guide to docs.json navigation, placed after the existing "Agent Skills & Context" guide.

Code Sync

The guide includes a code block that references examples/05_skills_and_plugins/01_loading_agentskills/main.py from the agent-sdk repository. This follows the sync pattern used by other guides, allowing the sync-docs-code-blocks workflow to keep the documentation in sync with the source code.

Related PRs

feat: Add skills example and include skill location in agent prompt software-agent-sdk#1599 - The PR that adds the skills example and skill location feature

Checklist

Documentation follows the existing style and format
Code block uses the sync format for automatic updates
Navigation updated in docs.json
Tested sync script locally - all code blocks are in sync

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

This adds documentation for the new example in software-agent-sdk that demonstrates how to use skills following the AgentSkills standard (compatible with Claude's format). The guide covers: - AgentSkills directory structure (SKILL.md, scripts/, references/, assets/) - Using load_skills_from_dir() and discover_skill_resources() - How skill location is passed to the agent prompt - A complete example with ROT13 encryption skill Related to: OpenHands/software-agent-sdk#1599 Co-authored-by: openhands <openhands@all-hands.dev>

neubig · 2026-01-07T16:24:07Z

@OpenHands run the sync script to update this example

openhands-ai · 2026-01-07T16:24:17Z

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

- Update skill-loading.mdx to use rot13-encryption skill directory name - Update pr-review.mdx workflow file Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2026-01-07T16:26:36Z

I ran the sync script to update the code blocks in the documentation. The changes have been committed and pushed to the examples/skills-and-plugins branch.

Summary of Changes

The sync script (python .github/scripts/sync_code_blocks.py) was executed, which:

Updated sdk/guides/skill-loading.mdx - Synced the code block with the actual source file from agent-sdk:
- Changed skill_subdir = example_skills_dir / "my-custom-skill" → skill_subdir = example_skills_dir / "rot13-encryption"
- Changed print("\nDiscovered resources in my-custom-skill/:") → print("\nDiscovered resources in rot13-encryption/:")
Updated sdk/guides/github-workflows/pr-review.mdx - Also synced as part of the same script run (minor workflow file update)

Checklist

✅ Ran the sync script as requested
✅ Code blocks now match the actual source files in agent-sdk
✅ Changes committed with appropriate message
✅ Changes pushed to the PR branch

The PR #238 has been updated with the synced code blocks.

View full conversation

sdk/guides/skill-loading.mdx

neubig · 2026-01-07T19:18:38Z

@OpenHands reflect xingyaoww's comment, and also make sure that the docs will appear in the sidebar appropriately

openhands-ai · 2026-01-07T19:18:47Z

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

Per reviewer feedback, combined the AgentSkills/Claude format documentation directly into the existing skill.mdx file and reorganized for better flow: - Added 'Inline Skills' section for code-defined skills - Added 'Loading Skills from Disk (AgentSkills Standard)' section with: - Directory structure - SKILL.md format - Loading functions (load_skills_from_dir, discover_skill_resources) - Skill location in prompts - ROT13 encryption example - Renamed 'Message Suffixes' section to 'Customizing Agent Context' - Removed separate skill-loading.mdx file - Updated docs.json navigation to remove skill-loading entry Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2026-01-07T19:23:09Z

I've addressed xingyaoww's comment by merging the skill-loading.mdx content directly into skill.mdx and reorganizing the file for better flow. The changes have been pushed to the PR.

Summary of Changes

What was done:

✅ Merged skill-loading.mdx into skill.mdx - Combined all AgentSkills/Claude format documentation into the existing skill guide
✅ Reorganized skill.mdx for better readability with clear sections:
- Inline Skills - For code-defined skills with the existing example
- Loading Skills from Disk (AgentSkills Standard) - New section covering directory structure, SKILL.md format, loading functions, and the ROT13 example
- Loading Public Skills - Existing content about public skills repository
- Customizing Agent Context - Renamed from "Message Suffixes" for clarity
✅ Removed skill-loading.mdx - Deleted the separate file
✅ Updated docs.json navigation - Removed the sdk/guides/skill-loading entry so the sidebar only shows the single combined guide

Files changed:

sdk/guides/skill.mdx - Expanded with merged content (+284 lines)
sdk/guides/skill-loading.mdx - Deleted (-279 lines)
docs.json - Removed skill-loading navigation entry (-1 line)

The PR at #238 has been updated with these changes.

View full conversation

sdk/guides/skill.mdx

The SDK repository was renamed from agent-sdk to software-agent-sdk. This commit syncs the workflow example to match the current SDK source. Co-authored-by: openhands <openhands@all-hands.dev>

Link to issue #1646 discussing alignment with AgentSkills standard for skills without triggers. Co-authored-by: openhands <openhands@all-hands.dev>

sdk/guides/skill.mdx

Major rewrite of skill documentation to clearly explain: - AgentSkills progressive disclosure model - Skill categorization flow diagram - Behavior differences between AgentSkills and legacy formats - How triggers work with AgentSkills format (best of both worlds) Key clarifications: - SKILL.md files always use progressive disclosure - SKILL.md with triggers: listed in available_skills AND auto-inject on trigger - Legacy skills without triggers: full content in REPO_CONTEXT - Legacy skills with triggers: listed in available_skills, inject on trigger Co-authored-by: openhands <openhands@all-hands.dev>

- Replace ugly ASCII flow diagram with CardGroup cards - Simplify behavior table to focus on user-facing behavior - Use Tabs component for system prompt examples - Remove internal implementation details (is_agentskills_format) - Clarify that OpenHands extends AgentSkills standard with triggers - Change Warning to Info for triggers extension (it's a feature, not a problem) Co-authored-by: openhands <openhands@all-hands.dev>

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

Major reorganization focused on user understanding: 1. Start with 'Two Types of Skills' - the key concept users need 2. Add 'Quick Start' with minimal code example 3. Add 'How It Works' with Steps component showing the flow 4. Simplify SKILL.md section with cleaner frontmatter table 5. Remove confusing 'How Skills Appear in System Prompt' section (this was implementation detail, not user-facing) 6. Use Tip instead of Info for actionable advice The goal is: users understand WHAT skills do before HOW to configure them. Co-authored-by: openhands <openhands@all-hands.dev>

sdk/guides/skill.mdx

Reorganize documentation to clearly show the three approaches: 1. AGENTS.md (Recommended for repos) - At repo root, auto-loaded - Model variants: CLAUDE.md, GEMINI.md - Works with other AI tools 2. Keyword-Triggered Skills - Activated by keywords in user messages - Content injected as <EXTRA_INFO> - Keeps system prompt lean 3. Always-Active Skills (Code-Based) - For programmatic control - Full content in system prompt This makes it clear when to use each approach. Co-authored-by: openhands <openhands@all-hands.dev>

Reorganize to focus on SDK implementation with clear loading methods: 1. Always-loaded context - AGENTS.md (auto-loaded via load_project_skills) - Inline skills (trigger=None) 2. Trigger-loaded context - KeywordTrigger for on-demand injection 3. Progressive disclosure (AgentSkills) - SKILL.md format via load_skills_from_dir - Optional triggers for both listing AND injection Reference overview pages for concepts, focus on code here. Co-authored-by: openhands <openhands@all-hands.dev>

sdk/guides/skill.mdx

Co-authored-by: Engel Nyst <engel.nyst@gmail.com>

sdk/guides/skill.mdx

Co-authored-by: Engel Nyst <engel.nyst@gmail.com>

enyst

LGTM, much better than it was, thank you!

We can iterate on details from here.

openhands-ai · 2026-01-08T23:12:55Z

Double-check (since last summary)

Addressed request: Updated the overview skills docs to reflect the AgentSkills SKILL.md format (progressive disclosure) alongside the legacy .md format.
Concise changes: Only overview/skills.mdx was changed; no unrelated edits.
Implementation verified: Cloned OpenHands/software-agent-sdk and confirmed load_skills_from_dir() supports both legacy .md and AgentSkills SKILL.md directory formats.
Pushed to remote branch: Pushed to openhands/update-skills-overview-agentskills (could not push to main due to repo rules).
Opened PR: Created draft PR: docs: update skills overview with AgentSkills SKILL.md #248

What changed

File updated: overview/skills.mdx

Clarified the two loading models:
- Always-on context (e.g., AGENTS.md)
- On-demand skills (user keyword-triggered or agent-invoked progressive disclosure)
Updated the “Triggered and optional skills” section to explicitly cover:
- Legacy/OpenHands .openhands/skills/*.md
- AgentSkills standard .openhands/skills/<skill>/SKILL.md
Expanded the example repo structure to include an AgentSkills-style skill directory (rot13-encryption/ with SKILL.md, scripts/, references/).

View full conversation

neubig requested review from enyst and xingyaoww as code owners January 6, 2026 13:19

mintlify bot deployed to staging January 6, 2026 13:20 View deployment

openhands-ai bot mentioned this pull request Jan 6, 2026

feat: Add skills example and include skill location in agent prompt OpenHands/software-agent-sdk#1599

Merged

neubig force-pushed the examples/skills-and-plugins branch from 77ecfea to 086d9fe Compare January 6, 2026 15:14

neubig changed the title ~~docs: Add guide for loading skills from disk (AgentSkills standard)~~ docs: Add guide for using skills in AgentSkills/Claude format Jan 6, 2026

mintlify bot deployed to staging January 6, 2026 15:15 View deployment

docs: Sync code blocks with agent-sdk source files

d6f3414

- Update skill-loading.mdx to use rot13-encryption skill directory name - Update pr-review.mdx workflow file Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging January 7, 2026 16:26 View deployment

xingyaoww reviewed Jan 7, 2026

View reviewed changes

sdk/guides/skill-loading.mdx Outdated Show resolved Hide resolved

Merge branch 'main' into examples/skills-and-plugins

1e163be

neubig marked this pull request as draft January 7, 2026 19:19

neubig mentioned this pull request Jan 7, 2026

Plugin 1.0 Definition OpenHands/software-agent-sdk#1440

Open

mintlify bot deployed to staging January 7, 2026 19:30 View deployment

mintlify bot deployed to staging January 7, 2026 19:33 View deployment

Merge branch 'main' into examples/skills-and-plugins

c9c328b

mintlify bot deployed to staging January 8, 2026 16:21 View deployment

xingyaoww reviewed Jan 8, 2026

View reviewed changes

sdk/guides/skill.mdx Outdated Show resolved Hide resolved

xingyaoww reviewed Jan 8, 2026

View reviewed changes

sdk/guides/skill.mdx Show resolved Hide resolved

chore: sync pr-review.mdx code block with SDK repo

0aad912

The SDK repository was renamed from agent-sdk to software-agent-sdk. This commit syncs the workflow example to match the current SDK source. Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging January 8, 2026 16:29 View deployment

Apply suggestions from code review

4ea21a6

mintlify bot deployed to staging January 8, 2026 18:10 View deployment

docs: Add note about known limitation with progressive disclosure

c6aa140

Link to issue #1646 discussing alignment with AgentSkills standard for skills without triggers. Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging January 8, 2026 19:38 View deployment

enyst reviewed Jan 8, 2026

View reviewed changes

sdk/guides/skill.mdx Outdated Show resolved Hide resolved

mintlify bot deployed to staging January 8, 2026 19:54 View deployment

openhands-agent added 2 commits January 8, 2026 19:59

docs: Add AgentSkills standard reference to skills overview

d9bd4b5

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

mintlify bot deployed to staging January 8, 2026 20:00 View deployment

mintlify bot deployed to staging January 8, 2026 20:01 View deployment

Merge branch 'main' into examples/skills-and-plugins

45c7bb7

mintlify bot deployed to staging January 8, 2026 20:06 View deployment

enyst reviewed Jan 8, 2026

View reviewed changes

sdk/guides/skill.mdx Outdated Show resolved Hide resolved

mintlify bot deployed to staging January 8, 2026 20:08 View deployment

mintlify bot deployed to staging January 8, 2026 20:11 View deployment

mintlify bot deployed to staging January 8, 2026 20:19 View deployment

xingyaoww requested a review from enyst January 8, 2026 20:22

enyst reviewed Jan 8, 2026

View reviewed changes

sdk/guides/skill.mdx Outdated Show resolved Hide resolved

Update sdk/guides/skill.mdx

455fad1

Co-authored-by: Engel Nyst <engel.nyst@gmail.com>

mintlify bot deployed to staging January 8, 2026 20:40 View deployment

enyst reviewed Jan 8, 2026

View reviewed changes

sdk/guides/skill.mdx Outdated Show resolved Hide resolved

Update sdk/guides/skill.mdx

57a786b

Co-authored-by: Engel Nyst <engel.nyst@gmail.com>

mintlify bot deployed to staging January 8, 2026 20:41 View deployment

enyst approved these changes Jan 8, 2026

View reviewed changes

xingyaoww merged commit 86cf9a0 into main Jan 8, 2026
2 checks passed

xingyaoww deleted the examples/skills-and-plugins branch January 8, 2026 22:58

docs: Add guide for using skills in AgentSkills/Claude format #238

docs: Add guide for using skills in AgentSkills/Claude format #238

Uh oh!

Conversation

neubig commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

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

Navigation Update

Code Sync

Related PRs

Checklist

Uh oh!

neubig commented Jan 7, 2026

Uh oh!

openhands-ai bot commented Jan 7, 2026

Uh oh!

openhands-ai bot commented Jan 7, 2026

Summary of Changes

Checklist

Uh oh!

Uh oh!

neubig commented Jan 7, 2026

Uh oh!

openhands-ai bot commented Jan 7, 2026

Uh oh!

openhands-ai bot commented Jan 7, 2026

Summary of Changes

What was done:

Files changed:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

enyst left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

openhands-ai bot commented Jan 8, 2026

Double-check (since last summary)

What changed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

neubig commented Jan 6, 2026 •

edited

Loading

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