OpenClaw Skills 系统全解
OpenClaw 学习笔记
一、Skills 系统设计理念
OpenClaw 的 Skills 系统是其核心扩展机制，旨在为 AI Agent 提供可复用、可组合、可动态加载的行为模块。每个 Skill 封装了一组特定的指令、知识和行为模式，使 Agent 能够在特定场景中展现出专业能力。
1.1 设计动机
传统 AI Agent 面临以下挑战：
- 上下文窗口限制：所有指令和知识同时注入会迅速填满上下文窗口
- 知识组织混乱：不同领域的知识混杂在一起，难以维护
- 复用性差：相似的指令在不同场景中重复编写
- 触发条件僵化：缺乏灵活的按需激活机制
Skills 系统正是为解决这些问题而生。它将知识、指令和行为模式封装为独立的模块（Skill），通过优先级、触发条件和按需加载策略，实现高效的资源利用和灵活的 Agent 行为控制。
核心目标：在有限的上下文窗口中，让 Agent 始终拥有最相关的知识和指令，同时保持系统的可扩展性和可维护性。
1.2 核心架构
Skills 系统的架构分为三层：
- 定义层：SKILL.md 文件 — 每个 Skill 的定义和内容载体
- 管理层：优先级系统 + 加载策略 — 决定何时加载哪些 Skill
- 触发层：触发机制 — 决定 Skill 在什么条件下被激活
SKILL.md 定义
→
优先级排序
→
摘要注入
→
按需读取
→
触发执行
二、SKILL.md 文件格式规范
每个 Skill 由一个 SKILL.md 文件定义，该文件包含 Skill 的元信息、描述和具体指令。文件采用 Markdown 格式，通过特定的 front matter 结构声明元数据。
2.1 文件结构
name: skill-name
description: Brief description of the skill (used for summary injection)
trigger: keyword1, keyword2, pattern:regex
schedule: cron expression or interval
priority: 1-6
Detailed instructions, knowledge, and behavior definitions go here.
- Overview
- Instructions
- Examples
- Notes
2.2 Front Matter 字段说明
| 字段 | 必填 | 说明 |
|---|
name | 是 | Skill 的唯一标识名，用于引用和调试 |
description | 是 | 简要描述，用于摘要注入阶段向 Agent 介绍此 Skill 的用途 |
trigger | 否 | 触发条件，支持关键词匹配和正则表达式模式 |
schedule | 否 | 定时计划，使用 cron 表达式或时间间隔 |
priority | 否 | 优先级等级，取值范围 1-6（默认取决于存放位置） |
最佳实践
description 字段应精准概括 Skill 的功能，因为它是摘要注入时唯一可见的内容。Agent 通过 description 判断是否需要进一步读取完整的 SKILL.md 文件。
2.3 文件存放位置
SKILL.md 文件存放在以下目录结构中，位置决定了其默认优先级：
.claude/skills/
├── extra/
├── bundled/
├── managed/
├── personal/
├── project/
└── workspace/
三、6 级优先级加载机制
Skills 系统采用 6 级优先级机制，从低到高依次排列。高优先级的 Skill 在加载和匹配时拥有更高的权重，当多个 Skill 对同一场景都有定义时，高优先级者胜出。
1
extra
2
bundled
3
managed
4
personal
5
project
6
workspace
3.1 各层级详解
Level 1 — extra（最低优先级）
存放来自外部插件或社区贡献的 Skill。这些 Skill 未被官方审核，质量参差不齐。适合实验性的功能或临时辅助工具。
- 位置：
.claude/skills/extra/
- 来源：第三方插件、社区贡献
- 特点：可被所有更高优先级覆盖
Level 2 — bundled
OpenClaw 官方内置的 Skill 集，随 OpenClaw 安装包一起发布。覆盖通用场景如代码审查、安全审查、初始化等基础操作。
- 位置：
.claude/skills/bundled/
- 来源：OpenClaw 官方发布
- 特点：稳定可靠，覆盖广泛的基础场景
Level 3 — managed
由插件管理器（plugin manager）安装和管理的 Skill。当用户通过 /plugin 命令安装插件时，插件自带的 Skill 会放置在此目录。
- 位置：
.claude/skills/managed/
- 来源：通过插件管理器安装
- 特点：可自动更新，插件生态的核心
Level 4 — personal
用户个人偏好的 Skill，存放于用户全局配置目录（如 ~/.claude/skills/personal/）。适用于跨项目通用的个人工作流定义。
- 位置：
~/.claude/skills/personal/（全局）
- 来源：用户自行编写
- 特点：全局生效，跨项目可用
Level 5 — project
项目级别的 Skill，存放于项目根目录的 .claude/skills/project/ 下。适用于为特定项目定制的专属技能，如项目的构建、测试、部署流程等。
- 位置：
.claude/skills/project/（项目内）
- 来源：项目开发者
- 特点：仅对当前项目生效，可团队共享
Level 6 — workspace（最高优先级）
工作区级别的 Skill，存放于当前工作区目录的 .claude/skills/workspace/ 下。优先级最高，可覆盖所有其他层级的同名 Skill。适合临时调试或高度定制化的场景。
- 位置：
.claude/skills/workspace/（工作区内）
- 来源：当前会话/工作区
- 特点：最高优先级，用于调试或紧急覆盖
覆盖规则：当多个层级的 SKILL.md 文件同名时，高优先级的文件完全覆盖低优先级的文件。这是一种"整体替换"而非"合并"的策略。因此，workspace 级别的同名 Skill 会完全替代 extra 级别的同名 Skill。
3.2 加载顺序
在启动时，系统按照优先级从低到高（extra 到 workspace）依次扫描所有 SKILL.md 文件，提取 front matter 中的 description 字段，形成摘要列表。具体体 SKILL.md 内容在需要时才会被读取。
扫描 extra
→
扫描 bundled
→
扫描 managed
→
扫描 personal
→
扫描 project
→
扫描 workspace
→
摘要列表
四、按需加载策略（摘要注入 -> 按需读取）
按需加载是 Skills 系统的核心优化策略，解决 Agent 上下文窗口有限的问题。它分为两个阶段：摘要注入和按需读取。
4.1 摘要注入阶段
在 Agent 启动或会话初始化时，系统不会将所有 SKILL.md 的完整内容加载到上下文中，而是只注入每个 Skill 的 摘要信息（即 front matter 中的 description 字段）。
摘要注入的格式
在 system prompt 中，摘要信息以列表形式呈现，格式如下：
Available skills:
- skill-name1: Brief description of skill 1
- skill-name2: Brief description of skill 2
- skill-name3: Brief description of skill 3
摘要注入的目的是让 Agent 知晓有哪些 Skill 可用，以及每个 Skill 的大致功能。这样 Agent 就可以在需要时决定是否读取完整的 Skill 内容。
为什么要设计为摘要注入？如果一个项目有 50 个 SKILL.md 文件，每个文件包含数百行指令，全部注入会立即耗尽上下文。摘要注入将每个 Skill 的上下文占用从数百行压缩到 1-2 行，极大地提高了上下文利用效率。
4.2 按需读取阶段
当 Agent 判断某个 Skill 与当前任务相关时，它会主动读取对应的 SKILL.md 文件，获取完整指令。读取操作在后台进行，对用户透明。
触发按需读取的典型场景：
- 用户输入的关键词与某个 Skill 的描述匹配
- 用户在对话中明确提及了某个 Skill 的名称
- Agent 在执行任务过程中发现需要特定领域的知识
- 定时计划触发了某个 Skill 的执行
用户输入
→
Agent 匹配
摘要列表
→
读取完整
SKILL.md
→
执行 Skill
指令
4.3 缓存优化
按需读取的 SKILL.md 内容会被缓存，避免在同一个会话中重复读取。缓存策略如下：
- 会话缓存：当前会话中读取过的 Skill 内容缓存在内存中
- 文件监听：如果 SKILL.md 文件发生变化，缓存自动失效并重新读取
- 主动刷新：用户可通过命令强制刷新所有缓存
性能提示
SKILL.md 文件应尽量保持精简。过长的 Skill 文件会占用更多的缓存空间，且在按需读取时消耗更多的令牌（tokens）。建议将复杂的 Skill 拆分为多个聚焦单一职责的小 Skill。
五、触发机制
Skills 系统提供三种触发机制：关键词匹配触发、文件变化触发和时间计划触发。开发者可以根据需要选择一种或多种组合。
5.1 关键词匹配触发
当用户的输入或对话内容中的关键词与 SKILL.md 中定义的 trigger 字段匹配时，自动激活该 Skill。这是最常用、最灵活的触发方式。
name: review
description: Review pull requests in the repository
trigger: pr, pull request, review, code review
priority: 5
匹配规则：
- 精确匹配：用户输入中出现 trigger 中的完整关键词
- 正则匹配：支持
pattern: 前缀定义正则表达式模式
- 大小写不敏感：默认忽略大小写差异
- 多关键词 OR 逻辑：匹配任一关键词即触发
正则匹配示例
trigger: pattern:(review|check|approve)\s+(this|the|my)\s+(pr|pull.request|changes)
trigger: pattern:git\s+(commit|push|pull|merge|rebase)
5.2 文件变化触发
当项目中的特定文件发生变化时触发 Skill 的执行。适用于自动化工作流场景，如文件保存后自动运行代码检查或测试。
name: auto-format
description: Auto-format code files on save
trigger: file:src/**/*.js, file:src/**/*.ts
priority: 5
文件变化触发支持：
- Glob 模式：使用
**、* 等通配符匹配文件路径
- 多路径：同时监听多个文件模式，用逗号分隔
- 变化类型：可指定监听创建、修改或删除事件
注意事项
文件变化触发在大型项目中可能产生大量事件。建议合理设置触发条件，避免过度频繁的 Skill 激活影响性能。可以使用 debounce 选项合并短时间内的连续触发。
5.3 时间计划触发
使用 cron 表达式或时间间隔定期执行 Skill。适合定时任务、周期性检查和自动化报告生成等场景。
name: weekly-report
description: Generate weekly progress report
schedule: 0 9 * * 1
| 类型 | 格式 | 示例 |
|---|
| cron 表达式 | 分 时 日 月 周 | 0 9 * * 1（每周一 9:00） |
| 时间间隔 | 数字+单位 | 30m（每 30 分钟）、2h（每 2 小时） |
| 特定时间点 | HH:MM | 08:00（每天 8:00） |
三种触发组合使用
一个 Skill 可以同时配置多种触发方式。例如，一个代码审查 Skill 既可以由关键词 "review" 触发，也可以在推送到特定分支时自动触发。多触发方式之间是 OR 关系，满足任一条件即可激活。
六、常用 Skills 示例
以下是 OpenClaw 生态中常用的 Skill 示例，展示了 SKILL.md 的实际编写方式。
6.1 代码审查 Skill
name: review
description: Review pull requests and suggest improvements
trigger: pr, pull request, review, code review
priority: 5
# Pull Request Review
When conducting a code review, follow these guidelines:
1. Start with a summary of the changes
2. Check for potential bugs and edge cases
3. Verify test coverage
4. Suggest improvements with clear reasoning
5. Maintain a constructive tone
6.2 安全审查 Skill
name: security-review
description: Complete a security review of pending changes
trigger: security, security review, audit
priority: 5
# Security Review
Follow this security review checklist:
- Check for hardcoded credentials and secrets
- Verify input validation and sanitization
- Review authentication and authorization logic
- Assess dependency vulnerabilities
- Check for proper error handling (no stack trace leaks)
6.3 初始化 Skill
name: init
description: Initialize a new CLAUDE.md file with codebase documentation
trigger: init, initialize, setup
priority: 5
# Project Initialization
When initializing a new project:
1. Scan the codebase structure
2. Identify key files and entry points
3. Document build and test commands
4. Create CLAUDE.md with essential project info
6.4 简化代码 Skill
name: simplify
description: Review changed code for reuse, quality, and efficiency
trigger: simplify, refactor, clean up, optimize
priority: 5
# Code Simplification
When asked to simplify code:
1. Identify duplicated logic and extract into reusable functions
2. Reduce nesting and improve readability
3. Replace imperative loops with functional alternatives where clearer
4. Remove dead code and unused imports
5. Verify tests still pass after changes
6.5 循环任务 Skill
name: loop
description: Run a prompt or command on a recurring interval
trigger: loop, interval, recurring, every
priority: 5
# Loop / Recurring Task
Execute a command or prompt repeatedly at a specified interval.
Usage: /loop <interval> <command>
Intervals: 5m, 10m, 30m, 1h, 2h
6.6 用户自定义 Personal Skill
name: my-workflow
description: My personal development workflow for web projects
trigger: my workflow, personal workflow
priority: 4
# Personal Web Development Workflow
1. Run `npm run lint` before committing
2. Write tests for new features
3. Update documentation when changing APIs
4. Create a new branch for each feature
Skill 设计原则：每个 Skill 应聚焦单一职责（Single Responsibility），描述应简明扼要，指令应清晰可执行。避免在一个 SKILL.md 中塞入过多不相关的功能。
七、Skills 调试与排错
Skills 系统的调试主要围绕三个方面：Skill 是否被正确识别、是否正确加载、以及是否正确触发。以下是常见问题及其排查方法。
7.1 查看已加载的 Skills
通过以下方式可以查看当前会话中所有已识别的 Skill：
/skills list
/skills info <skill-name>
/skills reload
7.2 常见问题排查
问题 1：Skill 未被触发
| 可能原因 | 解决方案 |
|---|
| trigger 字段未定义或定义错误 | 检查 SKILL.md 中的 trigger 字段格式是否正确 |
| 关键词不匹配 | 确认 trigger 中的关键词与用户输入完全匹配（或正则正确） |
| 优先级被覆盖 | 检查是否有更高优先级的同名 Skill 阻止了本 Skill 的加载 |
| SKILL.md 语法错误 | 验证 front matter 的 YAML 格式是否正确（缩进、冒号等） |
问题 2：Skill 加载失败
- 检查文件路径：SKILL.md 必须位于正确的
skills/<level>/ 目录下
- 检查文件名：文件名必须严格为
SKILL.md（大小写敏感？取决于操作系统）
- 检查文件权限：确保 OpenClaw 进程有读取权限
- 查看错误日志：检查 OpenClaw 的日志输出，寻找解析错误信息
问题 3：同名校验错误
同名优先级覆盖
当多个目录中存在同名的 SKILL.md 时，高优先级目录中的文件会完全覆盖低优先级目录中的文件。这可能导致低优先级目录中定义的 Skill 看似"消失"。使用 /skills list 命令查看最终生效的是哪个版本。
7.3 调试技巧
- 从简单开始：创建一个最小化的 SKILL.md 验证系统是否正常运行，再逐步增加内容
- 使用 description 测试：修改 description 后重启会话，观察摘要注入是否更新
- 日志监控：开启 OpenClaw 的详细日志模式，监控 Skill 的加载和触发事件
- 插件冲突排查：如果使用了第三方插件，尝试禁用后测试原生命令，排除插件干扰
快速验证模板
创建一个测试 Skill，确认系统正常工作：
name: hello
description: A test skill that says hello
trigger: hello, test
priority: 5
# Hello Skill
When triggered, respond with "Hello from Skills system!"
7.4 调试命令速查表
| 命令 | 用途 |
|---|
/skills list | 列出所有已加载的 Skill |
/skills info <name> | 查看指定 Skill 的详细信息 |
/skills reload | 重新加载所有 SKILL.md 文件 |
/plugin list | 列出已安装的插件及其 Skill |
/reload-plugins | 安装插件后重新加载以激活新功能 |
八、核心要点总结
- Skills 是 OpenClaw 的扩展机制核心：将知识、指令和行为模式封装为独立模块，实现按需加载和高效利用上下文窗口。
- SKILL.md 是 Skills 的定义文件：采用 Markdown + YAML front matter 格式，包含 name、description、trigger、schedule、priority 等关键元数据。
- 6 级优先级体系：extra(1) < bundled(2) < managed(3) < personal(4) < project(5) < workspace(6)。高优先级完全覆盖低优先级同名 Skill。
- 按需加载分为两个阶段：摘要注入（仅注入 description）和按需读取（触发后才读取完整内容），极大节省上下文空间。
- 三种触发机制：关键词匹配（最常用）、文件变化监听（自动化工作流）、时间计划（定时任务），可组合使用。
- 单一职责原则：每个 Skill 聚焦一个功能领域，避免编写过于庞大复杂的 SKILL.md 文件。
- 调试有章可循：使用
/skills list、/skills info、/skills reload 等调试命令快速定位问题。
- 缓存机制：已读取的 SKILL.md 内容在会话中缓存，文件变化时自动失效，保证性能和实时性。