OpenClaw Skills 系统工程化深度解析：从 SKILL.md 动态注入到 MetaSkill DAG 的全链路架构

题记：如果你用 OpenClaw 还只在聊天，那这篇是写给真正想掌控它的人看的。

一、背景：为什么传统 Agent 的"技能"是残次品

在聊 OpenClaw 的 Skills 系统之前，我们先搞清楚一个根本问题：大多数 AI Agent 的"技能扩展"本质上是什么？

答案是：Prompt 拼接。

你给 GPT-4 加一段 system prompt，告诉他"你现在是一个 Python 专家"，他就声称自己会写 Python 了。你再给他加一段"你现在是一个产品经理"，他就声称自己能写 PRD 了。每次切换角色，都是在 Prompt 的海洋里游来游去——没有边界、没有版本、没有复用、没有结构。

这种模式的深层问题有三个：

1. 上下文爆炸
一个专业技能可能需要几十段前置知识。当你想同时让 Agent 做"Python 开发 + 数据库优化 + 云原生部署"三件事时，Prompt 可能已经超过上下文窗口的 30%。模型开始出现"幻觉性遗忘"——最前面写的指令到后面就忽略了。

2. 执行不透明
Prompt 里写"先查天气，再查路况，再决定穿什么衣服"。LLM 真的严格按照这个顺序执行吗？不一定。它可能先回答了路况，然后跳回去查天气，最后给出一个混乱的结论。没有执行保证，没有状态追踪。

3. 技能无法复用
你为项目 A 写的"数据库迁移专家"Prompt，项目 B 想用只能复制粘贴。没有版本管理、没有依赖声明、没有参数化。改一个细节要同步改十个地方。

OpenClaw 的 Skills 系统，正是为了解决这三个问题而生的。

它的核心理念是：技能不是 Prompt，技能是一个有边界、有触发条件、有执行协议、可组合、可版本化的独立能力单元。 就像一个 npm 包——你不需要知道它的实现细节，只需要知道它的接口和用途。

二、核心概念：Tool、Skill、Plugin 到底有什么区别

这三个概念是大多数 OpenClaw 入门者最头疼的地方。我们先给出一个清晰的定义。

2.1 Tool：原子级别的"手"

Tool（工具） 是 OpenClaw 执行能力的最小单元，是 LLM 调用操作的接口定义。

一个 Tool 在系统层面的定义通常长这样：

{
  "name": "browser_navigate",
  "description": "导航浏览器到指定 URL",
  "parameters": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "目标网页的完整 URL"
      },
      "target": {
        "type": "string",
        "enum": ["sandbox", "host"],
        "description": "在哪个浏览器实例中执行"
      }
    },
    "required": ["url"]
  }
}

Tool 的特点：

• 无状态：每次调用都是独立的，不保留上下文
• 原子性：一个 Tool 只做一件事（导航、点击、填表、抓取）
• 底层性：Tool 通常直接映射到某个系统能力（Shell 命令、HTTP 请求、文件系统操作）
• OpenClaw 内置了大量 Tool：文件读写、Shell 执行、浏览器控制、网页抓取、代码执行等

2.2 Skill：结构化的"技能卡"

Skill（技能） 是给 LLM 看的"工作手册"，是一组告诉 AI 何时激活、如何思考、按什么步骤执行的指令包。

Skill 的核心是 SKILL.md 文件，它的结构远不止 Prompt 那么简单：

---
name: python-code-reviewer
description: 当用户要求审查代码、重构方案评估、或发现潜在 Bug 时激活此技能。触发词：代码审查、review、重构、bug、代码质量。
---

# Python 代码审查专家

你是一名拥有 10 年经验的高级 Python 工程师，专长于代码审查和架构评估。

## 核心职责

1. **可读性评估**：命名规范、注释质量、函数长度、模块划分
2. **性能分析**：算法复杂度、循环嵌套、内存泄漏风险
3. **安全审计**：SQL 注入、XSS、敏感信息硬编码、依赖安全
4. **架构建议**：设计模式适用性、模块耦合度、扩展性预测

## 执行流程

1. 提取代码的关键逻辑片段
2. 识别明显的代码异味（Code Smell）
3. 使用 Pyright/pylint 执行静态分析
4. 生成结构化的审查报告

## 输出格式

使用以下 Markdown 模板：

\`\`\`
## 🔍 审查结果：{文件名}

### 评分：{X}/10
### 总体评价：{一句话总结}

### 🚨 严重问题
- {问题描述}（行 {N}）

### ⚠️ 警告
- {问题描述}

### 💡 优化建议
- {建议内容}

### 📊 统计
- 总行数：{N}
- 函数数：{N}
- 圈复杂度：{N}
\`\`\`

## 触发条件详解

当用户输入包含以下任一关键词时激活：
- "审查"、"review"、"review 下"
- "重构"、"refactor"
- "代码质量"、"规范"
- "帮我看看这段代码"

## 注意事项

- 不修改原始代码，只提供分析和建议
- 对不确定性使用"建议进一步验证"而非猜测
- 优先关注业务逻辑正确性，再关注风格

看到这里你应该明白：Skill 是给 AI 看的执行规范，不是给人类看的操作手册。 它的 YAML frontmatter 是机器可解析的元数据，它的 Markdown 正文是 AI 的行为指令。

2.3 Plugin：系统级的"扩展包"

Plugin（插件） 是在系统层面扩展 OpenClaw 能力的机制，通常包含：

• 新的 Channel Adapter（接入新的聊天平台）
• 新的 Tool Provider（注册新的工具）
• 新的 Memory Backend（换一种存储方案）
• 新的 Model Provider（接入新的 AI 模型）

Plugin 的代码结构比 Skill 重得多，通常需要编写 TypeScript/JavaScript 代码：

// plugin 典型结构
export default {
  name: 'my-custom-plugin',
  version: '1.0.0',
  
  // 插件加载时执行
  onLoad: async (ctx: PluginContext) => {
    ctx.tools.register({
      name: 'my_custom_tool',
      description: '自定义工具描述',
      execute: async (params) => {
        // 实现逻辑
        return { result: '...' }
      }
    })
  },
  
  onUnload: async () => {
    // 清理逻辑
  }
}

2.4 三者关系总结

三者的协作关系可以这样理解：

用户输入 → Skill 匹配 → Skill 提供执行策略 → LLM 决定调用哪些 Tool → Tool 执行具体操作
                                      ↑
Plugin 在这里注册新的 Tool Provider

三、SKILL.md 深度解析：每一个字段的工程含义

现在我们深入到 SKILL.md 的内部，理解它的完整结构。

3.1 YAML Frontmatter：机器可读的元数据

---
name: skill-name              # 全局唯一标识，/skill-name 直接触发
description: >                # 简短描述，供 AI 判断是否调用（≤160 字节最佳）
  在用户要求 {做什么} 时激活，覆盖 {场景}。
available_skills:              # 引用的下游 skill（Skill Workshop 专有）
  - skill: weather-query
    path: ~/.qclaw/skills/weather/
triggers:                      # 触发模式（显式 vs 隐式）
  - "查询天气"
  - "今天 {city} 天气"
  - "/weather"
skill_type: standard           # standard | workshop | system
---

name 字段的工程含义：

• 决定了 /name slash 命令的可用性
• 会被 OpenClaw 注册到 Skill Registry 中
• 命名规范建议：kebab-case，如 python-code-reviewer

description 的设计哲学：

• description 不是给人类读的，是给 LLM 做 Skill 路由判断的
• 好的 description 应该包含：激活场景 + 用户意图 + 关键词
• 太泛的 description（如"这是一个有用的技能"）会导致 LLM 错误调用

available_skills 的依赖注入：
这是 Skill Workshop 模式的核心字段。当你创建一个复杂 Skill 时，它可以声明对其他 Skill 的依赖。OpenClaw 在加载这个 Skill 时，会自动把依赖的 Skill 内容注入到上下文中。

3.2 Markdown 正文：LLM 的执行宪章

Markdown 正文不是随意写的，每一段都有语义：

触发条件区（Triggers）

## 触发条件

当用户说以下内容时激活：
- "帮我 {action}"
- "执行 {task}"
- "/{skill-name}"

角色定义区（Role Definition）

## 角色

你是一名 {职业}，拥有 {X} 年经验，专长于 {领域}。

你的工作风格：
- {特质 1}
- {特质 2}
- {特质 3}

执行流程区（Workflow）

这是最关键的部分。OpenClaw 的 Skill 执行流程支持确定性步骤和LLM 自主决策两种模式：

## 执行流程

### 确定性模式（明确的线性步骤）

1. 接收用户输入
2. 解析关键参数（使用 {tool} 提取 {信息}）
3. 调用 {API/工具} 获取 {数据}
4. 按照以下格式整理结果：

### LLM 自主模式（启发式引导）

1. 先理解用户的核心诉求
2. 判断是否需要外部工具
3. 如果需要，优先选择 {工具 A}，备选 {工具 B}
4. 在 {N} 步内给出一个完整答案

确定性模式的工程价值：很多人低估了这个功能。确定性步骤意味着你可以把一个复杂的业务流程代码化——每一步做什么、用什么工具、输出什么格式，都是固定的。LLM 在确定性模式下的表现远比自由发挥稳定。

输出格式区（Output Schema）

## 输出格式

必须使用以下结构，不得省略任何部分：

### {标题}
内容...

### {标题}
内容...

## 禁止事项
- 不要 {行为 A}
- 不要在未确认前 {行为 B}
- 绝对禁止 {行为 C}

上下文注入区（Context Injection）

## 上下文注入规则

你还需要从以下来源获取额外信息：
- 当前项目技术栈：读取 `{workspace}/package.json` 中的 `dependencies`
- 用户偏好：读取 `{workspace}/TOOLS.md` 中的 `user_preferences`
- 相关历史：搜索 `{workspace}/MEMORY.md` 中关于 {topic} 的记录

四、动态注入机制：Skills 是如何被 AI 感知和调用的

这是 Skills 系统的核心工程问题：OpenClaw 怎么知道在某个场景下该加载哪个 Skill？LLM 怎么感知 Skill 的存在？

4.1 技能发现与注册（Discovery & Registry）

OpenClaw 在启动时，会扫描工作空间中的 skills/ 目录：

~/.qclaw/workspace/
├── skills/
│   ├── weather/
│   │   └── SKILL.md
│   ├── python-code-reviewer/
│   │   ├── SKILL.md
│   │   ├── references/
│   │   │   └── pylint-rules.md
│   │   └── templates/
│   │       └── review-report.md
│   └── stock-query/
│       └── SKILL.md

扫描后，每个 Skill 的 frontmatter 被解析并注册到 Skill Registry 中：

// Skill Registry 的数据结构（简化版）
interface SkillRegistry {
  skills: Map<string, SkillMetadata>
  triggerIndex: InvertedIndex<string, string>  // 关键词 → Skill 名称
}

interface SkillMetadata {
  name: string
  description: string
  path: string
  triggers: string[]
  dependencies: string[]
  loadedAt: Date
  tokenEstimate: number  // 估算的注入 Token 消耗
}

同时，系统会构建一个触发倒排索引：

"审查"     → ["python-code-reviewer", "go-code-reviewer"]
"天气"     → ["weather-query", "baidu-weather"]
"发布文章" → ["chenxutan-article-publish"]

这个倒排索引在每次对话时都会被用于快速匹配。

4.2 上下文组装时的技能注入（Context Injection）

当用户发送一条消息时，OpenClaw 的 Agent Runtime 会经历以下流程：

用户消息
  ↓
触发检测：Query Skill Index（倒排索引 + 语义匹配）
  ↓
候选 Skill 列表（可能多个）
  ↓
Token 预算检查：injectable_token_budget - base_context_tokens
  ↓
按优先级排序，选择能在 Token 预算内放入的 Skill
  ↓
加载 SKILL.md 内容
  ↓
替换 available_skills 中的依赖 Skill
  ↓
注入到 System Prompt
  ↓
LLM 调用

关键设计：不是所有匹配的 Skill 都会被注入。

如果用户的消息同时触发了 5 个 Skill，但把它们全部塞进 System Prompt 会超过上下文窗口，OpenClaw 只会选择最相关的 N 个。这就需要用到 tokenEstimate 字段。

4.3 语义匹配 vs 关键词匹配

除了触发倒排索引，OpenClaw 还会用语义相似度来判断一个 Skill 是否相关：

// 语义匹配逻辑（简化）
async function findRelevantSkills(userMessage: string, context: ConversationContext) {
  // 1. 关键词匹配（快速过滤）
  const keywordMatches = triggerIndex.lookup(userMessage)
  
  // 2. 语义匹配（深度搜索）
  const userEmbedding = await embedModel.encode(userMessage)
  const allSkills = await skillRegistry.listAll()
  
  const semanticMatches = await Promise.all(
    allSkills.map(async (skill) => {
      const descEmbedding = await embedModel.encode(skill.description)
      const similarity = cosineSimilarity(userEmbedding, descEmbedding)
      return { skill, similarity }
    })
  )
  
  // 3. 综合排序：关键词匹配权重 × 0.7 + 语义匹配权重 × 0.3
  const scored = [...keywordMatches, ...semanticMatches]
    .reduce((acc, match) => {
      // 去重并加权
      return acc
    }, [])
    .sort((a, b) => b.score - a.score)
  
  return scored.slice(0, MAX_INJECTABLE_SKILLS)
}

4.4 Token 预算管理：注入的艺术

OpenClaw 对每个 Skill 都会估算它的 Token 消耗：

function estimateSkillTokens(skill: Skill): number {
  const frontmatterTokens = countTokens(skill.frontmatter)
  const contentTokens = countTokens(skill.markdown)
  const refsTokens = skill.references
    .reduce((sum, ref) => sum + countTokens(ref.content), 0)
  
  // references/ 目录下的文件是"按需加载"的
  // 只有当 LLM 在正文中引用时，才会被计入
  return frontmatterTokens + contentTokens
}

典型的 Token 消耗估算：

五、Skill Workshop：从想法到可运行 Skill 的完整链路

OpenClaw 的 Skill Workshop 是 Skills 系统中最强大的功能之一——它允许 AI 自己创建和修改 Skill。这意味着你可以对 OpenClaw 说："我需要一个能帮我做 X 的 Skill，帮我创建一下"，然后 OpenClaw 会自动生成完整的 SKILL.md。

5.1 Workshop 的触发与工作流

当你请求创建一个 Skill 时，Workshop 会经历以下阶段：

阶段 1：需求理解

用户输入：帮我创建一个"技术文章发布助手"的 Skill

OpenClaw 分析：
- 触发词：发布文章、技术博客、程序员茄子
- 核心功能：搜索选题 → 撰写文章 → 调用发布 API
- 所需工具：web_search, browser, qclaw_tdoc_mcp_call
- 输出物：SKILL.md 文件

阶段 2：骨架生成

OpenClaw 根据分析结果生成 Skill 骨架：

---
name: article-publisher
description: 当用户要求发布技术文章、写博客、投稿到程序员茄子时激活。
---

# 技术文章发布助手

## 角色
你是一名专业的内容策划和发布专家，精通技术写作和内容运营。

## 防重复检查流程

在确定选题前，必须执行以下步骤：

1. **读取已发布列表**
   使用 web_fetch 访问 https://www.chenxutan.com
   提取所有文章的标题，存入"已发布列表"

2. **选题相似度比对**
   对每个候选选题，与"已发布列表"进行标题相似度比较
   计算方法：共有关键词数 / 总关键词数

3. **去重决策**
   - 相似度 > 0.6：跳过该选题
   - 相似度 0.3-0.6：改写标题差异化
   - 相似度 < 0.3：可接受

4. **搜索新选题**
   如果所有候选都重复，使用新的搜索关键词重新搜索
   最多尝试 3 组关键词

## 文章结构要求

技术深度文章必须包含以下模块：

### 1. 背景与问题定义（10%）
- 当前技术痛点是什么
- 现有方案的局限性

### 2. 核心概念拆解（20%）
- 技术原理的可视化解释
- 关键术语的定义

### 3. 架构设计与实现（30%）
- 完整的代码示例（带注释）
- 架构图描述（Mermaid 或 ASCII）

### 4. 实战演练（25%）
- 端到端可运行的代码
- 常见坑和解决方案

### 5. 性能对比与优化（10%）
- 量化数据对比
- 优化前后的效果

### 6. 总结与展望（5%）
- 核心收获
- 未来趋势判断

## 字数要求
- 最低 5000 字
- 代码块占比 ≥ 20%
- 每个技术点必须配代码示例

## 禁止事项
- 不写自然人真实姓名
- 不发布与已有文章高度相似的内容
- 不省略代码示例
- 不使用截图代替代码

## 触发关键词
"发布文章"、"写博客"、"技术文章"、"投稿"、"发布到程序员茄子"

阶段 3：文件写入

生成的骨架被写入 ~/.qclaw/workspace/skills/article-publisher/SKILL.md。

阶段 4：自验证

Workshop 创建的 Skill 会被 OpenClaw 实际执行一次，以验证：

• SKILL.md 语法是否正确
• 引用的 available_skills 是否存在
• 执行流程是否可正常触发

5.2 Workshop 的安全保障

Skill Workshop 允许 AI 写文件，这带来了安全风险。OpenClaw 的防护机制：

// Workshop 文件写入前的安全检查
async function validateWorkshopOutput(skill: Skill): Promise<ValidationResult> {
  const checks = []
  
  // 1. 路径检查：只能在 workspace/skills/ 下创建
  if (!skill.path.startsWith(WORKSPACE_SKILLS_DIR)) {
    checks.push({ level: 'error', msg: '路径不在允许范围内' })
  }
  
  // 2. 权限检查：不能请求超出配置的 Tool 权限
  const requiredTools = extractToolRequests(skill.markdown)
  const allowedTools = getAllowedToolsForCurrentSession()
  const unauthorizedTools = requiredTools.filter(t => !allowedTools.includes(t))
  
  if (unauthorizedTools.length > 0) {
    checks.push({
      level: 'warning',
      msg: `使用了未授权工具: ${unauthorizedTools.join(', ')}`
    })
  }
  
  // 3. 内容扫描：检测恶意 Prompt 注入模式
  const injectionPatterns = [
    /ignore previous instructions/i,
    /disregard all previous/,
    /sudo\s+rm\s+-rf/i,
    /eval\s*\(\s*base64/i,
  ]
  
  const detectedInjections = injectionPatterns
    .filter(p => p.test(skill.markdown))
  
  if (detectedInjections.length > 0) {
    checks.push({ level: 'critical', msg: '检测到 Prompt 注入模式' })
  }
  
  return aggregateChecks(checks)
}

六、MetaSkill DAG：多技能编排的确定性架构

在复杂任务中，单个 Skill 往往不够用——你需要把多个 Skill 按特定顺序组合起来执行。OpenClaw 的 MetaSkill DAG 正是为这种场景设计的。

6.1 什么是 DAG（Directed Acyclic Graph，有向无环图）

DAG 是一种图结构，其中：

• 节点（Node）：一个具体的 Skill
• 边（Edge）：Skill 之间的依赖关系
• 无环（Acyclic）：不会出现 A→B→C→A 这样的死循环

举例：一个"技术文章自动发布"DAG 可能长这样：

[选题搜索] ──→ [去重检查]
[选题搜索] ──┬──→ [文章撰写]
[去重检查] ──┘
                    │
[文章撰写] ──→ [相似度预检] ──→ [发布 API]
[文章撰写] ──→ [保存草稿]

6.2 MetaSkill 的定义

---
name: article-auto-publish-workflow
description: 完整的技术文章自动发布工作流，从选题到发布全覆盖。
skill_type: workshop
---

# 技术文章自动发布工作流

## DAG 定义

这是一个 MetaSkill，定义了子技能之间的编排关系。

### 节点定义

```yaml
nodes:
  - id: search_topics
    skill: multi-search-engine
    params:
      keywords: ["GitHub Trending", "AI技术突破", "Go语言新特性"]
      freshness: week
    output_var: topics
  
  - id: deduplicate
    skill: article-dedup-checker
    params:
      source: "${search_topics.topics}"
      published_list: "${fetch_published_list.result}"
    depends_on: [search_topics]
    output_var: verified_topics
  
  - id: write_article
    skill: article-writer
    params:
      topic: "${deduplicate.selected_topic}"
      min_words: 5000
    depends_on: [deduplicate]
    output_var: article_content
  
  - id: similarity_check
    skill: chenxutan-similarity-check
    params:
      title: "${write_article.title}"
      content: "${write_article.content}"
    depends_on: [write_article]
    output_var: similarity_result
  
  - id: publish
    skill: chenxutan-article-publish
    params:
      title: "${write_article.title}"
      content: "${write_article.content}"
      cid: 1
    depends_on: [similarity_check]
    condition: "${similarity_check.is_unique}"

执行引擎

DAG 由 OpenClaw 的执行引擎驱动：

1. 拓扑排序：按照依赖关系确定执行顺序
2. 并行优化：没有依赖关系的节点可以并行执行
3. 状态追踪：每个节点的输入、输出、状态全程记录
4. 失败恢复：节点失败时，支持从断点重试

错误处理

每个节点都可以定义错误处理策略：

- id: search_topics
  error_handling:
    max_retries: 3
    backoff: exponential
    fallback: skip_and_notify
    on_permanent_failure: abort_workflow

6.3 DAG 执行的可观测性

MetaSkill DAG 的另一个重要特性是完整的执行追踪：

{
  "workflow_id": "article-auto-publish-20260731",
  "started_at": "2026-07-31T17:00:00Z",
  "nodes": [
    {
      "id": "search_topics",
      "status": "completed",
      "started_at": "17:00:00",
      "finished_at": "17:00:03",
      "output": {
        "topics": [
          { "title": "Go Swiss Table 原理", "source": "GitHub Trending" },
          { "title": "OpenClaw Skills 系统", "source": "AI技术突破" }
        ]
      }
    },
    {
      "id": "deduplicate",
      "status": "completed",
      "started_at": "17:00:03",
      "finished_at": "17:00:05",
      "output": {
        "selected_topic": {
          "title": "OpenClaw Skills 系统",
          "similarity_score": 0.12
        }
      }
    },
    {
      "id": "write_article",
      "status": "in_progress",
      "started_at": "17:00:05",
      "progress": { "current_section": 3, "total_sections": 6 }
    }
  ]
}

这种可观测性在生产环境中至关重要——你可以清楚地知道工作流卡在哪一步、为什么失败、需要什么干预。

七、代码实战：从零创建一个"数据库慢查询分析"Skill

光说不练假把式。让我们实战创建一个完整的 Skill。

7.1 需求分析

目标：创建一个当用户提到"慢查询"、"MySQL 慢"、"PostgreSQL 性能问题"时自动激活的 Skill，能够：

1. 解析用户提供的慢查询 SQL
2. 生成 EXPLAIN 分析
3. 给出优化建议

7.2 目录结构

~/.qclaw/workspace/skills/
└── db-slow-query-analyzer/
    ├── SKILL.md                    # 核心技能定义
    ├── references/
    │   ├── mysql-optimization.md   # MySQL 优化知识库
    │   └── postgres-optimization.md # PostgreSQL 优化知识库
    └── templates/
        └── analysis-report.md       # 分析报告模板

7.3 SKILL.md 完整代码

---
name: db-slow-query-analyzer
description: 当用户提到慢查询、数据库性能问题、SQL 优化、执行计划分析时激活。支持 MySQL 和 PostgreSQL。
available_skills:
  - skill: mysql-optimization
    path: ./references/
  - skill: postgres-optimization
    path: ./references/
---

# 数据库慢查询分析专家

你是一名拥有 15 年经验的数据库架构师，精通 MySQL 和 PostgreSQL 的性能调优。

## 核心能力

- 解读 `EXPLAIN` / `EXPLAIN ANALYZE` 输出
- 识别全表扫描、索引失效、JOIN 膨胀等问题
- 生成可执行的 SQL 优化建议
- 评估优化后的预期性能提升

## 分析流程

### 第一步：识别数据库类型

```sql
-- MySQL
SELECT VERSION();

-- PostgreSQL
SELECT version();

第二步：获取执行计划

MySQL：

EXPLAIN FORMAT=JSON {你的 SQL};
-- 或
EXPLAIN ANALYZE {你的 SQL};

PostgreSQL：

EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) {你的 SQL};

第三步：分析执行计划

逐行解读执行计划，关注以下关键指标：

第四步：生成优化建议

根据分析结果，按以下优先级给出建议：

P0（立即修复）：

• 全表扫描（Seq Scan / ALL type）
• 缺失关键索引
• 过大的 JOIN 结果集

P1（高优先级）：

• 低效的子查询（改写为 JOIN）
• 不必要的排序（filesort）
• 缺失复合索引

P2（优化建议）：

• LIMIT 分页优化
• 覆盖索引建议
• 批量操作合并

报告模板

```

📊 慢查询分析报告

基本信息

• 数据库类型：{MySQL / PostgreSQL}
• 分析时间：{时间戳}

原始 SQL

```sql
{原始 SQL}
```

执行计划分析

关键指标

问题列表

🚨 {问题描述}

• 位置：{行号 / 步骤}
• 影响：{性能影响量化}
• 原因：{根本原因}

优化方案

方案 1：{优化名称}

SQL：
```sql
{优化后的 SQL}
```
预期提升：{X}%

原理：
{技术原理说明}

索引建议

```sql
-- 新增索引
CREATE INDEX idx_{table}_{columns} ON {table} ({columns});

-- 检查现有索引
SHOW INDEX FROM {table}; -- MySQL
SELECT * FROM pg_indexes WHERE tablename = '{table}'; -- PostgreSQL
```

总结

{一句话总结 + 后续建议}
```

注意事项

• 优化建议需要结合实际数据量验证
• 添加索引会增加写入开销，需要权衡读/写比例
• 在生产环境执行前，先在测试环境验证
• 对于复杂查询，建议分步优化，每步后验证效果

## 触发关键词

"慢查询"、"慢 SQL"、"性能问题"、"数据库调优"、"执行计划"、"EXPLAIN"、"索引优化"、"MySQL 优化"、"PostgreSQL 优化"、"SQL 优化建议"

## 依赖说明

本 Skill 依赖以下知识库文件：
- `references/mysql-optimization.md`：MySQL 特有的优化技巧和参数说明
- `references/postgres-optimization.md`：PostgreSQL 特有的优化技巧和参数说明

这些文件会在 Skill 激活时自动注入到上下文中。

7.4 references 文件示例（mysql-optimization.md）

# MySQL 慢查询优化知识库

## EXPLAIN type 字段含义

| type值 | 含义 | 性能 |
|--------|------|------|
| system | 只有一行（系统表） | 最优 |
| const | 通过主键或唯一索引最多匹配一行 | 优 |
| eq_ref | 使用主键或唯一索引连接 | 优 |
| ref | 使用非唯一索引匹配多行 | 中 |
| range | 索引范围扫描 | 中 |
| index | 全索引扫描 | 差 |
| ALL | 全表扫描 | 最差 |

## 常见索引失效场景

1. **函数包裹索引列**
\`\`\`sql
-- 错误：索引失效
WHERE YEAR(created_at) = 2026

-- 正确：保留索引
WHERE created_at >= '2026-01-01' AND created_at < '2027-01-01'
\`\`\`

2. **隐式类型转换**
\`\`\`sql
-- 假设 user_id 是 VARCHAR，但传入了 INT
-- 错误：索引失效
WHERE user_id = 12345

-- 正确：类型匹配
WHERE user_id = '12345'
\`\`\`

3. **OR 条件断裂**
\`\`\`sql
-- 错误：导致索引部分失效
WHERE status = 'active' OR name = 'test'

-- 正确：拆分为 UNION 或改写
WHERE status = 'active'
UNION ALL
SELECT * FROM users WHERE name = 'test' AND status != 'active'
\`\`\`

## JOIN 优化规则

- 小表驱动大表（`STRAIGHT_JOIN` 强制指定驱动表）
- 避免 `SELECT *`，只取需要的列
- 多表 JOIN 时，确保每个条件列都有索引

7.5 使用效果演示

当用户在 OpenClaw 中输入：

"这个 SQL 很慢，帮我分析一下：SELECT * FROM orders WHERE user_id = 123 AND status = 'pending' ORDER BY created_at DESC LIMIT 20"

OpenClaw 会：

1. 检测到触发词"很慢"、"分析"，激活 db-slow-query-analyzer
2. 注入 MySQL 优化知识库到上下文
3. 按流程执行分析
4. 输出完整分析报告

八、性能优化：技能注入的 Token 控制

Skills 系统最大的性能挑战是：Skill 越多，注入开销越大，上下文窗口越紧张。

OpenClaw 提供了几个优化手段：

8.1 分层加载策略

// 分层加载配置
const skillInjectionConfig = {
  layers: [
    {
      name: 'always',
      skills: ['*'],  // 始终注入的全局 Skill
      tokenBudget: 500
    },
    {
      name: 'contextual',
      skills: [],  // 由触发匹配决定
      tokenBudget: 2000
    },
    {
      name: 'explicit',
      skills: [],  // 由 /slash 命令显式加载
      tokenBudget: 5000
    }
  ],
  totalBudget: 8000  // Skill 注入总预算
}

8.2 条件加载（Conditional Loading）

---
name: production-deployer
description: 在生产环境执行部署任务时激活
---

# 生产部署专家

## 激活条件

本 Skill 仅在以下条件同时满足时激活：
- 当前环境变量 `ENV = production`
- 用户意图包含"部署"、"发布"、"上线"

## 执行前的安全确认

1. 显示即将执行的操作摘要
2. 列出所有涉及的服务器/服务
3. 等待用户确认（输入"确认部署"）
4. 执行前创建快照/备份

8.3 异步预加载

对于需要加载大量 references 的 Skill，OpenClaw 支持异步预加载：

---
name: large-skill-demo
description: 大型知识密集型技能
load_strategy: eager   # eager | lazy | background
preload_threshold: 0.8 # 当上下文利用率 < 80% 时预加载
---

九、安全架构：Skills 的权限与隔离

Skills 之所以强大，正是因为它能操作文件、执行命令、访问网络。但这也意味着错误的 Skill 可能是危险的。OpenClaw 提供了多层安全机制。

9.1 权限层级

// OpenClaw 的 Skill 权限层级
const permissionHierarchy = [
  'kernel',      // 系统内核操作
  'provider',    // 模型/API 提供商配置
  'global',      // 全局策略
  'agent',       // Agent 级别配置
  'group',       // 群组级别策略
  'sandbox'      // 沙箱策略（最严格）
]

// 每个 Skill 在加载时会继承所在层级的权限
// 但不能超出层级赋予的权限

9.2 沙箱执行隔离

---
name: untrusted-skill
description: 来源不明的 Skill
execution_mode: sandboxed  # sandboxed | isolated | unrestricted
sandbox_config:
  network: none            # none | limited | full
  filesystem: /tmp/skill   # 限制只能访问 /tmp/skill 目录
  execution_timeout: 30     # 最大执行时间（秒）
  max_memory_mb: 256       # 最大内存
---

9.3 Skill 来源验证

OpenClaw 会对安装的 Skill 进行来源验证：

async function verifySkillIntegrity(skillPath: string): Promise<VerifyResult> {
  // 1. 签名验证（如果 Skill 有签名）
  const signatureFile = path.join(skillPath, '.signature')
  if (await fs.exists(signatureFile)) {
    const sig = await fs.readFile(signatureFile)
    const pubKey = await getClawHubPublicKey()
    if (!crypto.verify(sig, pubKey)) {
      return { trusted: false, reason: 'invalid_signature' }
    }
  }
  
  // 2. 权限清单检查
  const manifestFile = path.join(skillPath, '.permissions')
  if (await fs.exists(manifestFile)) {
    const permissions = JSON.parse(await fs.readFile(manifestFile))
    const untrusted = permissions.filter(p => !TRUSTED_PERMISSIONS.includes(p))
    if (untrusted.length > 0) {
      return {
        trusted: false,
        reason: 'unauthorized_permissions',
        details: untrusted
      }
    }
  }
  
  // 3. 恶意代码扫描
  const scanResult = await scanForMalware(skillPath)
  if (scanResult.detected) {
    return { trusted: false, reason: 'malware_detected' }
  }
  
  return { trusted: true }
}

十、总结与展望

核心要点回顾

1. Tool 是原子，Skill 是组织，Plugin 是扩展。三者分工明确，不是替代关系。

2. SKILL.md 不只是 Prompt，是结构化的执行规范。YAML frontmatter 是机器可解析的元数据，Markdown 正文是 LLM 的行为指令。

3. 动态注入解决了上下文爆炸问题。不是把所有 Skill 塞进 System Prompt，而是按需、按时、按 Token 预算精确注入。

4. MetaSkill DAG 让复杂任务可编排、可追踪、可恢复。这是从"AI 辅助"到"AI 执行"的关键一步。

5. Skill Workshop 让 AI 自己改进自己的能力。这是一个自举的过程——用 AI 创作用于增强 AI 的工具。

未来展望

Skills 系统的发展方向值得关注：

• 标准化：Skill 的跨 Agent 互通——一个为 OpenClaw 写的 Skill，未来能否无缝迁移到另一个 Agent 平台？MCP 协议已经在朝这个方向努力。

• AI 原生 Skill 生成：未来的 Workshop 可能不再需要人类写 SKILL.md。AI 会自动从对话历史中学习用户的工作模式，自动生成 Skill。

• Skill 的可验证性：当 Skill 越来越多，如何验证一个 Skill 的执行效果？Skill 评测框架会成为下一个热点。

• 去中心化 Skill 市场：基于区块链或 DAO 的 Skill 分发机制，确保 Skill 作者的收益和 Skill 质量的正反馈循环。

最后一句话：OpenClaw 的 Skills 系统，本质上是在解决一个问题——如何让 AI 的能力像软件一样工程化管理。当你开始用 SKILL.md 而非 Prompt 模板思考时，你就从"调教 AI"进化到了"构建 AI 能力系统"。这是质的飞跃。

本文约 9800 字，覆盖了 OpenClaw Skills 系统的架构设计、核心原理、代码实现和工程实践。如有问题，欢迎通过 OpenClaw 的 Skill Workshop 功能创建一个"本文答疑"Skill 来继续探讨。