Phase 4 / Ep 17: 理解 Skill 架构 —— SKILL.md 是灵魂

⏱ 预计阅读 4 分钟 更新于 2026/4/13

🎯 学习目标：深入理解 Skill 的定义规范和运行机制。

1. Skill 是什么？

Skill 是 OpenClaw 的能力声明单元。它不是可执行程序，而是一组指令和元数据，被注入到 Agent 的上下文中，告诉 AI "你能做什么、怎么做"。

2. Skill 的文件结构

graph TD
    subgraph Skill["📦 一个完整的 Skill"]
        SkillMD["SKILL.md\n元数据 + 指令\n（YAML frontmatter + Markdown）"]
        Scripts["scripts/（可选）\n辅助脚本"]
        Examples["examples/（可选）\n示例用法"]
        Resources["resources/（可选）\n模板 · 数据文件"]
    end

    SkillMD -->|"每次对话注入"| Context["Agent 上下文窗口"]
    Scripts -->|"Agent 调用"| Exec["工具执行"]

3. SKILL.md 格式规范

name: weather-query
description: 让 Agent 能够查询全球城市的天气信息
version: 1.0.0
author: your-username
tags: [weather, utility, api]
permissions: [network]

# 天气查询技能

## 使用场景
当用户询问天气相关问题时使用此技能。

## 操作步骤
1. 解析用户提到的城市名称
2. 调用 scripts/query_weather.sh 获取天气数据
3. 以友好的格式返回结果

## 输出格式
- 城市名称
- 当前温度
- 天气状况
- 未来 3 天预报

## 限制
- 仅支持中国和美国城市
- 每小时最多查询 60 次

YAML Frontmatter 字段

字段 必填 说明
name ✅ Skill 唯一标识
description ✅ 一句话描述
version ✅ 语义化版本号
author ✅ 作者
tags ❌ 标签列表
permissions ❌ 需要的权限声明

4. Skill 的运行机制

sequenceDiagram
    participant Boot as 启动阶段
    participant Agent as Agent
    participant Skill as SKILL.md
    participant LLM as LLM

    Boot->>Agent: 加载所有 Skill
    Agent->>Skill: 读取 SKILL.md 内容
    Agent->>Agent: 将 Skill 指令注入上下文

    Note over Agent: 用户发送消息
    Agent->>LLM: Prompt 包含 Skill 指令
    LLM->>Agent: "应使用 weather-query"
    Agent->>Agent: 执行 scripts/query_weather.sh
    Agent->>LLM: 提交执行结果

⚠️ Token 成本：每个 Skill 的文本都会被注入到上下文中，消耗 Token。不要安装不需要的 Skill！

下节预告： Ep 18，巡礼 10 大必装 Skill——web-search、file-manager、git-assist 等核心技能。