OpenClaw Skill 系统架构：按需加载的模块化 Agent 能力

Skill 是什么

OpenClaw 的 Skill 系统是一种按需加载的能力模块。每个 Skill 独立定义自己的 prompt、工具链和执行流程。Agent 不会一次性加载所有 Skill，而是根据当前任务精确匹配并加载最相关的一个——这避免了上下文膨胀，同时保持了能力的可扩展性。

Skill 生命周期

用户输入
    ↓
扫描 available_skills → 匹配任务描述
    ↓
读取最匹配 Skill 的 SKILL.md
    ↓
按 SKILL.md 指令执行（工具调用、API 交互、文件操作等）
    ↓
任务完成 → Skill 上下文自然退出

核心设计原则

一、职责单一（Single Responsibility）

一个 Skill 只做一件事。典型案例：email-skill 只做路由决策（判断走哪个邮箱通道），imap-smtp-email 只做执行（实际收发邮件）。路由和执行分层，互不干扰。

# email-skill/SKILL.md — 纯路由
"邮件统一入口（纯路由层），自身不执行任何脚本与接口，
 识别用户意图后用 read 工具读取下游 skill 的 SKILL.md 路由到下游。"

# imap-smtp-email/SKILL.md — 纯执行
"【内部执行层 Skill — 禁止直接调用】个人邮箱 IMAP/SMTP 执行通道。"

二、优先级覆盖

qclaw-rules 是系统级规则 Skill，优先级最高，不可被其他 Skill 覆盖。它定义了通用行为规则和标准任务执行流程，所有 Skill 都在它的约束下运行。

优先级链：
qclaw-rules (系统规则, 不可覆盖)
  └─> 功能 Skill (email-skill, xlsx, pdf, ...)
       └─> 执行层 Skill (imap-smtp-email, ...)

三、精确匹配触发

每个 Skill 在 available_skills 列表中有一段描述文本，Agent 据此判断何时触发。描述要精准——太宽泛会导致误触发，太窄会导致漏触发。

# ✅ 精准描述
"当用户提到知识库、资料库、笔记、备忘录、记事，或者想要上传文件、
 添加网页到知识库、搜索知识库内容时，使用此 skill。"

# ❌ 太宽泛
"处理用户数据相关的所有操作"

# ❌ 太窄
"仅在用户说出确切短语'上传到 ima 知识库'时触发"

Skill 安装与分发

SkillHub 是 OpenClaw 的 Skill 管理器，支持在线安装和本地 zip 安装。它会自动处理依赖环境（Python3、curl 等），无需手动配置。

# 在线安装
skillhub_install install_skill openai-whisper

# 本地 zip 安装
skillhub_install install_skill_zip /path/to/my-skill.zip

# 环境检查
skillhub_install check_env

Skill 开发要点

• SKILL.md 是唯一入口：Agent 通过读取 SKILL.md 了解 Skill 的全部能力
• 路径解析基准是 Skill 目录：SKILL.md 中写的相对路径（如 ./scripts/run.sh）相对于 Skill 目录而非工作区根目录
• 技能之间靠路由解耦：不要在一个 Skill 中硬编码调用另一个 Skill，始终通过路由层决策
• Skills 可热更新：安装或修改 Skill 后无需重启 Agent

Skill vs Function Calling vs MCP