Documentation Index
Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
Use this file to discover all available pages before exploring further.
The Skill system provides a mechanism for injecting reusable, specialized knowledge into agent context. Skills use trigger-based activation to determine when they should be included in the agent’s prompt.
Source: openhands/sdk/context/skills/
Core Responsibilities
The Skill system has five primary responsibilities:
- Context Injection - Add specialized prompts to agent context based on triggers
- Trigger Evaluation - Determine when skills should activate (always, keyword, task)
- Dynamic Content Rendering - Execute inline shell commands for dynamic context injection
- MCP Integration - Load MCP tools associated with repository skills
- Third-Party Support - Parse
.cursorrules, agents.md, and other skill formats
Architecture
Key Components
| Component | Purpose | Design |
|---|
Skill | Core skill model | Pydantic model with name, content, trigger |
KeywordTrigger | Keyword-based activation | String matching on user messages |
TaskTrigger | Task-based activation | Special type of KeywordTrigger for skills with user inputs |
InputMetadata | Task input parameters | Defines user inputs for task skills |
render_content_with_commands | Dynamic content | Executes inline !command“ patterns |
| Skill Loader | File parsing | Reads markdown with frontmatter, validates schema |
Skill Types
Repository Skills
Always-active, repository-specific guidelines.
Recommended: put these permanent instructions in AGENTS.md (and optionally GEMINI.md / CLAUDE.md) at the repo root.
Characteristics:
- Trigger:
None (always active)
- Purpose: Project conventions, coding standards, architecture rules
- MCP Tools: Can include MCP tool configuration
- Location:
AGENTS.md (recommended) and/or .agents/skills/*.md (supported)
Example Files (permanent context):
AGENTS.md - General agent instructionsGEMINI.md - Gemini-specific instructionsCLAUDE.md - Claude-specific instructions
Other supported formats:
.cursorrules - Cursor IDE guidelinesagents.md / agent.md - General agent instructions
Knowledge Skills
Keyword-triggered skills for specialized domains:
Characteristics:
- Trigger:
KeywordTrigger with regex patterns
- Purpose: Domain-specific knowledge (e.g., “kubernetes”, “machine learning”)
- Activation: Keywords detected in user messages
- Location: System or user-defined knowledge base
Trigger Example:
---
name: kubernetes
trigger:
type: keyword
keywords: ["kubernetes", "k8s", "kubectl"]
---
Task Skills
Keyword-triggered skills with structured inputs for guided workflows:
Characteristics:
- Trigger:
TaskTrigger (a special type of KeywordTrigger for skills with user inputs)
- Activation: Keywords/triggers detected in user messages (same matching logic as KeywordTrigger)
- Purpose: Guided workflows (e.g., bug fixing, feature implementation)
- Inputs: User-provided parameters (e.g., bug description, acceptance criteria)
- Location: System-defined or custom task templates
Trigger Example:
---
name: bug_fix
triggers: ["/bug_fix", "fix bug", "bug report"]
inputs:
- name: bug_description
description: "Describe the bug"
required: true
---
Trigger Evaluation
Skills are evaluated at different points in the agent lifecycle:
Evaluation Rules:
| Trigger Type | Evaluation Point | Activation Condition |
|---|
| None | Every step | Always active |
| KeywordTrigger | On user message | Keyword/string match in message |
| TaskTrigger | On user message | Keyword/string match in message (same as KeywordTrigger) |
---
name: repo_skill
mcp_tools:
mcpServers:
filesystem:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
---
- Load Skill: Parse markdown file with frontmatter
- Extract MCP Config: Read
mcp_tools field
- Spawn MCP Servers: Create MCP clients for each server
- Register Tools: Add MCP tools to agent’s tool registry
- Inject Context: Add skill content to agent prompt
Dynamic Content Rendering
Skills support inline command execution for injecting dynamic context at render time:
- Parse content for
!`cmd` patterns outside code blocks
- Execute each command via subprocess
- Replace pattern with stdout (or error marker)
- Return rendered content
Syntax:
!`command` - Executes command and replaces with stdout\!`command` - Escapes to literal !`command` text- Fenced (```) and inline (`) code blocks are never executed
Safety:
- Unclosed fenced blocks (odd ``` count) extend to EOF, protecting trailing content
- Failed commands return
[Error: ...] markers
- Output truncated at 50KB per command
See Dynamic Command Execution for usage details.
Skills are defined in markdown files with YAML frontmatter:
---
name: skill_name
trigger:
type: keyword
keywords: ["pattern1", "pattern2"]
---
# Skill Content
This is the instruction text that will be added to the agent's context.
Dynamic values: !`git branch --show-current`
| Field | Required | Description |
|---|
| name | Yes | Unique skill identifier |
| trigger | Yes* | Activation trigger (null for always active) |
| mcp_tools | No | MCP server configuration (repo skills only) |
| inputs | No | User input metadata (task skills only) |
trigger: null (or omit trigger field)
Component Relationships
How Skills Integrate
Relationship Characteristics:
- Skills → Agent Context: Active skills contribute their content to system prompt
- Skills → MCP: Repository skills can spawn MCP servers and register tools
- Context → Agent: Combined skill content becomes part of agent’s instructions
- Skills Lifecycle: Loaded at conversation start, evaluated each step
See Also
