Skip to main content
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 four primary responsibilities:
  1. Context Injection - Add specialized prompts to agent context based on triggers
  2. Trigger Evaluation - Determine when skills should activate (always, keyword, task)
  3. MCP Integration - Load MCP tools associated with repository skills
  4. Third-Party Support - Parse .cursorrules, agents.md, and other skill formats

​
Architecture

​
Key Components

ComponentPurposeDesign
SkillCore skill modelPydantic model with name, content, trigger
KeywordTriggerKeyword-based activationString matching on user messages
TaskTriggerTask-based activationSpecial type of KeywordTrigger for skills with user inputs
InputMetadataTask input parametersDefines user inputs for task skills
Skill LoaderFile parsingReads markdown with frontmatter, validates schema

​
Skill Types

​
Repository Skills

Always-active skills that provide repository-specific guidelines: Characteristics:
  • Trigger: None (always active)
  • Purpose: Project conventions, coding standards, architecture rules
  • MCP Tools: Can include MCP tool configuration
  • Location: .openhands/skills/*.md or third-party formats
Example Files:
  • .cursorrules - Cursor IDE guidelines
  • agents.md / agent.md - General agent instructions
  • Custom repo skills with frontmatter

​
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
---
Note: TaskTrigger uses the same keyword matching mechanism as KeywordTrigger. The distinction is semantic - TaskTrigger is used for skills that require structured user inputs, while KeywordTrigger is for knowledge-based skills.

​
Trigger Evaluation

Skills are evaluated at different points in the agent lifecycle: Evaluation Rules:
Trigger TypeEvaluation PointActivation Condition
NoneEvery stepAlways active
KeywordTriggerOn user messageKeyword/string match in message
TaskTriggerOn user messageKeyword/string match in message (same as KeywordTrigger)
Note: Both KeywordTrigger and TaskTrigger use identical string matching logic. TaskTrigger is simply a semantic variant used for skills that include user input parameters.

​
MCP Tool Integration

Repository skills can include MCP tool configurations: MCP Configuration Format: Skills can embed MCP server configuration following the FastMCP format: 
---
name: repo_skill
mcp_tools:
  mcpServers:
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
---
Workflow:
  1. Load Skill: Parse markdown file with frontmatter
  2. Extract MCP Config: Read mcp_tools field
  3. Spawn MCP Servers: Create MCP clients for each server
  4. Register Tools: Add MCP tools to agent’s tool registry
  5. Inject Context: Add skill content to agent prompt

​
Skill File Format

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.
Frontmatter Fields:
FieldRequiredDescription
nameYesUnique skill identifier
triggerYes*Activation trigger (null for always active)
mcp_toolsNoMCP server configuration (repo skills only)
inputsNoUser input metadata (task skills only)
*Repository skills use 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