OpenClaw Skill 实战指南：让 AI Agent 学会新技能

Skill 不是代码库，不是插件框架，而是一份给 AI 的上岗手册。

如果你用 OpenClaw 做过稍微复杂的事，一定会遇到这个场景：某些任务 Agent 总做不好，不是漏步骤就是选错工具。每次纠正，下次又忘。

Skill 就是解决这个问题的。 它把你的经验和规范打包成结构化指令，Agent 遇到对应场景时自动激活，按规矩干活。

本文从原理到实战，带你搞清楚 Skill 的运作机制，并亲手创建一个「一键发布 CSDN 博客」的 Skill。

一、Skill 的本质：一份结构化的上岗手册

想象你雇了一个实习生。你不会丢给他一整个代码库让他自己悟，而是给他一份操作手册——什么时候该做什么、怎么做、注意什么。

Skill 就是这份手册。

它告诉 AI Agent 三件事：
1. 什么时候用我（触发条件）
2. 怎么做（执行指令）
3. 需要什么工具（脚本和资源）

仅此而已。没有运行时，没有沙箱，没有依赖注入。纯粹的信息传递。

二、Skill 的目录结构：极简主义

skill-name/
├── SKILL.md        # 唯一必需文件：元数据 + 指令
├── scripts/        # 可执行脚本（Python / Bash 等）
├── references/     # 参考文档（按需加载，不常驻内存）
└── assets/         # 模板、图片等静态资源

只有 SKILL.md 是必需的。 其余目录按需添加，没有的不用创建。

这意味着一个 Skill 可以简单到只有一个 .md 文件——只要描述清楚，Agent 就能按图索骥。

三、SKILL.md 的结构：触发器 + 指令体

---
name: my-skill
description: "当用户想要……时使用此 Skill。核心触发逻辑写在这里。"
---
# 具体指令（只有触发后才会被加载到上下文）
...

关键在于 description 字段——它是触发器。Agent 每次收到用户请求时，会扫描所有 Skill 的 description，语义匹配成功则激活对应 Skill。

正文内容只有触发后才加载，不会长期占用上下文窗口。

四、三级加载机制：省 Token 的核心设计

Skill 的加载不是一股脑全塞进来，而是分三层渐进式加载：

这个设计的核心目标就一个：省 Token。

假设你装了 20 个 Skill，如果每个的完整指令都常驻上下文，光是 Skill 描述就要吃掉几千 Token。三级加载让大部分 Skill 只以一行 description 的代价存在，触发时才按需展开。

五、Skill 的工作流程

用户请求 → Agent 扫描 description → 匹配成功 → 加载 SKILL.md 正文
→ 按指令执行（调用脚本 / 读取参考 / 引用资源）→ 完成任务

5.1 触发匹配

Agent 收到用户请求后，会扫描所有已安装 Skill 的 description 字段。语义匹配成功则自动激活，无需用户手动指定。

这意味着 description 的质量直接决定 Skill 能否被正确触发。写得太模糊会被忽略，写得太窄会错过相关场景。

5.2 指令执行与自由度设计

Skill 加载后，Agent 按文档指令执行。根据任务的容错空间，指令可以设计成三种自由度：

设计原则：桥窄加栏杆，路宽少限制。

• 操作浏览器、调 API 这类容易翻车的事 → 低自由度，写死脚本
• 分析总结、创意写作这类灵活任务 → 高自由度，给方向就行

5.3 渐进加载策略

Agent 不会一次性读取 Skill 下的所有文件。典型加载路径：

1. 匹配到 description → 加载 SKILL.md 正文
2. 正文提到脚本路径 → 读取 scripts/ 下的文件
3. 脚本需要参考文档 → 读取 references/ 下的文件

每一步都是按需触发，有效控制上下文长度，降低消耗、提升响应速度。

5.4 四条核心设计原则

1. description 是门面：写清楚触发条件，这是 Skill 被发现的关键
2. 指令要具体但不冗余：Agent 需要「做什么」和「怎么做」，不需要「为什么」
3. 脚本处理脆弱操作：浏览器自动化、API 调用等容易出错的步骤，封装成脚本而非自然语言
4. 资源按需提供：参考文档和模板不要塞进正文，放在 references/ 和 assets/ 下按需加载

六、实战：用 skill-creator 创建 CSDN 自动发博 Skill

说了这么多原理，来点实际的。

目标：创建一个 Skill，实现 Markdown 文档一键转为 CSDN 草稿，支持图片自动上传、标签分类、原创声明。

Step 1：明确需求

Step 2：规划目录结构

csdn-blog/
├── SKILL.md              # 触发描述 + 使用指引
└── scripts/
    └── csdn_publish.py   # Playwright 自动化核心脚本

流程简单直接，不需要额外的参考文档和模板，精简结构减少冗余。

Step 3：核心脚本设计

脚本的核心逻辑拆解：

① 启动持久化浏览器

ctx = playwright.chromium.launch_persistent_context(
    USER_DATA_DIR,
    headless=False,      # CSDN 屏蔽无头浏览器，必须可视化
    viewport={"width": 1280, "height": 720},
    locale="zh-CN",
)

Cookie 保存在本地目录，下次启动自动复用，不用每次重新登录。

② 检测登录状态

page.goto("https://mp.csdn.net/mp_blog/creation/editor")
if has_login_iframe:
    wait_for_login(page)  # 阻塞等待用户手动扫码登录

CSDN 会检测无头浏览器，所以只能用有头模式。首次登录后 Cookie 持久化，后续无需重复。

③ 图片预处理

content = process_images(page, content, base_dir)

扫描 Markdown 中的本地图片引用，逐个上传到 CSDN CDN，替换为远程 URL。远程图片链接保持不变。

④ 写入标题与内容

page.fill("#txtTitle", title)
page.evaluate("(c) => CKEDITOR.instances.editor.setData(c)", content)

CSDN 使用 CKEditor 富文本编辑器，直接通过 JavaScript API 注入 HTML 内容，绕过 Markdown/富文本切换的不稳定性。

⑤ 设置类型与标签

page.click("input.el_mcm-radio__original[value='original']")
# 标签输入：点击展开 → 键盘输入 → 回车确认
tag_area.click()
page.keyboard.type(tag, delay=50)
page.keyboard.press("Enter")

标签输入框是自定义组件，fill() 方法会因为只读状态失败，需用 keyboard.type() 模拟键盘输入。

⑥ 保存草稿

page.click("button:has-text('保存草稿')")

Step 4：编写 SKILL.md

---
name: csdn-blog
description: "Publish blog drafts to CSDN via browser automation (Playwright).
Use when: user wants to post/publish/write a blog to CSDN, create CSDN draft.
NOT for: reading CSDN articles or non-CSDN platforms."
---
# CSDN Blog Publisher

## First-Time Setup
python {baseDir}/scripts/csdn_publish.py --login

## Usage
python {baseDir}/scripts/csdn_publish.py -t "标题" -f article.md
python {baseDir}/scripts/csdn_publish.py -t "标题" -c "内容" --tags Python AI

## Image Handling
本地图片自动上传到 CSDN CDN，远程图片链接保持不变。

## Troubleshooting
- 登录会话过期：重新执行 --login 缓存账号
- 内容写入失败：CSDN 前端 UI 更新，需微调选择器

注意 {baseDir} 占位符——Agent 在执行时会自动替换为 Skill 的实际路径，无需硬编码。

Step 5：让 skill-creator 生成

上面是手动拆解的设计过程，实际操作中可以直接告诉 OpenClaw：

"帮我创建一个 CSDN 自动发博客的 Skill，用 Playwright 自动化，支持 Markdown 输入、图片上传、标签设置，首次需要 --login 登录。"

skill-creator 会根据需求生成完整目录结构和代码，然后你测试、微调、定稿。

七、小结

写 Skill 的本质：将业务规则、操作流程、专属约束，压缩为 AI Agent 可精准识别、高效执行的标准化指令。

规则越精简，运行越稳定。Skill 适用于工程化场景——重复操作、固定流程、需要可靠性的任务。对于需要创意和灵活性的场景，自然语言指引就够了，不必过度工程化。