diff --git a/docs.json b/docs.json
index 16aa34c5..901cc596 100644
--- a/docs.json
+++ b/docs.json
@@ -44,15 +44,18 @@
"overview/skills/repo",
"overview/skills/keyword",
"overview/skills/org",
- "overview/skills/public"
+ "overview/skills/public",
+ "overview/skills/adding"
]
- }
+ },
+ "overview/plugins"
]
},
{
"group": "Tips and Tricks",
"pages": [
- "openhands/usage/tips/prompting-best-practices"
+ "openhands/usage/tips/prompting-best-practices",
+ "overview/skills/creating"
]
},
{
diff --git a/overview/plugins.mdx b/overview/plugins.mdx
new file mode 100644
index 00000000..10eafda1
--- /dev/null
+++ b/overview/plugins.mdx
@@ -0,0 +1,562 @@
+---
+title: Plugins
+description: Plugins bundle multiple agent components together—skills, hooks, MCP servers, agents, and commands—into reusable packages that extend OpenHands capabilities.
+---
+
+Plugins provide a way to package and distribute multiple agent components as a single unit. Instead of managing individual skills, hooks, and configurations separately, plugins bundle everything together for easier installation and distribution.
+
+## What Are Plugins?
+
+A plugin is a directory structure that can contain:
+
+- **Skills**: Specialized knowledge and workflows
+- **Hooks**: Event handlers for tool lifecycle
+- **MCP Config**: External tool server configurations
+- **Agents**: Specialized agent definitions
+- **Commands**: Slash commands
+
+Think of plugins as "extension packs" that add a complete feature set to OpenHands in one step.
+
+
+The plugin format is compatible with the [Claude Code plugin structure](https://github.com/anthropics/claude-code/tree/main/plugins), enabling ecosystem interoperability.
+
+
+## Plugins vs Skills
+
+Understanding the difference helps you choose the right approach:
+
+
+
+ **Single-purpose knowledge packages**
+
+ - One skill = one specific capability
+ - Just a SKILL.md file (+ optional resources)
+ - Lightweight and focused
+ - Easy to create and share
+
+ **When to use:**
+ - Adding single capabilities
+ - Simple workflows
+ - Domain-specific knowledge
+ - Quick solutions
+
+
+
+ **Multi-component bundles**
+
+ - Multiple skills + hooks + config
+ - Complete feature ecosystems
+ - Coordinated components
+ - Professional distribution
+
+ **When to use:**
+ - Complete feature sets
+ - Tool integrations
+ - Team standards
+ - Commercial distributions
+
+
+
+### Comparison Table
+
+| Aspect | Skills | Plugins |
+|--------|--------|---------|
+| **Complexity** | Simple | Comprehensive |
+| **Components** | Knowledge only | Skills + hooks + MCP + commands |
+| **Use Case** | Single capability | Complete feature set |
+| **Creation** | Few minutes | Planned development |
+| **Distribution** | Copy directory | Structured package |
+| **Maintenance** | Individual files | Coordinated bundle |
+
+### When to Use Each
+
+**Use a Skill when you need:**
+- A single reusable prompt or workflow
+- Domain-specific knowledge
+- Simple automation
+- Quick solutions
+
+**Use a Plugin when you need:**
+- Multiple related skills working together
+- Event handlers (hooks) for tool actions
+- External tool integrations (MCP)
+- Complete platform integrations
+- Team or organizational standards
+
+**Example: Code Quality**
+
+*As separate skills:*
+```
+.agents/skills/
+├── python-linting/
+├── code-review/
+└── pre-commit-setup/
+```
+
+*As a plugin:*
+```
+code-quality-plugin/
+├── .plugin/plugin.json # Plugin metadata
+├── skills/
+│ ├── linting/
+│ ├── review/
+│ └── setup/
+├── hooks/hooks.json # Post-edit linting
+└── .mcp.json # Code analysis tools
+```
+
+The plugin version bundles all quality-related capabilities and automatically runs checks after file edits.
+
+## Plugin Structure
+
+A complete plugin follows this directory structure:
+
+```
+plugin-name/
+├── .plugin/
+│ └── plugin.json # Required: Plugin metadata
+├── skills/
+│ └── skill-name/
+│ └── SKILL.md # Individual skills
+├── hooks/
+│ └── hooks.json # Tool lifecycle hooks
+├── agents/
+│ └── agent-name.md # Specialized agents
+├── commands/
+│ └── command-name.md # Slash commands
+├── .mcp.json # MCP server config
+└── README.md # Documentation
+```
+
+### Required Components
+
+Only one file is required:
+
+- **`plugin-name/.plugin/plugin.json`**: Plugin metadata
+
+All other components are optional—include only what your plugin needs.
+
+### Plugin Metadata
+
+The `plugin.json` file defines your plugin:
+
+```json
+{
+ "name": "code-quality",
+ "version": "1.0.0",
+ "description": "Code quality tools and workflows",
+ "author": "your-name",
+ "license": "MIT",
+ "repository": "https://github.com/example/code-quality-plugin"
+}
+```
+
+## Plugin Components Explained
+
+
+
+ Skills in plugins work identically to standalone skills. Each skill has its own directory with a SKILL.md file:
+
+ ```
+ skills/
+ ├── linting/
+ │ ├── SKILL.md
+ │ └── scripts/
+ └── testing/
+ └── SKILL.md
+ ```
+
+ See [Skills Documentation](/overview/skills) for skill creation details.
+
+
+
+ Hooks are event handlers that run during tool lifecycle events:
+
+ ```json
+ {
+ "hooks": {
+ "PostToolUse": [
+ {
+ "matcher": "file_editor",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "ruff check {file_path}",
+ "timeout": 10
+ }
+ ]
+ }
+ ]
+ }
+ }
+ ```
+
+ **Common use cases:**
+ - Run linters after file edits
+ - Validate tool inputs
+ - Log tool usage
+ - Trigger dependent actions
+
+ **Available hook events:**
+ - `PreToolUse`: Before tool execution
+ - `PostToolUse`: After tool execution
+ - `OnError`: When tool fails
+
+
+
+ MCP (Model Context Protocol) servers provide external tools and resources:
+
+ ```json
+ {
+ "mcpServers": {
+ "fetch": {
+ "command": "uvx",
+ "args": ["mcp-server-fetch"]
+ },
+ "github": {
+ "command": "uvx",
+ "args": ["mcp-server-github"],
+ "env": {
+ "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+ }
+ }
+ }
+ }
+ ```
+
+ **Use cases:**
+ - Connect to external APIs
+ - Add specialized tools
+ - Integrate third-party services
+
+ Learn more: [Model Context Protocol](/overview/model-context-protocol)
+
+
+
+ Specialized agent definitions for specific tasks:
+
+ ```markdown
+ ---
+ name: code-reviewer
+ description: Specialized agent for code review tasks
+ ---
+
+ # Code Review Agent
+
+ This agent specializes in reviewing code according to team standards...
+ ```
+
+ Agents in plugins can use the plugin's skills and hooks automatically.
+
+
+
+ Custom slash commands for plugin functionality:
+
+ ```markdown
+ ---
+ name: /lint
+ description: Run linters on current file
+ ---
+
+ # Lint Command
+
+ Run configured linters on the current file...
+ ```
+
+ Commands provide quick access to plugin features.
+
+
+
+## Using Plugins
+
+How you use plugins depends on your platform:
+
+
+
+ **Via configuration file:**
+
+ Create `~/.openhands/config.toml`:
+ ```toml
+ [plugins]
+ sources = [
+ "/path/to/local/plugin",
+ "github:org/plugin-repo",
+ ]
+ ```
+
+ **Via command line:**
+ ```bash
+ openhands --plugin /path/to/plugin
+ openhands --plugin github:org/plugin-repo
+ ```
+
+ Plugins are loaded when OpenHands starts.
+
+
+
+ Load plugins programmatically:
+
+ ```python
+ from openhands.sdk import Conversation
+ from openhands.sdk.plugin import PluginSource
+
+ plugins = [
+ PluginSource(source="/path/to/plugin"),
+ PluginSource(source="github:org/repo", ref="v1.0.0"),
+ ]
+
+ conversation = Conversation(
+ agent=agent,
+ plugins=plugins,
+ )
+ ```
+
+ See [SDK Plugins Guide](/sdk/guides/plugins) for details.
+
+
+
+ **Via UI:**
+ 1. Open Settings
+ 2. Navigate to Plugins section
+ 3. Add plugin path or GitHub URL
+ 4. Restart to load
+
+ **Via file system:**
+ Place plugins in `.openhands/plugins/` in your workspace.
+
+
+
+ **Via Cloud UI:**
+ 1. Navigate to Workspace Settings
+ 2. Select Plugins tab
+ 3. Browse plugin library or add custom plugin
+ 4. Click "Enable" to activate
+
+ Organization admins can publish plugins for team-wide access.
+
+
+
+## Installing Plugins
+
+### From a Local Directory
+
+1. **Verify plugin structure**:
+ ```bash
+ ls plugin-dir/.plugin/plugin.json
+ ```
+
+2. **Use the plugin path** in your configuration or command line
+
+### From GitHub
+
+Plugins can be loaded directly from GitHub repositories:
+
+```
+github:OpenHands/example-plugin
+github:org/repo/path/to/plugin # For monorepos
+github:org/repo#branch-name # Specific branch
+github:org/repo#v1.0.0 # Specific tag
+```
+
+### Plugin Sources
+
+
+
+ [github.com/OpenHands/extensions](https://github.com/OpenHands/extensions)
+
+ Community-maintained plugins
+
+
+
+ Your own GitHub repositories
+
+ Organization or private plugins
+
+
+
+## Creating Plugins
+
+To create your own plugin:
+
+### 1. Plan Your Components
+
+Determine what your plugin needs:
+- Which skills?
+- What hooks for automation?
+- Any MCP integrations?
+- Custom commands?
+
+### 2. Create Directory Structure
+
+```bash
+mkdir -p my-plugin/.plugin
+mkdir -p my-plugin/skills
+mkdir -p my-plugin/hooks
+```
+
+### 3. Create Plugin Metadata
+
+Create `my-plugin/.plugin/plugin.json`:
+```json
+{
+ "name": "my-plugin",
+ "version": "0.1.0",
+ "description": "My custom plugin",
+ "author": "Your Name"
+}
+```
+
+### 4. Add Components
+
+Add skills, hooks, and other components as needed:
+
+```
+my-plugin/
+├── .plugin/plugin.json
+├── skills/
+│ └── my-skill/
+│ └── SKILL.md
+└── hooks/
+ └── hooks.json
+```
+
+### 5. Test Locally
+
+Load your plugin and verify all components work:
+
+```bash
+openhands --plugin /path/to/my-plugin
+```
+
+### 6. Distribute
+
+Options for distribution:
+- **GitHub repository**: Push to GitHub and share URL
+- **File sharing**: Zip and share directory
+- **Package registry**: Submit to official registry
+
+## Plugin Examples
+
+
+
+ **Contains:**
+ - Python linting skill
+ - JavaScript linting skill
+ - Post-edit hooks for auto-linting
+ - Pre-commit setup
+
+ **Use case:** Enforce code standards
+
+
+
+ **Contains:**
+ - Kubernetes deployment skill
+ - Docker build skill
+ - CI/CD workflow skill
+ - kubectl MCP server
+
+ **Use case:** Infrastructure management
+
+
+
+ **Contains:**
+ - REST API client skill
+ - Authentication skill
+ - Rate limiting hooks
+ - API MCP server
+
+ **Use case:** External service integration
+
+
+
+ **Contains:**
+ - Unit testing skill
+ - Integration testing skill
+ - Post-code hooks for test runs
+ - Coverage commands
+
+ **Use case:** Automated testing
+
+
+
+## Plugin Development Best Practices
+
+
+
+ Begin by creating the core skills your plugin needs. Test them individually before bundling.
+
+
+
+ Identify repetitive tasks and automate them with hooks. Example: run linters after file edits.
+
+
+
+ Add MCP servers for external tool integration. This provides your skills with additional capabilities.
+
+
+
+ Include a comprehensive README explaining:
+ - What the plugin does
+ - How to install it
+ - Configuration options
+ - Example usage
+
+
+
+ Use semantic versioning (major.minor.patch) and document breaking changes.
+
+
+
+## Troubleshooting
+
+
+
+ **Check:**
+ - `.plugin/plugin.json` exists and is valid JSON
+ - Plugin path is correct
+ - All referenced files exist
+
+ **Debug:**
+ ```bash
+ # Verify structure
+ ls -la plugin-name/.plugin/plugin.json
+
+ # Check JSON syntax
+ cat plugin-name/.plugin/plugin.json | python -m json.tool
+ ```
+
+
+
+ **Check:**
+ - Skills have valid SKILL.md files
+ - Frontmatter includes `triggers`
+ - Trigger keywords match your prompts
+
+ **Test:**
+ Use explicit trigger keywords from the skill's frontmatter.
+
+
+
+ **Check:**
+ - `hooks/hooks.json` syntax is valid
+ - Hook matchers target the right tools
+ - Commands are executable
+
+ **Debug:**
+ Check logs for hook execution errors.
+
+
+
+## Next Steps
+
+- **[Learn about Skills](/overview/skills)** - Understand the core component of plugins
+- **[Explore MCP](/overview/model-context-protocol)** - Add external tool integrations
+- **[SDK Plugins Guide](/sdk/guides/plugins)** - Programmatic plugin usage
+- **[Browse Examples](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/02_loading_plugins/example_plugins)** - See complete plugin structures
+
+## Further Reading
+
+For SDK developers:
+- **[SDK Plugins Documentation](/sdk/guides/plugins)** - Detailed SDK integration
+- **[Hooks Guide](/sdk/guides/hooks)** - Event handler details
+- **[MCP Integration](/sdk/guides/mcp)** - External tool servers
diff --git a/overview/skills.mdx b/overview/skills.mdx
index 249ebbb3..a71183a0 100644
--- a/overview/skills.mdx
+++ b/overview/skills.mdx
@@ -133,6 +133,9 @@ Each skill file may include frontmatter that provides additional information. In
## Learn More
+- **To add existing skills**: See [Adding New Skills](/overview/skills/adding)
+- **To create your own skills**: See [Creating New Skills](/overview/skills/creating)
+- **For bundling multiple components**: See [Plugins](/overview/plugins)
- **For SDK integration**: See [SDK Skills Guide](/sdk/guides/skill)
- **For architecture details**: See [Skills Architecture](/sdk/arch/skill)
- **For specific skill types**: See [Repository Skills](/overview/skills/repo), [Keyword Skills](/overview/skills/keyword), [Organization Skills](/overview/skills/org), and [Global Skills](/overview/skills/public)
\ No newline at end of file
diff --git a/overview/skills/adding.mdx b/overview/skills/adding.mdx
new file mode 100644
index 00000000..3874ccea
--- /dev/null
+++ b/overview/skills/adding.mdx
@@ -0,0 +1,210 @@
+---
+title: Adding New Skills
+description: Learn how to add existing skills to your OpenHands workspace from the official registry or custom repositories.
+---
+
+OpenHands makes it easy to extend your agent's capabilities by adding pre-built skills from the community or custom repositories. Skills can be added globally (available in all conversations) or to specific projects.
+
+## Using the Add-Skill Action
+
+The quickest way to add a skill is using the `/add-skill` command in your conversation with OpenHands. This command fetches skills from GitHub repositories and installs them in your workspace.
+
+### Basic Usage
+
+Simply provide a GitHub URL pointing to a skill:
+
+```
+/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview
+```
+
+OpenHands will:
+1. Parse the URL to identify the repository and skill path
+2. Fetch the skill files from GitHub
+3. Install the skill in `.agents/skills/` directory
+4. Verify the installation
+5. Make the skill immediately available
+
+### Supported URL Formats
+
+The `/add-skill` command accepts various GitHub URL formats:
+
+- Full GitHub tree URL: `https://github.com/OpenHands/extensions/tree/main/skills/codereview`
+- Repository path: `https://github.com/OpenHands/extensions/skills/codereview`
+- Short form: `github.com/OpenHands/extensions/skills/codereview`
+- Shorthand: `OpenHands/extensions/skills/codereview`
+
+### Examples
+
+Add the code review skill:
+```
+/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview-roasted
+```
+
+Add the Kubernetes skill:
+```
+/add-skill OpenHands/extensions/skills/kubernetes
+```
+
+Add a skill from a custom repository:
+```
+/add-skill https://github.com/your-org/your-repo/tree/main/custom-skills/analytics
+```
+
+## Skill Storage Locations
+
+Skills are stored in different locations depending on the platform and scope:
+
+
+
+ The CLI supports two skill locations:
+
+ **User-level skills** (global, available in all conversations):
+ ```
+ ~/.openhands/skills/
+ ```
+
+ **Project-level skills** (specific to current directory):
+ ```
+ .agents/skills/
+ ```
+
+ Skills added via `/add-skill` are installed in `.agents/skills/` of your current workspace, making them available for that project.
+
+ To add skills globally, manually place skill directories in `~/.openhands/skills/`.
+
+
+
+ SDK users programmatically load skills:
+
+ ```python
+ from openhands.sdk import Skill
+
+ # Load from a directory
+ skill = Skill.load("/path/to/skill")
+
+ # Load all skills from a directory
+ skills = Skill.load_all("/path/to/skills")
+ ```
+
+ See the [SDK Skills Guide](/sdk/guides/skill) for more details.
+
+
+
+ Skills are stored in:
+ ```
+ .agents/skills/
+ ```
+
+ The GUI provides a visual interface for managing skills, but skills can also be added manually by placing them in this directory.
+
+
+
+ OpenHands Cloud provides a centralized skill library accessible through the web interface. Skills can be:
+ - Added from the official registry with one click
+ - Imported from your connected repositories
+ - Shared across your team or organization
+
+ See the [Cloud UI documentation](/openhands/usage/cloud/cloud-ui) for details.
+
+
+
+## Manual Installation
+
+You can also manually install skills by copying skill directories into the appropriate location.
+
+### For Project-Level Skills
+
+1. Create the skills directory if it doesn't exist:
+ ```bash
+ mkdir -p .agents/skills
+ ```
+
+2. Copy or clone the skill directory:
+ ```bash
+ # Using git
+ git clone https://github.com/OpenHands/extensions temp-clone
+ cp -r temp-clone/skills/codereview .agents/skills/
+ rm -rf temp-clone
+
+ # Or download and extract manually
+ ```
+
+3. Verify the skill structure:
+ ```bash
+ ls .agents/skills/codereview/SKILL.md
+ ```
+
+### For User-Level Skills (CLI Only)
+
+1. Create the global skills directory:
+ ```bash
+ mkdir -p ~/.openhands/skills
+ ```
+
+2. Add skills to this directory:
+ ```bash
+ cp -r /path/to/skill ~/.openhands/skills/
+ ```
+
+Skills in `~/.openhands/skills/` are available in all your conversations when using the CLI.
+
+## Verifying Installation
+
+After adding a skill, verify it's available:
+
+1. **Check the file exists**: The skill directory should contain at least a `SKILL.md` file
+ ```bash
+ ls .agents/skills/your-skill/SKILL.md
+ ```
+
+2. **Test the trigger**: For keyword-triggered skills, use one of the trigger words in your prompt:
+ ```
+ Help me set up kubernetes
+ ```
+
+3. **Check skill loading**: OpenHands will indicate when a skill is loaded in response to your prompt
+
+## Skill Updates
+
+To update a skill to the latest version:
+
+1. **Remove the old version**:
+ ```bash
+ rm -rf .agents/skills/skill-name
+ ```
+
+2. **Add the updated version**:
+ ```
+ /add-skill https://github.com/OpenHands/extensions/tree/main/skills/skill-name
+ ```
+
+Or manually pull updates if you cloned the skill repository.
+
+## Authentication for Private Skills
+
+If you need to add skills from private repositories:
+
+1. **Set GITHUB_TOKEN**: Ensure the `GITHUB_TOKEN` environment variable is set with a token that has access to the private repository
+
+2. **Use the same `/add-skill` command**: The command will automatically use the token for authentication
+
+```bash
+export GITHUB_TOKEN=your_github_token
+```
+
+Then use `/add-skill` as normal with private repository URLs.
+
+## Skill Conflicts
+
+If a skill with the same name already exists, OpenHands will warn you before overwriting. To resolve conflicts:
+
+1. **Rename the existing skill**: Move or rename the existing skill directory
+2. **Choose a different installation location**: Install at user-level vs project-level
+3. **Overwrite**: Confirm the overwrite when prompted
+
+## Next Steps
+
+- **[Browse available skills](https://github.com/OpenHands/extensions)** in the official registry
+- **[Create your own skills](/overview/skills/creating)** for custom workflows
+- **[Learn about keyword triggers](/overview/skills/keyword)** to make skills activate automatically
+- **[Understand skill structure](/sdk/guides/skill)** for the AgentSkills format
diff --git a/overview/skills/creating.mdx b/overview/skills/creating.mdx
new file mode 100644
index 00000000..49a53297
--- /dev/null
+++ b/overview/skills/creating.mdx
@@ -0,0 +1,532 @@
+---
+title: Creating New Skills
+description: Learn how to create reusable skills instead of repeating prompts, with best practices for structure, triggers, and content organization.
+---
+
+Instead of repeating the same prompts or instructions in every conversation, create a skill that OpenHands can load automatically when needed. Skills transform one-time prompts into reusable, maintainable knowledge that improves over time.
+
+## Why Create Skills?
+
+**Before (repeating yourself):**
+```
+Please analyze this code using our company's Python style guide:
+- Use black for formatting
+- Max line length 88
+- Use type hints for all functions
+- Follow PEP 8 naming conventions
+...
+```
+
+**After (using a skill):**
+```
+Review this Python code
+```
+
+The skill triggers automatically and applies all your style guidelines consistently.
+
+## When to Create a Skill
+
+Create a skill when you find yourself:
+
+- Repeating the same instructions across multiple conversations
+- Working with domain-specific knowledge (company policies, API schemas, workflows)
+- Using the same multi-step procedures repeatedly
+- Needing consistent behavior for specific tools or frameworks
+- Sharing best practices across a team
+
+## Quick Start
+
+### Easiest Way: Let OpenHands Help
+
+The simplest way to create a skill is to ask OpenHands to help you:
+
+```
+Create a skill for [your use case]
+```
+
+or simply:
+
+```
+Write a new skill
+```
+
+The `skill-creator` skill will guide you through an interactive process:
+- Asks questions about your use cases and requirements
+- Suggests appropriate skill structure (references, scripts, assets)
+- Helps you write effective trigger keywords and descriptions
+- Ensures you follow best practices automatically
+- Creates the complete skill structure for you
+
+This is the recommended approach, especially when you're starting out.
+
+### Manual Approach
+
+If you prefer to create the skill structure manually:
+
+1. **Create the skill directory**:
+ ```bash
+ mkdir -p .agents/skills/my-skill
+ ```
+
+2. **Create the SKILL.md file**:
+ ```bash
+ touch .agents/skills/my-skill/SKILL.md
+ ```
+
+3. **Add content** (see structure and guidelines below)
+
+4. **Test it** by using a trigger keyword in your prompt
+
+## Determining Scope
+
+Before writing your skill, define its scope clearly:
+
+### Ask These Questions
+
+1. **What specific task does this skill handle?**
+ - ❌ Too broad: "Help with coding"
+ - ✅ Focused: "Lint Python code using ruff with our company rules"
+
+2. **What knowledge is required?**
+ - Code style guidelines
+ - API documentation
+ - Domain-specific schemas
+ - Multi-step procedures
+
+3. **What resources are needed?**
+ - Scripts for deterministic tasks
+ - Reference documents for detailed information
+ - Asset files for templates or boilerplate
+
+4. **Who will use this skill?**
+ - Just you (keep it simple)
+ - Your team (add more documentation)
+ - Public sharing (comprehensive examples)
+
+### Scope Examples
+
+**Good scope (focused):**
+- "Configure pre-commit hooks for Python projects"
+- "Generate financial reports using our SQL schema"
+- "Deploy to our Kubernetes staging environment"
+
+**Poor scope (too broad):**
+- "Help with Python"
+- "Work with databases"
+- "Deploy applications"
+
+## Choosing Name and Triggers
+
+The skill name and trigger keywords determine when OpenHands loads your skill.
+
+### Naming Your Skill
+
+Choose a clear, descriptive name:
+
+- **Use lowercase with hyphens**: `python-linting`, `k8s-deploy`, `api-docs`
+- **Be specific**: `ruff-linter` not just `linter`
+- **Match common terms**: Use vocabulary your users know
+
+### Defining Triggers
+
+Triggers are keywords that automatically activate your skill. Choose words users naturally say when they need this skill.
+
+
+
+ List specific words or phrases that should activate the skill:
+
+ ```yaml
+ ---
+ name: python-linting
+ description: This skill should be used when the user asks to "lint Python code", "check Python style", "run ruff", or mentions Python code quality.
+ triggers:
+ - lint
+ - linting
+ - ruff
+ - code quality
+ ---
+ ```
+
+ **Best practices:**
+ - Include 2-5 trigger keywords
+ - Use terms users actually say
+ - Include tool names (e.g., "ruff", "pytest")
+ - Include action words (e.g., "lint", "test", "deploy")
+
+
+
+ The skill description is crucial for trigger matching. Write it in third person and include specific phrases:
+
+ ```yaml
+ description: This skill should be used when the user asks to "deploy to Kubernetes", "apply K8s manifests", "check pod status", or mentions kubectl commands. Provides comprehensive Kubernetes deployment workflows.
+ ```
+
+ **Key elements:**
+ - Start with "This skill should be used when..."
+ - Quote specific user phrases: "deploy to Kubernetes"
+ - List concrete scenarios
+ - Mention related tools or frameworks
+
+
+
+### Examples of Good Triggers
+
+```yaml
+# API integration skill
+triggers:
+- stripe
+- payment
+- checkout
+```
+
+```yaml
+# Database skill
+triggers:
+- bigquery
+- sql query
+- data warehouse
+```
+
+```yaml
+# Deployment skill
+triggers:
+- deploy
+- kubernetes
+- k8s
+- kubectl
+```
+
+## Defining the Skill Body
+
+The skill body contains the instructions OpenHands will follow. Write in imperative form (command form) rather than second person.
+
+### Basic Structure
+
+```markdown
+---
+name: skill-name
+description: This skill should be used when...
+triggers:
+- keyword1
+- keyword2
+---
+
+# Skill Title
+
+Brief overview of what this skill does.
+
+## Core Instructions
+
+Main procedures and guidelines.
+
+## Common Patterns
+
+Typical use cases and solutions.
+
+## Additional Resources
+
+(Optional) References to bundled files.
+```
+
+### Writing Style
+
+**Use imperative/infinitive form:**
+✅ "Check the configuration file"
+✅ "Validate input before processing"
+✅ "Run tests after deployment"
+
+**Avoid second person:**
+❌ "You should check the configuration"
+❌ "You need to validate input"
+❌ "You must run tests"
+
+### Keep It Focused
+
+**SKILL.md content:**
+- Core concepts and workflows (1,500-2,000 words ideal)
+- Essential procedures
+- Quick reference information
+- Pointers to additional resources
+
+**What NOT to include:**
+- Exhaustive API documentation (use `references/` instead)
+- Detailed edge cases (use `references/` instead)
+- Long examples (use `references/` instead)
+
+## Best Practices and Tips
+
+### Use Numbered Step Workflows
+
+For multi-step procedures, use numbered lists:
+
+```markdown
+## Deployment Workflow
+
+1. **Validate the configuration**:
+ ```bash
+ kubectl apply --dry-run=client -f deployment.yaml
+ ```
+
+2. **Apply to staging**:
+ ```bash
+ kubectl apply -f deployment.yaml -n staging
+ ```
+
+3. **Verify pod status**:
+ ```bash
+ kubectl get pods -n staging --watch
+ ```
+
+4. **Check logs**:
+ ```bash
+ kubectl logs -f deployment/app-name -n staging
+ ```
+```
+
+**Benefits:**
+- Clear sequence for complex workflows
+- Easy to follow and verify
+- Reduces errors from skipped steps
+
+### Add Large Files as References
+
+Keep SKILL.md lean by moving detailed content to `references/`:
+
+```
+my-skill/
+├── SKILL.md # Core instructions (< 3,000 words)
+└── references/
+ ├── api-docs.md # Detailed API reference
+ ├── examples.md # Comprehensive examples
+ └── troubleshooting.md # Edge cases and fixes
+```
+
+**In SKILL.md, reference these files:**
+
+```markdown
+## Additional Resources
+
+For detailed information, see:
+- **`references/api-docs.md`** - Complete API documentation
+- **`references/examples.md`** - Working code examples
+- **`references/troubleshooting.md`** - Common issues and solutions
+```
+
+**Benefits:**
+- Keeps context window smaller when skill loads
+- OpenHands reads references only when needed
+- Easier to maintain and update specific sections
+
+### Create Scripts for Predictable Steps
+
+For tasks that are repeatedly rewritten or need deterministic behavior, create executable scripts:
+
+```
+my-skill/
+├── SKILL.md
+└── scripts/
+ ├── validate_config.py
+ ├── deploy.sh
+ └── rollback.sh
+```
+
+**When to use scripts:**
+- Same code being rewritten repeatedly
+- Deterministic reliability required
+- Complex parsing or validation
+- Multi-step automation
+
+**Reference scripts in SKILL.md:**
+
+```markdown
+## Validation
+
+Run the validation script:
+
+\`\`\`bash
+python3 scripts/validate_config.py config.yaml
+\`\`\`
+
+This checks:
+- YAML syntax
+- Required fields
+- Value constraints
+```
+
+**Benefits:**
+- Token efficient (scripts can run without being read)
+- Deterministic behavior
+- Reusable across projects
+- Can be versioned and tested
+
+### Include Quick Reference Tables
+
+Use tables for configuration options, command flags, or status codes:
+
+```markdown
+## Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `timeout` | 30s | Maximum wait time |
+| `retries` | 3 | Number of retry attempts |
+| `env` | production | Target environment |
+```
+
+### Provide Concrete Examples
+
+Show real examples, not abstract descriptions:
+
+```markdown
+## Example Usage
+
+Deploy the web application:
+
+\`\`\`bash
+# Build the image
+docker build -t myapp:v1.0 .
+
+# Push to registry
+docker push registry.example.com/myapp:v1.0
+
+# Update Kubernetes deployment
+kubectl set image deployment/web web=registry.example.com/myapp:v1.0
+\`\`\`
+```
+
+### Use Progressive Disclosure
+
+Structure information from simple to complex:
+
+1. **SKILL.md**: Essential workflows and core concepts
+2. **references/**: Detailed patterns, advanced techniques, edge cases
+3. **scripts/**: Automation for predictable tasks
+4. **assets/**: Templates and boilerplate files
+
+## Complete Example
+
+Here's a complete skill for Python code review:
+
+```
+python-review/
+├── SKILL.md
+├── references/
+│ ├── style-guide.md
+│ └── common-issues.md
+└── scripts/
+ └── run-checks.sh
+```
+
+**SKILL.md:**
+```markdown
+---
+name: python-review
+description: This skill should be used when the user asks to "review Python code", "check Python style", "lint Python", or requests code quality analysis. Provides comprehensive Python code review workflows.
+triggers:
+- python review
+- code review
+- lint python
+- black
+- ruff
+---
+
+# Python Code Review
+
+Review Python code using company standards and best practices.
+
+## Review Workflow
+
+1. **Run automated checks**:
+ \`\`\`bash
+ scripts/run-checks.sh
+ \`\`\`
+
+2. **Review linter output** for:
+ - Style violations (Black, Ruff)
+ - Type errors (mypy)
+ - Security issues (bandit)
+
+3. **Check code structure**:
+ - Function length (< 50 lines)
+ - Complexity (< 10 cyclomatic)
+ - Naming conventions
+
+4. **Verify tests**:
+ \`\`\`bash
+ pytest tests/ --cov=src --cov-report=term
+ \`\`\`
+
+## Style Guidelines
+
+- **Formatting**: Black with 88-character line limit
+- **Linting**: Ruff with company config
+- **Types**: Full type hints for public APIs
+- **Docstrings**: Google style for all public functions
+
+## Additional Resources
+
+- **`references/style-guide.md`** - Complete style guide
+- **`references/common-issues.md`** - Common mistakes and fixes
+- **`scripts/run-checks.sh`** - Automated quality checks
+```
+
+## Testing Your Skill
+
+After creating your skill:
+
+1. **Verify structure**:
+ ```bash
+ ls .agents/skills/your-skill/SKILL.md
+ ```
+
+2. **Check frontmatter**: Ensure YAML is valid with `name`, `description`, and `triggers`
+
+3. **Test trigger keywords**: Use a trigger word in a prompt:
+ ```
+ Help me lint this Python code
+ ```
+
+4. **Verify loading**: OpenHands should indicate the skill was loaded
+
+5. **Iterate**: Improve based on actual usage
+
+## Common Mistakes to Avoid
+
+
+**Mistake 1: Vague triggers**
+❌ `description: Helps with Python`
+✅ `description: This skill should be used when the user asks to "lint Python code", "run black", or mentions Python code quality`
+
+
+
+**Mistake 2: Everything in SKILL.md**
+❌ Single 10,000-word SKILL.md
+✅ Focused SKILL.md (2,000 words) + references/ for details
+
+
+
+**Mistake 3: Using "you" in instructions**
+❌ "You should validate the config"
+✅ "Validate the config"
+
+
+
+**Mistake 4: Missing examples**
+❌ Abstract descriptions only
+✅ Concrete examples with actual commands
+
+
+## Next Steps
+
+- **[Add your skill](/overview/skills/adding)** to your workspace
+- **[Share skills](https://github.com/OpenHands/extensions)** with the community
+- **[Learn the AgentSkills format](/sdk/guides/skill)** for advanced features
+- **[Explore example skills](https://github.com/OpenHands/extensions)** for inspiration
+
+## Further Reading
+
+For advanced skill creation techniques and SDK integration:
+- **[Plugins](/overview/plugins)** - Bundle multiple skills with hooks and MCP config
+- **[SDK Skills Guide](/sdk/guides/skill)** - Programmatic skill creation
+- **[Skills Architecture](/sdk/arch/skill)** - Technical details
+- **[Official Skill Registry](https://github.com/OpenHands/extensions)** - Community examples
diff --git a/overview/skills/keyword.mdx b/overview/skills/keyword.mdx
index 6526c467..dd829cd3 100644
--- a/overview/skills/keyword.mdx
+++ b/overview/skills/keyword.mdx
@@ -21,15 +21,31 @@ Enclose the frontmatter in triple dashes (---) and include the following fields:
## Example
-Keyword-triggered skill file example located at `.agents/skills/yummy.md`:
-```
+Here's a simplified example of the `github` skill located at `.agents/skills/github/SKILL.md`:
+
+```markdown
---
+name: github
+description: Interact with GitHub repositories, pull requests, issues, and workflows using the GITHUB_TOKEN environment variable and GitHub CLI. Use when working with code hosted on GitHub or managing GitHub resources.
triggers:
-- yummyhappy
-- happyyummy
+- github
+- git
---
-The user has said the magic word. Respond with "That was delicious!"
+You have access to an environment variable, `GITHUB_TOKEN`, which allows you to interact with
+the GitHub API.
+
+
+You can use `curl` with the `GITHUB_TOKEN` to interact with GitHub's API.
+ALWAYS use the GitHub API for operations instead of a web browser.
+ALWAYS use the `create_pr` tool to open a pull request
+
+
+... (additional GitHub-specific instructions)
```
-[See examples of keyword-triggered skills in the official OpenHands Skills Registry](https://github.com/OpenHands/extensions)
+
+**Context Management with Platform Skills**: OpenHands includes specialized skills for platforms like GitHub and GitLab that are only triggered when needed (e.g., when you mention "github" or "gitlab" in your prompt). This keeps your context clean and focused, loading platform-specific guidance only when working with those services.
+
+
+[See more examples of keyword-triggered skills in the official OpenHands Skills Registry](https://github.com/OpenHands/extensions)