13｜自定义 Skill 创作：打造专属自动化利器

文章目录摘要SEO 摘要目录开篇核心知识点1. 为什么需要自定义 Skill1.1 内置 Skill 的局限1.2 自定义 Skill 的价值1.3 Skill 开发 vs 普通脚本2. Skill 创建标准流程2.1 流程概览2.2 Step 1: 确定目标和功能2.3 Step 2: 创建目录结构3. SKILL.md 编写规范3.1 文件结构3.2 Metadata 板块3.3 Trigger 板块关键3.4 Capabilities 板块4.5 Error Handling 板块4.6 Configuration 板块3.7 Changelog 板块4. scripts 脚本开发4.1 语言选择4.2 Python 脚本模板4.3 Shell 脚本模板4.4 脚本规范专栏定位OpenClaw 从入门到精通第 13 章适读人群开发者、技术爱好者、AI应用创业者摘要虽然 OpenClaw 提供了丰富的内置 Skills但真正的超能力来自于你自己开发的定制化 Skills。本章将手把手教你从零创建一个完整的 SkillSkill 创建标准流程、SKILL.md 编写规范、scripts 脚本编写、references 文档编写。最后通过一个完整的「Git 操作 Skill」实战案例串联所有知识点。学完本章你将能够根据业务需求开发任何你需要的 Skill。SEO 摘要OpenClaw 自定义 Skill 开发教程、SKILL.md 编写规范、scripts 脚本开发、references 文档编写、Git Skill 实战案例。目录为什么需要自定义 SkillSkill 创建标准流程SKILL.md 编写规范scripts 脚本开发references 文档编写实战创建 Git 操作 Skill发布到 ClawHub常见错误与避坑指南术语注释面试高频问答深度扩展附录系列总结第 01-13 章版权声明开篇OpenClaw 内置的 Skills 解决了 80% 的常见需求但总有那么 20% 的场景是通用 Skill 覆盖不到的。比如你们公司有自己的内部系统需要操作特定的 API你的团队使用 Jira 来管理任务需要和 OpenClaw 集成你想要一个能自动操作你们公司内部后台的工具这些时候你就需要自己开发 Skill。好消息是开发一个 Skill 并不难。一个基本的 Skill 只需要一个SKILL.md定义文件一个或几个脚本文件只要掌握这两个核心你就能构建任何你需要的工具。核心知识点1. 为什么需要自定义 Skill1.1 内置 Skill 的局限痛点描述内部系统公司的 CRM、ERP、内部工具定制化特殊的工作流程和逻辑私有 API第三方服务没有公开 API特定场景行业特定的业务逻辑1.2 自定义 Skill 的价值没有自定义 Skill 用户 → 手动操作 → 30 分钟 ↓ 有自定义 Skill 用户 → OpenClaw → 自动操作 → 30 秒1.3 Skill 开发 vs 普通脚本维度普通脚本Skill调用方式手动运行OpenClaw 自然语言触发上下文无有知道用户是谁、当前项目参数传递手动传参通过自然语言理解输出打印到终端整合到对话中可复用性低高2. Skill 创建标准流程2.1 流程概览Step 1: 确定 Skill 的目标和功能 Step 2: 创建 Skill 目录结构 Step 3: 编写 SKILL.md Step 4: 开发 scripts Step 5: 编写 references 文档 Step 6: 测试 Skill Step 7: 发布到 ClawHub可选2.2 Step 1: 确定目标和功能在动手之前先回答以下问题这个 Skill 要解决什么问题用户会用什么话触发这个 Skill触发词需要调用哪些外部 API 或工具输入和输出是什么有哪些边界条件和错误处理2.3 Step 2: 创建目录结构# 在 skills 目录下创建新的 Skillcd~/.openclaw/skillsmkdirgit-workflowcdgit-workflow# 创建子目录mkdir-pscripts references assets完整目录结构skills/ └── git-workflow/ ├── SKILL.md # 必填Skill 定义文件 ├── scripts/ # 必填脚本目录 │ ├── main.py # 主脚本 │ └── utils.py # 辅助脚本可选 ├── references/ # 可选参考文档 │ ├── usage.md │ └── api.md └── assets/ # 可选静态资源 └── logo.png3. SKILL.md 编写规范3.1 文件结构# Skill: [Skill 名称] ## Metadata [基本信息] ## Description [详细描述] ## Trigger [何时触发] ## Capabilities [提供的能力] ## Parameters [参数说明] ## Examples [使用示例] ## Configuration [配置说明] ## Limitations [已知限制] ## Changelog [版本历史]3.2 Metadata 板块## Metadata - **Name:** git-workflow - **Version:** 1.0.0 - **Author:** Your Name - **License:** MIT - **Repository:** https://github.com/yourname/openclaw-skill-git - **Tags:** git, workflow, development - **Min OpenClaw Version:** 1.0.03.3 Trigger 板块关键Trigger 决定何时使用这个 Skill## Trigger ### Auto-Trigger Keywords 触发这个 Skill 的关键词 - git - 分支 - branch - merge - pr - pull request - 代码审查 - git flow ### Context Patterns 更具体的触发场景 - 帮我创建一个新分支 - 查看当前分支状态 - 把这个分支合并到 main - 创建一个 PR - 最近有哪些提交 ### NOT Trigger When 不应该触发这个 Skill 的情况 - 用户在说 GitHub 的 Git可能是其他意思 - 用户只是在问 Git 是什么概念性问题3.4 Capabilities 板块定义 Skill 提供的能力## Capabilities ### 1. create_branch **Description:** 创建新的 Git 分支 **Parameters:** | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | name | string | 是 | 分支名称 | | base | string | 否 | 基于哪个分支创建默认当前分支 | **Example:**Input: name“feature/new-feature”, base“main”Output: Successfully created branch ‘feature/new-feature’ from ‘main’### 2. list_branches **Description:** 列出所有本地和远程分支 **Parameters:** | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | local | boolean | 否 | 只显示本地分支 | | remote | boolean | 否 | 只显示远程分支 | **Example:**Input: localtrue, remotefalseOutput: 显示所有本地分支当前分支用 * 标记### 3. create_pr **Description:** 创建 Pull Request **Parameters:** | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | title | string | 是 | PR 标题 | | body | string | 否 | PR 描述 | | base | string | 否 | 目标分支默认 main | | draft | boolean | 否 | 是否为草稿 PR | **Example:**Input: title“feat: add new feature”, body“这个 PR 添加了…”, base“main”Output: PR 创建成功: https://github.com/xxx/yyy/pull/123### 4. recent_commits **Description:** 查看最近的提交记录 **Parameters:** | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | count | integer | 否 | 显示多少条默认 10 | | author | string | 否 | 只显示某个作者的提交 | **Example:**Input: count5Output:abc1234 (2026-03-30) feat: add logindef5678 (2026-03-29) fix: resolve bug…4.5 Error Handling 板块## Error Handling | 错误情况 | 返回信息 | 处理方式 | |---------|---------|---------| | 不是 Git 仓库 | 当前目录不是 Git 仓库 | 提示用户切换目录 | | 分支已存在 | 分支 {name} 已存在 | 提示用其他名称 | | 合并冲突 | 存在未解决的合并冲突 | 提示先解决冲突 | | Git 未安装 | Git 未安装或不在 PATH 中 | 提示安装 Git | | 网络错误 | 无法连接到远程仓库 | 检查网络连接 |4.6 Configuration 板块## Configuration ### Required Environment Variables - GIT_DEFAULT_REMOTE: 默认远程仓库名称默认 origin ### Optional Environment Variables - GIT_DEFAULT_BASE_BRANCH: 默认基础分支默认 main - GIT_PR_TEMPLATE: PR 描述模板 ### GitHub Integration (Optional) 如果需要创建 PR需要配置 - GITHUB_TOKEN: GitHub Personal Access Token3.7 Changelog 板块## Changelog ### v1.0.0 (2026-03-30) - 初始版本 - 支持 create_branch, list_branches, create_pr, recent_commits ### v1.1.0 (2026-04-15) - 添加 merge_branch 功能 - 修复分支列表显示问题4. scripts 脚本开发4.1 语言选择语言优势适用场景Python生态丰富、易读API 调用、数据处理Shell简洁、Unix 工具集成Git、系统命令Node.jsJSON 处理好、异步Webhook、实时处理推荐优先使用 Python大多数场景Shell系统命令集成。4.2 Python 脚本模板#!/usr/bin/env python3 Git Workflow Skill - Git 操作辅助工具 importsysimportjsonimportsubprocessfromtypingimportDict,Any,Optional,List# CLI 接口 defmain():主入口解析命令行参数并执行对应功能iflen(sys.argv)2:print(json.dumps({error:Usage: python main.py action [args...]}))sys.exit(1)actionsys.argv[1]argssys.argv[2:]# 调用对应的处理函数ifactioncreate_branch:resultcreate_branch(*args)elifactionlist_branches:resultlist_branches(*args)elifactioncreate_pr:resultcreate_pr(*args)elifactionrecent_commits:resultrecent_commits(*args)else:result{error:fUnknown action:{action}}# 输出 JSON 格式结果print(json.dumps(result,ensure_asciiFalse))# 功能实现 defrun_git_command(*args)-subprocess.CompletedProcess:执行 Git 命令的辅助函数try:resultsubprocess.run([git]list(args),capture_outputTrue,textTrue,checkTrue)returnresultexceptsubprocess.CalledProcessErrorase:returneexceptFileNotFoundError:raiseRuntimeError(Git is not installed or not in PATH)defcreate_branch(name:str,base:strHEAD)-Dict[str,Any]:创建新分支ifnotname:return{error:Branch name is required}# 检查分支是否已存在checkrun_git_command(rev-parse,--verify,name)ifcheck.returncode0:return{error:fBranch {name} already exists}# 创建分支resultrun_git_command(checkout,-b,name)ifresult.returncode!0:return{error:fFailed to create branch:{result.stderr}}return{success:True,message:fSuccessfully created and switched to branch {name},branch:name}deflist_branches(local:boolTrue,remote:boolTrue)-Dict[str,Any]:列出分支branches{local:[],remote:[]}iflocal:resultrun_git_command(branch)ifresult.returncode0:currentresult.stdout.strip().split(\n)branches[local][{name:b.strip(* ).strip(),current:*inb}forbincurrentifb.strip()]ifremote:resultrun_git_command(branch,-r)ifresult.returncode0:branches[remote][b.strip()forbinresult.stdout.strip().split(\n)ifb.strip()and-notinb]return{success:True,branches:branches}defrecent_commits(count:int10,author:Optional[str]None)-Dict[str,Any]:查看最近的提交cmd[log,f-{count},--prettyformat:%H|%s|%ad|%an,--dateshort]ifauthor:cmd.extend([--author,author])resultrun_git_command(*cmd)ifresult.returncode!0:return{error:fFailed to get commits:{result.stderr}}commits[]forlineinresult.stdout.strip().split(\n):if|inline:partsline.split(|)iflen(parts)4:commits.append({hash:parts[0],message:parts[1],date:parts[2],author:parts[3]})return{success:True,count:len(commits),commits:commits}defcreate_pr(title:str,body:str,base:strmain,draft:boolFalse)-Dict[str,Any]:创建 Pull Request需要 GitHub CLI# 检查 gh CLI 是否可用try:subprocess.run([gh,--version],capture_outputTrue,checkTrue)except(subprocess.CalledProcessError,FileNotFoundError):return{error:GitHub CLI (gh) is not installed or not in PATH}cmd[gh,pr,create,--title,title]ifbody:cmd.extend([--body,body])cmd.extend([--base,base])ifdraft:cmd.append(--draft)resultsubprocess.run(cmd,capture_outputTrue,textTrue)ifresult.returncode!0:return{error:fFailed to create PR:{result.stderr}}return{success:True,message:Pull Request created successfully,url:result.stdout.strip()}# 入口 if__name____main__:main()4.3 Shell 脚本模板#!/usr/bin/env bash# Git Workflow Skill - Shell 实现set-e# 解析参数ACTION$1shiftcase$ACTIONinstatus)gitstatus;;log)COUNT${1:-10}gitlog--oneline-n$COUNT;;branches)gitbranch-a;;current_branch)gitbranch --show-current;;*)echo{\error\:\Unknown action:$ACTION\}exit1;;esac4.4 脚本规范输入输出规范主脚本通过命令行参数接收指令输出统一使用 JSON 格式stdout错误信息输出到 stderr错误处理规范defmain():try:# 业务逻辑passexceptGitNotFoundError:print(json.dumps({error:Git is not installed}))sys.exit(1)exceptExceptionase:print(json.dumps({eTEST INJECTION WORKS