Add Skills and Plugins documentation by juanmichelini · Pull Request #339 · OpenHands/docs

juanmichelini · 2026-02-16T19:25:25Z

Overview

This PR adds comprehensive documentation for Skills and Plugins, improving the user experience across all skill levels (new, experienced, and power users).

Changes

1. Updated Keyword Skills Example

Changed example from 'yummy' to real-world skill
Added Info callout explaining context management with platform skills (GitHub/GitLab)
Justification: Real-world examples are more useful than toy examples; helps users understand practical applications

2. Added "Adding New Skills" Page

Explains how to use the /add-skill action
Documents skill storage locations for all platforms (CLI, SDK, GUI, Cloud)
Provides examples for various URL formats
Covers manual installation, updates, and authentication
Location: overview/skills/adding.mdx (under Skills section)
Justification: Users need a clear guide on how to add existing skills before they can use them

3. Added "Creating New Skills" Page

Comprehensive guide for creating custom skills
Sections: Determining Scope, Choosing Name and Triggers, Defining Body
Best practices: Numbered step workflows, references for large files, scripts for predictable steps
Includes common mistakes and complete examples
Location: overview/skills/creating.mdx (under Skills group in Product Guides)
Justification: Instead of repeating prompts, users should learn to create reusable skills

4. Added "Creating New Skills" Page

Comprehensive guide for creating custom skills
Sections: Determining Scope, Choosing Name and Triggers, Defining Body
Best practices: Numbered step workflows, references for large files, scripts for predictable steps
Includes common mistakes and complete examples
Location: overview/skills/creating.mdx (under Skills group in Product Guides)
Justification: Instead of repeating prompts, users should learn to create reusable skills; positioned in Tips and Tricks as it's a how-to guide

4. Added Plugins Overview Page

Explains what plugins are and how they bundle multiple components
Clear comparison table: Plugins vs Skills
Details on plugin structure and components (skills, hooks, MCP, agents, commands)
Platform-specific usage instructions
Complete examples and troubleshooting
Location: overview/plugins.mdx (same level as Skills in Product Guides)
Justification: Plugins are a distinct concept from Skills; deserve their own top-level section for discoverability

5. Updated Navigation Structure

Added "Adding New Skills" to Skills section
Added "Creating New Skills" and "Monitoring" to Skills section
Added "Plugins" at same level as Skills in Product Guides
Justification: All skills-related pages grouped together for better discoverability

6. Enhanced Cross-References

Added links to new pages in Skills overview "Learn More" section
Added plugins reference in Creating Skills "Further Reading"
Bidirectional links between related pages
Justification: Improves navigation and helps users discover related content

User Flow Analysis

New Users (don't know the terms yet)

Journey: Overview → Keyword Examples → Adding Skills
✅ Clear progression with real-world examples
✅ Info callouts provide context without overwhelming

Experienced Users (trying things out, want to scratch an itch)

Journey: Direct access to Adding or Creating based on need
✅ Quick Start sections for fast action
✅ Practical examples throughout

Power Users (want to do things properly)

Journey: Creating → Plugins → SDK integration
✅ Comprehensive best practices
✅ Clear guidance on when to use each approach
✅ Links to SDK documentation for advanced usage

Tone and Style

All new content maintains consistency with existing docs:

Imperative form for instructions
Third-person in frontmatter descriptions
Practical, actionable guidance
Real-world examples over abstract concepts
Progressive disclosure (simple → advanced)

Checklist

All changes have clear justifications
Flow reviewed for three user levels
Cross-references added for better navigation
Examples use real-world scenarios
Tone consistent with existing documentation
Navigation structure updated in docs.json

- Update keyword.mdx example to use github skill instead of yummy example - Add context management note explaining github/gitlab skills triggering - Create Adding New Skills guide explaining /add-skill action and storage locations - Create Creating New Skills guide with best practices for scope, naming, triggers, and content - Create Plugins overview explaining plugin structure and comparison with skills - Update docs.json navigation to include new pages in appropriate sections - Add cross-references between related documentation pages for better user flow Co-authored-by: openhands <openhands@all-hands.dev>

- Add Tip callout in Quick Start section mentioning skill-creator - Explain that users can ask OpenHands to 'create a skill' for guided assistance - Helpful for new users learning best practices Co-authored-by: openhands <openhands@all-hands.dev>

- Move skill-creator to be the first and primary method - Present manual approach as alternative for those who prefer it - Make it clear that skill-creator is the recommended starting point - Better reflects that guided creation is simpler than manual setup Co-authored-by: openhands <openhands@all-hands.dev>

juanmichelini · 2026-03-06T16:05:04Z

@OpenHands please fix pre commit hooks

openhands-ai · 2026-03-06T16:05:28Z

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

- Add missing comma after overview/plugins on line 48 - Add missing comma after overview/skills/creating on line 59 - Resolves Mintlify broken links check failure Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2026-03-06T16:08:25Z

Summary

I've successfully fixed the pre-commit hook issues for PR #339.

What Was Wrong

The Mintlify "Check Broken Links" CI check was failing due to JSON syntax errors in docs.json. The JSON parser was unable to read the configuration file, causing the validation to fail.

Changes Made

Fixed two missing commas in docs.json:

Line 48: Added comma after "overview/plugins"
Line 59: Added comma after "overview/skills/creating"

Verification

✅ Validated JSON syntax using Python's json.tool - confirmed valid
✅ Changes are minimal and concise (only 2 commas added)
✅ Committed with descriptive message including Co-authored-by tag
✅ Pushed to add-skills-plugins-documentation branch

Next Steps

The CI checks should automatically re-run and should now pass. The Mintlify validation will be able to properly parse the docs.json file and check for broken links without errors.

neubig · 2026-03-06T19:17:05Z

@OpenHands:

does this cover all elements in the workflow described in our blog? https://openhands.dev/blog/20260227-creating-effective-agent-skills
are you able to follow the instructions to (a) use a skill, (b) create a new skill, and (c) set up monitoring for a skill on this repo: https://github.com/OpenHands/llm-support-tracker
once you have attempted to follow the instructions in 1 and 2, do a /codereview-roasted of this PR and list up things that could be improved

openhands-ai · 2026-03-06T19:17:30Z

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

openhands-ai · 2026-03-06T19:21:53Z

Final Summary

I analyzed PR #339 "Add Skills and Plugins documentation" by performing three tasks as requested:

1. Blog Post Coverage Analysis

Answer: NO - The PR does NOT cover all elements from the blog post.

The blog at https://openhands.dev/blog/20260227-creating-effective-agent-skills has a major section (~40% of content) on "Monitoring and Improving Skills" that is completely missing from the PR documentation:

Logging with OpenTelemetry/Laminar
Automatic evaluation pipelines
Dashboarding evaluation scores
Aggregating feedback for skill improvement

2. Instruction Testing on llm-support-tracker

Task	Result	Notes
(a) Use a skill	✅ PASS	Instructions are clear and actionable
(b) Create a new skill	✅ PASS	Successfully created `llm-support-review` skill with references/ and scripts/
(c) Set up monitoring	❌ FAIL	Documentation doesn't cover this - no link to SDK observability guide

3. /codereview-roasted Verdict

🔴 Needs Improvement - Critical issues found:

Missing monitoring section - The entire skill lifecycle monitoring is absent
No link to observability guide - SDK has /sdk/guides/observability.mdx but skills docs don't reference it
Duplicate nav entry in docs.json (prompting-best-practices appears twice)
Path inconsistency - ~/.agents/skills/ vs ~/.openhands/skills/ for user-level skills
Missing GitHub CI/Actions example - Blog shows this, docs don't

No code changes were made. This was an analysis/review task only. The findings should be addressed by the PR author before merging.

neubig

@juanmichelini could you look at the openhands feedback, reflect it, and run the same review prompt again and see if you get a good result?

…latives - Create dedicated monitoring.mdx page (169 lines) for production skill monitoring - 4-part workflow: logging, evaluating, dashboarding, aggregating - Practical PR review examples with actual metrics - Links to SDK observability guide and GitHub workflows - Update creating.mdx: Remove superlatives, add monitoring links - 'Easiest' → 'Automated Approach' - Added Info callout linking to monitoring page - Enhanced Further Reading with monitoring + observability links - Update plugins.mdx: Remove conversational tone - 'Think of' → direct statement - 'knowledge packages' → 'specialized prompts' - 'Easy' → 'Quick' - Update skills.mdx: Add monitoring link to Learn More section - Add DOCS_UPDATES.md: Complete change log with justifications All changes maintain technical, down-to-earth tone without superlatives. Co-authored-by: openhands <openhands@all-hands.dev>

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

- Remove 'prompting-best-practices' from Onboarding (already in Essential Guidelines) - Remove 'overview/skills/repo' from Onboarding (already in Skills group under Essential Guidelines) - Remove 'model-context-protocol' from Product Guides (already in Essential Guidelines) - Remove Skills group from Product Guides (already in Essential Guidelines) Co-authored-by: openhands <openhands@all-hands.dev>

all-hands-bot

🟡 Acceptable: Strong documentation with comprehensive coverage and good structure. Two important accuracy issues need fixing (hook event types and author field format), but overall excellent work documenting Skills and Plugins.

overview/plugins.mdx

juanmichelini · 2026-04-03T15:09:59Z

@OpenHands please address reviewers concerns and resolve conflicts too

openhands-ai · 2026-04-03T15:10:19Z

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

- resolve the docs.json merge conflict against origin/main - document both supported plugin manifest directories - correct plugin hook event names to match the SDK - document both supported plugin author formats Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2026-04-03T15:15:55Z

all-hands-bot

🟢 Good taste - Comprehensive, well-structured documentation with practical examples. One minor navigation organization question worth clarifying.

docs.json

…scoverability This change consolidates all skills-related documentation under the Skills group for better discoverability, addressing reviewer feedback about navigation organization clarity. All skills pages are now grouped together: - overview/skills (overview) - overview/skills/repo - overview/skills/keyword - overview/skills/org - overview/skills/public - overview/skills/adding - overview/skills/creating - overview/skills/monitoring

Done

all-hands-bot

🟡 Acceptable: Comprehensive documentation with good structure and real-world examples. One technical inaccuracy in hooks example needs fixing.

overview/plugins.mdx

overview/skills/creating.mdx

overview/skills/adding.mdx

Address review comment: clarify that GITHUB_TOKEN is automatically used by /add-skill command via GitHub API, and distinguish from manual git clone authentication methods like SSH keys or token in URL.

- Fix hook command template syntax: use $OPENHANDS_PROJECT_DIR instead of unsupported {file_path} syntax, document available env vars - Complete SDK example: add LLM, Agent imports and SecretStr usage - Add skill-creator context: link to public skills library

juanmichelini · 2026-04-09T15:43:22Z

All review comments have been addressed and resolved. Could you please re-review the PR?

all-hands-bot

Comprehensive documentation work with one accuracy issue that needs fixing.

overview/plugins.mdx

mintlify bot deployed to staging February 16, 2026 19:26 View deployment

mintlify bot deployed to staging February 16, 2026 20:15 View deployment

mintlify bot deployed to staging February 16, 2026 20:25 View deployment

juanmichelini requested a review from neubig February 16, 2026 20:42

juanmichelini marked this pull request as ready for review February 17, 2026 13:50

juanmichelini changed the title ~~Add comprehensive Skills and Plugins documentation~~ Add Skills and Plugins documentation Mar 3, 2026

juanmichelini added 2 commits March 5, 2026 10:55

Merge branch 'main' into add-skills-plugins-documentation

80c73db

Merge branch 'main' into add-skills-plugins-documentation

8fec845

Fix JSON syntax errors in docs.json

9d22deb

- Add missing comma after overview/plugins on line 48 - Add missing comma after overview/skills/creating on line 59 - Resolves Mintlify broken links check failure Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging March 6, 2026 16:08 View deployment

neubig previously requested changes Mar 6, 2026

View reviewed changes

juanmichelini marked this pull request as draft March 11, 2026 14:54

juanmichelini and others added 2 commits March 11, 2026 20:22

Merge monitoring documentation and style updates

e748f80

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

mintlify bot deployed to staging March 11, 2026 23:24 View deployment

Merge branch 'main' into add-skills-plugins-documentation

10d31ce

mintlify bot deployed to staging March 12, 2026 23:44 View deployment

Delete DOCS_UPDATES.md

41c007d

mintlify bot deployed to staging March 13, 2026 14:59 View deployment

Update adding.mdx

0a18c7e

mintlify bot deployed to staging March 13, 2026 15:04 View deployment

mintlify bot deployed to staging March 14, 2026 01:05 View deployment

Merge branch 'main' into add-skills-plugins-documentation

4a8f7ab

mintlify bot deployed to staging March 23, 2026 20:08 View deployment

juanmichelini requested a review from all-hands-bot April 1, 2026 20:38

all-hands-bot reviewed Apr 1, 2026

View reviewed changes

overview/plugins.mdx Outdated Show resolved Hide resolved

overview/plugins.mdx Show resolved Hide resolved

mintlify bot deployed to staging April 3, 2026 15:15 View deployment

juanmichelini requested a review from all-hands-bot April 3, 2026 15:40

all-hands-bot reviewed Apr 3, 2026

View reviewed changes

docs.json Outdated Show resolved Hide resolved

mintlify bot deployed to staging April 7, 2026 18:35 View deployment

Merge branch 'main' into add-skills-plugins-documentation

989cb48

juanmichelini requested a review from all-hands-bot April 8, 2026 19:20

mintlify bot deployed to staging April 8, 2026 19:21 View deployment

all-hands-bot reviewed Apr 8, 2026

View reviewed changes

overview/plugins.mdx Show resolved Hide resolved

overview/plugins.mdx Show resolved Hide resolved

overview/skills/creating.mdx Show resolved Hide resolved

overview/skills/adding.mdx Outdated Show resolved Hide resolved

openhands-agent added 2 commits April 9, 2026 15:40

Clarify GITHUB_TOKEN usage for private skills

bcc8f26

Address review comment: clarify that GITHUB_TOKEN is automatically used by /add-skill command via GitHub API, and distinguish from manual git clone authentication methods like SSH keys or token in URL.

mintlify bot deployed to staging April 9, 2026 15:43 View deployment

mintlify bot deployed to staging April 9, 2026 16:30 View deployment

Merge branch 'main' into add-skills-plugins-documentation

12dfcde

juanmichelini requested a review from all-hands-bot April 9, 2026 22:08

mintlify bot deployed to staging April 9, 2026 22:09 View deployment

all-hands-bot reviewed Apr 9, 2026

View reviewed changes

overview/plugins.mdx Show resolved Hide resolved

Conversation

juanmichelini commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Changes

1. Updated Keyword Skills Example

2. Added "Adding New Skills" Page

3. Added "Creating New Skills" Page

4. Added "Creating New Skills" Page

4. Added Plugins Overview Page

5. Updated Navigation Structure

6. Enhanced Cross-References

User Flow Analysis

New Users (don't know the terms yet)

Experienced Users (trying things out, want to scratch an itch)

Power Users (want to do things properly)

Tone and Style

Checklist

Uh oh!

juanmichelini commented Mar 6, 2026

Uh oh!

openhands-ai bot commented Mar 6, 2026

Uh oh!

openhands-ai bot commented Mar 6, 2026

Summary

What Was Wrong

Changes Made

Verification

Next Steps

Uh oh!

neubig commented Mar 6, 2026

Uh oh!

openhands-ai bot commented Mar 6, 2026

Uh oh!

openhands-ai bot commented Mar 6, 2026

Final Summary

1. Blog Post Coverage Analysis

2. Instruction Testing on llm-support-tracker

3. /codereview-roasted Verdict

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!

Uh oh!

juanmichelini commented Apr 3, 2026

Uh oh!

openhands-ai bot commented Apr 3, 2026

Uh oh!

openhands-ai bot commented Apr 3, 2026

Estado

Cambios nuevos realizados

Concisión de los cambios

Validación

Nota pendiente

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

juanmichelini commented Apr 9, 2026

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

juanmichelini commented Feb 16, 2026 •

edited

Loading