从翻日志翻到怀疑人生说起

凌晨两点，我想查一下 OpenClaw 在 19:20 到 20:00 之间发生了什么。

听起来很简单对吧？但实际操作是这样的：

1
2
3
4
5
6
7
8

1. 打开 gateway.log → 发现时间戳有 UTC 和 +08:00 两种格式
2. 算时区 → 北京时间 19:20 = UTC 11:20
3. 用 grep 过滤 → 发现 JSON 运行日志在另一个文件里
4. 打开 /tmp/openclaw/openclaw-2026-03-04.log → 12MB 的结构化 JSON
5. 写 awk 命令解析 JSON → 行太长被截断
6. 换 python 写解析脚本 → 过滤 cron 心跳噪声
7. 交叉比对三个日志文件 → 去重
8. 终于拼出一份时间线

AI 帮我做完了这些，但整个过程用了十几轮对话，烧了不少 token。

然后我想：下次再查日志，还要再来一遍吗？

Skill 是什么

Claude Code 有一个叫 Skill 的机制。简单说：

Skill = 一份 Markdown 指令 + 可选的脚本/资源文件

它存在 ~/.claude/skills/你的技能名/ 目录下，Claude 在每次对话时会读取所有 skill 的名字和描述。当你的问题匹配某个 skill 的描述时，Claude 会自动加载这个 skill 的完整内容，按照里面的指令来行动。

跟 CLAUDE.md 的区别是：

  • CLAUDE.md 是永远加载的背景知识（“你要记住这些事”）
  • Skill 是按需触发的专项能力（“遇到这类问题，按这个套路来”）

一个 skill 的最小结构：

1
2
3
4

my-skill/
├── SKILL.md          # 必须有：技能描述 + 使用指令
└── scripts/          # 可选：辅助脚本
    └── helper.py

SKILL.md 的格式：

1
2
3
4
5
6
7
8

---
name: my-skill
description: 什么时候触发这个技能（这段话决定了 Claude 是否会使用它）
---

# 技能标题

具体指令写在这里...

实战：把"翻日志"变成一个 Skill

整个过程只有三步。

第一步：把手动操作提炼成脚本

我们刚才手动做的事情，本质上就是：

  1. 读多个日志文件（纯文本 + JSON 两种格式）
  2. 统一时区（UTC → 北京时间）
  3. 按时间范围过滤
  4. 去噪（过滤 cron 心跳等）
  5. 按事件类型分类（ERROR / RESTART / PLUGIN / TELEGRAM…）
  6. 去重（同一事件在多个日志文件中出现只保留一条）
  7. 输出结构化时间线

这些逻辑非常适合写成脚本。我让 AI 把刚才的解析逻辑整理成了一个 query_logs.py：

1
2
3
4
5
6
7
8

# 查询指定时间段
python3 query_logs.py --from "19:20" --to "20:00"

# 查最近半小时
python3 query_logs.py --last 30m

# 只看错误
python3 query_logs.py --last 1h --category error

脚本做的事情就是我们手动做的那 8 步，只不过它在 1 秒内完成。

第二步：写 SKILL.md

SKILL.md 要告诉 Claude 两件事：什么时候用 和 怎么用。

1
2
3
4
5
6

---
name: openclaw-logs
description: 查询和分析 OpenClaw gateway 日志。当用户提到「查日志」
  「openclaw 发生了什么」「openclaw 日志」「查看最近的错误」
  「openclaw 最近怎么了」时使用此技能。
---

description 是触发条件——写得越具体，匹配越准。我把能想到的问法都列进去了。

正文部分就是使用说明：脚本在哪、参数怎么用、输出长什么样。Claude 读到这个 skill 后，就知道该运行哪个命令、怎么解读输出。

第三步：放对位置

1
2
3
4

~/.claude/skills/openclaw-logs/
├── SKILL.md
└── scripts/
    └── query_logs.py

放好之后，下一次对话就自动生效了。不需要重启任何东西。

效果对比

之前（没有 skill）：

1
2
3
4
5
6
7
8

我：帮我查一下 openclaw 19:20 之后到 20:00 之间都发生了什么
AI：让我看看日志文件在哪...
AI：[读 gateway.log] 时间戳有两种格式...
AI：[写 awk 命令] 行太长了...
AI：[换 python 解析 JSON] ...
AI：[过滤噪声] ...
AI：[整理结果]
→ 十几轮对话，几分钟，大量 token

之后（有 skill）：

1
2
3
4

我：openclaw 最近半小时有什么报错没
AI：[运行 query_logs.py --last 30m --category error]
AI：最近半小时没有任何报错，一切正常。
→ 一轮对话，几秒钟

从"十几轮对话"到"一句话搞定"。

几个值得注意的点

1. description 要写得"贪心"一点

Claude 选择是否使用 skill 的唯一依据就是 description。宁可写多几种触发词，也不要写得太含蓄。比如：

1
2
3
4
5
6
7
8

# 太含蓄（可能漏触发）
description: OpenClaw log query tool

# 刚好（列举了用户可能的各种问法）
description: 查询和分析 OpenClaw gateway 日志。当用户提到
  「查日志」「openclaw 发生了什么」「openclaw 日志」
  「gateway 日志」「查看最近的错误」「openclaw 最近怎么了」
  「openclaw 报错」时使用此技能。

2. 脚本比指令更可靠

理论上你可以在 SKILL.md 里写一大段"先读这个文件、再用 awk 解析、然后过滤…“让 Claude 每次手动执行。但这样做的问题是：

  • 每次都要重新理解和执行，耗 token
  • Claude 可能每次的解析方式略有不同
  • 复杂逻辑容易出错

把确定性的操作封装成脚本，Claude 只需要 python3 script.py --last 30m，结果稳定、速度快、token 消耗极低。

3. Skill 和 CLAUDE.md 的分工

CLAUDE.mdSkill
加载时机每次对话都加载匹配到才加载
适合放通用原则、项目架构、注意事项特定任务的完整操作流程
典型内容“排查问题先实验后读码”“查日志时运行这个脚本”
大小建议精简（因为每次都要消耗 context）可以长一些（只在需要时加载）

简单说：CLAUDE.md 是性格，Skill 是技能。

4. 从痛苦中提取 Skill 的时机

最好的 skill 往往来自你刚做过的事。因为：

  • 你刚经历了完整的流程，知道哪些步骤是固定的
  • AI 刚帮你做过，代码和逻辑都在上下文里
  • 你知道哪些地方容易出错、哪些输出是噪声

就像我们这次：刚手动翻完日志，痛点还热乎着，趁这个劲头直接让 AI 把解析逻辑封装成脚本、写好 SKILL.md、测试通过、推到 GitHub——一气呵成。

如果等到下次再遇到同样的问题才想起来"上次好像应该做个 skill”，那时候上下文已经丢了，又得从头梳理。

这件事的本质

回到开头的问题：为什么要把翻日志做成 skill？

不是因为翻日志很难——AI 完全能做到。而是因为：

每次都让 AI 从零开始做同一件事，是一种浪费。浪费 token、浪费时间、浪费你的注意力。

Skill 的本质是 把 AI 的一次性能力变成可复用的能力。

你跟 AI 合作解决了一个问题 → 把解决方案沉淀成 skill → 下次同类问题自动按最优路径执行。

这不就是人类积累经验的方式吗？只不过现在，经验可以被编码成文件，让 AI 在每次对话的第一秒就站在上次的终点上。

本文基于 2026 年 3 月 4 日的实际操作。从手动翻日志到 skill 生效，总共花了大约 15 分钟。