OpenClaw 架构下 Skills System —— 为什么“文档即工具”是 OpenClaw 的扩展灵魂

skills/
├── restart_db.SKILL.md
├── analyze_logs.SKILL.md
└── deploy_webapp.SKILL.md

---
name: restart_db
description: 重启指定 Kubernetes 部署中的数据库
parameters:
  - name: deployment
    type: string
    required: true
    description: 数据库部署名（如 'postgres-prod'）
dependencies:
  - type: command
    name: kubectl
  - type: package
    manager: brew
    name: k9s
os: ["linux", "darwin"]
examples:
  - input: "重启生产数据库"
    args: { deployment: "postgres-prod" }
---

## 使用说明

本技能通过 `kubectl rollout restart` 安全重启数据库 Pod。

### 权限要求
- 必须拥有目标命名空间的 `deployments/rollout` 更新权限

### 安全限制
- 禁止操作 `kube-system` 命名空间
- 自动添加 `--namespace=default`（若未指定）

## 执行逻辑

```bash
kubectl rollout restart deployment/{{ deployment }} --namespace={{ namespace | default("default") }}

> **人类读 Markdown，机器读 Frontmatter + 模板**。

---

## 三、核心组件：Skill Parser 与 Executor

OpenClaw 启动时自动扫描 `skills/` 目录：

### 1. **解析阶段**（parse-skill-md.ts）
- 提取 YAML Frontmatter → 构建 `SkillMetadata`
- 验证参数契约（类型、必填）
- 编译模板（Handlebars 语法）

### 2. **注册阶段**
```ts
const skill = parseSkillFile('skills/restart_db.SKILL.md');
skillRegistry.register(skill.name, skill);

// agent-core.ts
if (toolCall.name in skillRegistry) {
  const skill = skillRegistry.get(toolCall.name);
  
  // 1. 检查环境兼容性
  if (!isOSCompatible(skill.os)) {
    throw new Error(`Skill ${name} not supported on this OS`);
  }

  // 2. 安装依赖（若缺失）
  await installDependencies(skill.dependencies);

  // 3. 渲染命令模板
  const cmd = renderTemplate(skill.template, toolCall.args);

  // 4. 在沙箱中执行
  return execInSandbox(cmd);
}

dependencies:
  - type: python
    packages:
      - "pandas>=2.0"
      - "matplotlib"
    installer: uv  # 或 pip

os: ["linux", "darwin"]     # 不支持 Windows
arch: ["amd64", "arm64"]   # 不支持 32 位

function isSkillCompatible(skill: Skill): boolean {
  const currentOS = process.platform; // 'linux', 'darwin', 'win32'
  const currentArch = process.arch;   // 'x64', 'arm64'

  return (
    (skill.os?.includes(currentOS) ?? true) &&
    (skill.arch?.includes(currentArch) ?? true)
  );
}

// 注册时跳过不兼容技能
if (isSkillCompatible(skill)) {
  registry.register(skill.name, skill);
}

touch skills/hello_world.SKILL.md

---
name: hello_world
description: 向用户问好
parameters:
  - name: name
    type: string
    required: true
examples:
  - input: "打招呼"
    args: { name: "Alice" }
---

echo "Hello, {{ name }}! Today is $(date)."