第 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 入门 Skilltodo-local13.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-local13.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.txtReplaceITEMwith the actual todo text extracted from the user’s message.List TodosWhen the user wants to see their todos:if[-f~/todo.txt];thencat~/todo.txtelseecho(~/todo.txt is empty or doesnt exist)fiMark as DoneWhen the user marks a todo as done (mention item number or text):# View current todos with line numbers firstcat-n~/todo.txt# Then use sed to replace [ ] with [x] on the matching linesed-is/- \[ \] ITEM/- [x] ITEM/~/todo.txtNotesThe file is plain text, one item per lineCompleted 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-localSkill 的使用场景因为 description 提到了#todo生成并执行echo - [ ] 买牛奶 (2026-03-02 15:30) ~/todo.txt然后回复「已添加到 ~/todo.txt买牛奶」。如果 Skill 没有被触发可以通过openclaw agent --message #todo 买牛奶 --verbose查看 Agent 的完整推理过程观察它是否读到了 Skill 的 description。13.3 进阶 Skillgithub-digest13.3.1 需求描述目标有两个手动问「今天 GitHub 有什么动态」时 Agent 能给出一份 Issue/PR 摘要结合 Cron 每天早上 9 点自动发一份日报。依赖工具是 GitHub CLIgh需要提前安装并完成gh auth login。13.3.2 创建 Skill 目录mkdir-p~/.openclaw/workspace/skills/github-digest13.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 statusList Recent Issues (last 24h)gh issue list\--repoOWNER/REPO\--stateopen\--jsonnumber,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)ghprlist\--repoOWNER/REPO\--stateopen\--jsonnumber,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 ReposWhen the user wants activity across multiple repos, run the above commands for eachrepo 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 watchFormat for Daily DigestSummarize 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)NotesRun each repo’s commands sequentially to avoid rate limitsIf 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-repo13.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 skillPR 标准参考 CONTRIBUTING.mdSKILL.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」不被滥用。
《OpenClaw架构与源码解读》· 第 13 章 构建你自己的 Skill：从一个 SKILL.md 开始
第 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 入门 Skilltodo-local13.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-local13.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.txtReplaceITEMwith the actual todo text extracted from the user’s message.List TodosWhen the user wants to see their todos:if[-f~/todo.txt];thencat~/todo.txtelseecho(~/todo.txt is empty or doesnt exist)fiMark as DoneWhen the user marks a todo as done (mention item number or text):# View current todos with line numbers firstcat-n~/todo.txt# Then use sed to replace [ ] with [x] on the matching linesed-is/- \[ \] ITEM/- [x] ITEM/~/todo.txtNotesThe file is plain text, one item per lineCompleted 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-localSkill 的使用场景因为 description 提到了#todo生成并执行echo - [ ] 买牛奶 (2026-03-02 15:30) ~/todo.txt然后回复「已添加到 ~/todo.txt买牛奶」。如果 Skill 没有被触发可以通过openclaw agent --message #todo 买牛奶 --verbose查看 Agent 的完整推理过程观察它是否读到了 Skill 的 description。13.3 进阶 Skillgithub-digest13.3.1 需求描述目标有两个手动问「今天 GitHub 有什么动态」时 Agent 能给出一份 Issue/PR 摘要结合 Cron 每天早上 9 点自动发一份日报。依赖工具是 GitHub CLIgh需要提前安装并完成gh auth login。13.3.2 创建 Skill 目录mkdir-p~/.openclaw/workspace/skills/github-digest13.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 statusList Recent Issues (last 24h)gh issue list\--repoOWNER/REPO\--stateopen\--jsonnumber,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)ghprlist\--repoOWNER/REPO\--stateopen\--jsonnumber,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 ReposWhen the user wants activity across multiple repos, run the above commands for eachrepo 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 watchFormat for Daily DigestSummarize 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)NotesRun each repo’s commands sequentially to avoid rate limitsIf 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-repo13.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 skillPR 标准参考 CONTRIBUTING.mdSKILL.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」不被滥用。
