第 13 章 构建你自己的 Skill：从一个 SKILL.md 开始

第 11 章我们理解了 Skills 的真实工作方式——它们是 Markdown 文件，不是代码插件。第 12 章又介绍了 Cron 和 Webhooks 驱动的自动化触发机制。本章动手写两个完整的 Skill：入门版的 todo-local（把 #todo 消息追加写入本地 todo.txt，只需 bash 命令，零依赖）和进阶版的 github-digest（结合 GitHub CLI 实现每日 Issue/PR 摘要，配合 Cron 定时触发）。

13.1 Skill 开发的思维方式

在写第一行 Markdown 之前，先想清楚三件事。

首先，这个任务可以用 bash/CLI 工具完成吗？如果可以（绝大多数任务都可以），那写一个 SKILL.md 就够了。如果不能（例如需要复杂的状态机、GUI 操作），考虑用 Browser 工具或 Node 工具。

其次，模型什么情况下该用这个 Skill？这决定了 description 字段的措辞——它是写给模型读的，决定 Skill 的调用时机。

最后，有没有依赖工具？在 requires.bins 里声明，这样 OpenClaw 能在加载时提前检查，而不是在执行时报错。

13.2 入门 Skill：todo-local

13.2.1 需求描述

目标：你在 Slack 里发「#todo 买牛奶」，OpenClaw 把「买牛奶」追加写入 ~/todo.txt，并回复「已记录」。技术约束是不依赖任何外部 API 或工具，只用 echo 和 shell 内置命令。

13.2.2 创建 Skill 目录

Workspace Skills 默认存放在 ~/.openclaw/workspace/skills/：

mkdir -p ~/.openclaw/workspace/skills/todo-local

13.2.3 编写 SKILL.md

---
name: todo-local
description: "Append a todo item to the local ~/todo.txt file.
  Use when: user says '#todo <item>', 'add a todo', 'remember to...', or
  asks you to record a task. Also use when user asks to list their todos.
  NOT for: project management tools, remote task services (use those specific skills)."
metadata:
  openclaw:
    emoji: "✅"
---

# Todo Local Skill

Manage a simple local todo list stored in ~/todo.txt.

## Append a Todo Item

When the user wants to add a todo:

```bash
echo "- [ ] ITEM  ($(date '+%Y-%m-%d %H:%M'))" >> ~/todo.txt
echo "Added to ~/todo.txt"

Replace ITEM with the actual todo text extracted from the user’s message.

List Todos

When the user wants to see their todos:

if [ -f ~/todo.txt ]; then
  cat ~/todo.txt
else
  echo "(~/todo.txt is empty or doesn't exist)"
fi

Mark as Done

When the user marks a todo as done (mention item number or text):

# View current todos with line numbers first
cat -n ~/todo.txt
# Then use sed to replace [ ] with [x] on the matching line
sed -i 's/- \[ \] ITEM/- [x] ITEM/' ~/todo.txt

Notes

• The file is plain text, one item per line
• Completed items use [x], pending items use [ ]
• Always confirm after adding: “Added: ITEM”

### 13.2.4 验证 Skill 加载

```bash
# 查看 Skill 是否被正确识别
openclaw skill list
# 应该看到：✓ todo-local (workspace)

openclaw skill status todo-local
# ✓ todo-local: ready (no binary requirements)

13.2.5 测试效果

在 Slack 或 WebChat 里发 #todo 买牛奶，OpenClaw 应该识别到这是 todo-local Skill 的使用场景（因为 description 提到了 #todo），生成并执行 echo "- [ ] 买牛奶 (2026-03-02 15:30)" >> ~/todo.txt，然后回复「已添加到 ~/todo.txt：买牛奶」。

如果 Skill 没有被触发，可以通过 openclaw agent --message "#todo 买牛奶" --verbose 查看 Agent 的完整推理过程，观察它是否读到了 Skill 的 description。

13.3 进阶 Skill：github-digest

13.3.1 需求描述

目标有两个：手动问「今天 GitHub 有什么动态？」时 Agent 能给出一份 Issue/PR 摘要，结合 Cron 每天早上 9 点自动发一份日报。依赖工具是 GitHub CLI（gh），需要提前安装并完成 gh auth login。

13.3.2 创建 Skill 目录

mkdir -p ~/.openclaw/workspace/skills/github-digest

13.3.3 编写 SKILL.md

---
name: github-digest
description: "Get a daily digest of GitHub activity: new issues, PRs, and comments
  in tracked repositories. Use when: user asks about GitHub activity, 'what happened
  on GitHub today', or for daily standups. Requires: gh CLI installed and authenticated."
metadata:
  openclaw:
    emoji: "🐙"
    requires:
      bins: ["gh", "jq"]
---

# GitHub Digest Skill

Generate a digest of recent GitHub activity across your repositories.

## Prerequisites

```bash
# Verify gh is authenticated
gh auth status

List Recent Issues (last 24h)

gh issue list \
  --repo OWNER/REPO \
  --state open \
  --json number,title,createdAt,author,labels \
  --jq '.[] | select(.createdAt > (now - 86400 | strftime("%Y-%m-%dT%H:%M:%SZ"))) | "  #\(.number) \(.title) (@\(.author.login))"' \
  2>/dev/null || echo "  (none)"

List Recent PRs (last 24h)

gh pr list \
  --repo OWNER/REPO \
  --state open \
  --json number,title,createdAt,author,isDraft \
  --jq '.[] | select(.createdAt > (now - 86400 | strftime("%Y-%m-%dT%H:%M:%SZ"))) | "  #\(.number) \(.title) (@\(.author.login))\(if .isDraft then " [DRAFT]" else "" end)"' \
  2>/dev/null || echo "  (none)"

Get Activity for Multiple Repos

When the user wants activity across multiple repos, run the above commands for each
repo and combine the results. Example repos to check:

• Replace OWNER/REPO with the actual repository (e.g., facebook/react)
• Ask the user if they haven’t specified which repos to watch

Format for Daily Digest

Summarize the results in this format:

📅 GitHub Digest — [DATE]

**[REPO NAME]**
Issues opened: N
- #123 Title (@author)
- #124 Title (@author)

PRs opened: N
- #456 Title (@author)

---
(repeat for each repo)

Notes

• Run each repo’s commands sequentially to avoid rate limits
• If gh is not authenticated, prompt: “Please run ‘gh auth login’ first”
• For large orgs, add --limit 10 to avoid very long output

### 13.3.4 配置追踪的仓库

因为 Skill 本身只是通用的「说明书」，具体追踪哪些仓库由两种方式决定。

一种是在与 Agent 的对话里直接说「帮我追踪 `vercel/next.js` 和 `facebook/react` 的 GitHub 动态」，Agent 会记住这个偏好存入长期记忆或 Profile。

另一种是在 `AGENTS.md` 或 `SOUL.md` 里明确声明：

```markdown
## GitHub Tracking
Monitor these repositories daily:
- vercel/next.js
- facebook/react
- your-org/your-repo

13.3.5 配置 Cron 定时触发

在 ~/.openclaw/openclaw.json 里加入 Cron Job：

{
  agent: {
    model: "anthropic/claude-opus-4-6",
  },
  cron: [
    {
      id: "github-daily-digest",
      schedule: "0 9 * * *",
      message: "Generate a GitHub digest for today. Check my tracked repositories for new issues and PRs opened in the last 24 hours. Format as a daily standup summary.",
    }
  ],
}

13.4 Skill 写作技巧

13.4.1 description 字段的黄金公式

好的 description 能显著提升 Skill 的调用准确率。公式是：做什么 + 使用时机（多个示例短语） + 不适合什么场景 + 前提条件。

差的例子："Manage todo items"——太模糊，模型不知道什么时候该调用。

好的例子："Append a todo item to ~/todo.txt. Use when: '#todo', 'add a todo', 'remember to', 'remind me to', 'note that'. NOT for: Todoist/Things/Notion (use those skills). No prerequisites."——具体、有边界、有示例。

13.4.2 Commands 部分的写作规范

每个命令附上注释，解释它在做什么。用大写占位符（如 OWNER/REPO、ITEM）让模型清楚哪里需要替换。提供错误处理（2>/dev/null || echo "fallback"）避免 bash 报错让模型困惑。按操作类型分节（List / Create / Delete / Update），不要把所有命令混在一起。

13.4.3 何时用 Skill，何时直接让 Agent 用 bash

并非所有任务都需要写 Skill。如果这类任务会频繁重复出现，或者需要特定的调用规范（某个 CLI 工具的用法不直观），那就写个 Skill。如果只是偶发性的一次性操作，让 Agent 直接写 bash 命令就好。如果任务很通用（ls、grep、curl 等），不需要 Skill，模型本身就会。

13.5 把 Skill 分享给社区

如果你的 Skill 对其他人也有用，可以提交到 OpenClaw 仓库：

# 1. Fork openclaw/openclaw 仓库
# 2. 在 skills/<your-skill>/ 目录下创建 SKILL.md
# 3. 确保 description 清晰，requires.bins 完整
# 4. 提交 PR，标题格式：feat(skills): add <name> skill

PR 标准（参考 CONTRIBUTING.md）：SKILL.md 包含 When to Use / When NOT to Use 两节，测试过在 macOS 和 Linux 上的命令兼容性，如果依赖需要授权（API Key）在 Notes 里说明获取方式。

13.6 小结

本章通过两个 Skill 的完整实现，覆盖了 Skill 开发的核心要点。每个 Skill 只需要一个 SKILL.md 文件。description 字段决定调用时机，要写得具体且有边界。Commands 部分是给模型看的 bash 命令示例，用大写占位符标注需要替换的部分。requires.bins 声明依赖工具，OpenClaw 会在加载时检查。Cron 加 Skill 的组合可以实现每日定时自动化任务。通过 PR 向社区贡献 Skill 的门槛很低，写好 Markdown 就够了。

下一章，我们进入系统的安全层面：OpenClaw 如何确保这个「有完整系统访问权限的 AI」不被滥用。