OpenHands 源码解析 · 第 8 讲
OpenHands 源码解析系列 第 8 讲：Skill 系统 —— 从 .md 到 Agent 能力的管道 基于 OpenHands 源码 · 2026-07-29 一、Skill 是什么？ 在 OpenHands 中，Skill 是一段以 Markdown 文件为载体、带 YAML frontmatter 的结构化知识，Agent 在运行时会加载这些文件作为"微代理"（microagent）指令。本质上它把"怎么做"从代码中抽离到可配置的文档里。 一个 Skill 文件长什么样？以全局 SSH Skill 为例： 📄 skills/ssh.md（前 20 行） --- name: SSH Microagent type: knowledge version: 1.0.0 agent: CodeActAgent triggers: - ssh - remote server - remote machine --- # SSH Microagent This microagent provides capabilities for establishing and managing SSH connections... 核心字段： 字段 说明 类型 name Skill 名称 str type knowledge / repo / task str triggers 触发关键词列表 list[str] agent 适用 Agent 类型 str version 版本号 str 二、Skill 的四个来源 OpenHands 从四个层级加载 Skill，每个层级对应不同的作用域： Skill 加载层级 🔵 Global（全局） skills/ 目录，OpenHands 内置的 26 个 Skill 🟢 User（用户级） ~/.openhands/microagents/ 目录，用户自定义 🟡 Project（项目级） 工作区内的 .openhands/ 或 .agents/ 目录 🟠 Org / Marketplace（组织/市场） Git 仓库中的 .openhands / openhands-config 仓库 三、核心架构：两层分离 OpenHands Skill 系统的关键设计决策是 app-server 只做代理，agent-server 做实际加载 。源码中的文档字符串说得很明确： 📄 skill_loader.py（第 1-7 行） """Utilities for loading skills for V1 conversations. This module provides functions to load skills from the agent-server, which centralizes all skill loading logic. The app-server acts as a thin proxy that: 1. Builds the org_config with authentication information 2. Builds the sandbox_config with exposed URLs 3. Calls the agent-server's /api/skills endpoint All source-specific skill loading is handled by the agent-server.""" 这意味着： 🔹 app-server ：构建 org_config（认证信息）、sandbox_config（暴露的 URL），然后发 HTTP 请求到 agent-server 的 /api/skills 端点 🔹 agent-server ：真正执行 git clone、解析 frontmatter、合并所有来源的 Skill 四、Skill 加载的完整链路 4.1 入口：load_skills_from_agent_server 这是整个 Skill 加载链路的入口函数（第 618-706 行）。它接收 6 个布尔开关控制哪些来源的 Skill 需要加载： 📄 skill_loader.py（第 618-640 行） async def l…
阅读全文：OpenHands 源码解析 第 8 讲