一句话介绍OpenClaw Skill 是 AI 编程助手的能力扩展包像给 AI 装插件一样让它在特定领域处理 PDF、操作数据库等变成专家级助手。一、什么是 OpenClaw SkillOpenClaw Skill 是一种模块化能力扩展机制每个 Skill 本质上是一个包含以下内容的目录SKILL.md技能说明文件告诉 AI 这个 Skill 能做什么、怎么做scripts/可直接执行的脚本Python / Node.js / Bashreferences/参考文档AI 需要时按需加载assets/模板文件、图片等静态资源与普通 prompt 的区别Skill 是可复用、可版本管理、可分发的完整知识包团队内部一次开发所有人一键复用。二、Skill 安装标准流程第一步下载 / 导入 Skill方式一从 zip 包导入推荐# 将 skill 包放置到项目 skills 目录 cp ~/Downloads/my-skill.zip /path/to/project/.openclaw/skills/ # 解压 cd .openclaw/skills/ unzip my-skill.zip # 验证目录结构 ls my-skill/ # 预期输出SKILL.md scripts/ references/ assets/方式二从源码克隆cd .openclaw/skills/ git clone https://github.com/your-org/my-skill.git # 安装 Skill 依赖如有 package.json cd my-skill npm install # 安装 Python 依赖如有 requirements.txt pip3 install -r requirements.txt方式三手动创建开发者# 使用官方初始化脚本需先加载 skill-creator skill python3 /path/to/skill-creator/scripts/init_skill.py my-hljs-keywordnew-skill \ --path .openclaw/skills/第三步启用 SkillSkill 放置到.openclaw/skills/目录后Openclaw 会自动扫描并加载无需手动注册。# 确认 Skill 目录结构正确 tree .openclaw/skills/my-skill/ # 输出示例 # .openclaw/skills/my-skill/ # ├── SKILL.md ← 必须存在 # ├── scripts/ # │ └── run.py # └── references/ # └── api-docs.md关键原则SKILL.md必须存在且包含有效的 YAML frontmatter否则 Skill 加载失败。第四步验证安装在 Openclaw 对话框中输入以下内容验证请列出当前已加载的所有 Skill或直接触发 Skill# 以 list-skill skill 为例 请用 list-skill skill 列出你所掌握的所有技能AI 若能正确识别并执行则安装成功。三、Skill 一键升级与批量更新最佳实践单个 Skill 升级# 方式一替换目录zip 包方式 cd .openclaw/skills/ rm -rf my-skill/ # 备份后再删除 unzip ~/Downloads/my-skill-v2.zip # 方式二git pull源码方式 cd .openclaw/skills/my-skill/ git pull origin main # 更新依赖 npm install # Node.js 项目 pip3 install -r requirements.txt --upgrade # Python 项目批量更新所有 git 管理的 Skill#!/bin/bash # 保存为 update-all-skills.sh赋权后执行 SKILLS_DIR.openclaw/skills echo 开始批量更新所有 Skill... hljs-keywordfor skill_dir hljs-keywordin$SKILLS_DIR/*/; do hljs-keywordif [ -d $skill_dir/.git ]; then skill_name$(basename $skill_dir) echo 更新: $skill_name cd $skill_dir git pull origin main 2amp;1 # 自动安装新增依赖 [ -f package.json ] amp;amp; npm install --silent [ -f requirements.txt ] amp;amp; pip3 install -r requirements.txt -q cd - /dev/hljs-keywordnull echo ✅ $skill_name 更新完成 fi done echo 所有 Skill 更新完毕chmod x update-all-skills.sh ./update-all-skills.sh版本管理建议# 升级前打标签备份 cd .openclaw/skills/my-skill/ git tag v1.0.0-backup git push origin v1.0.0-backup # 回滚到指定版本 git checkout v1.0.0-backup四、配置文件修改要点4.1 SKILL.md 核心配置SKILL.md的 YAML frontmatter 是 Skill 的身份证--- name: my-skill # 唯一标识只用小写字母和连字符 description: 一句话描述 Skill 的用途和触发场景越具体越好 metadata: version: 1.0.0 author: your-name requires: node: 18.0.0# 运行环境要求 python: 3.9 ---避坑name字段必须与目录名完全一致否则 Skill 识别异常。4.2 环境变量与密钥安全禁止将密钥硬编码在 SKILL.md 或脚本中# ❌ 错误做法 APP_SECREThardcoded_secret_123 # ✅ 正确做法使用环境变量 hljs-keywordexport MY_SKILL_API_KEYyour_key_here # 或写入 .env 文件确保加入 .gitignore echo MY_SKILL_API_KEYyour_key_here .env echo .env .gitignore在脚本中读取// Node.js hljs-keywordconst apiKey process.env.MY_SKILL_API_KEY; hljs-keywordif (!apiKey) { console.error(❌ 请设置环境变量 MY_SKILL_API_KEY); process.exit(1); }# Python hljs-keywordimport os api_key os.environ.get(MY_SKILL_API_KEY) hljs-keywordifhljs-keywordnot api_key: raise EnvironmentError(请设置环境变量 MY_SKILL_API_KEY)4.3 脚本权限配置# 为脚本添加可执行权限 chmod x .openclaw/skills/my-skill/scripts/.sh chmod x .openclaw/skills/my-skill/scripts/.py # 验证权限 ls -la .openclaw/skills/my-skill/scripts/ # 预期-rwxr-xr-x 1 user staff ...4.4 自启动与持久化配置对于需要后台服务的 Skill如本地 API 服务推荐使用系统服务管理# macOS使用 launchd cat ~/Library/LaunchAgents/com.myskill.plist EOF ?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN... plist version1.0 dict keyLabel/key hljs-keywordstringcom.myskill/hljs-keywordstring keyProgramArguments/key array hljs-keywordstring/usr/local/bin/node/hljs-keywordstring hljs-keywordstring/path/to/.openclaw/skills/my-skill/scripts/server.js/hljs-keywordstring /array keyRunAtLoad/key true/ /dict /plist EOF launchctl load ~/Library/LaunchAgents/com.myskill.plist五、常见失败原因与快速排错问题一Skill 未被识别加载失败现象让 AI 使用某 SkillAI 说没有找到该 Skill排查步骤# 1. 检查目录位置是否正确 ls .openclaw/skills/ # Skill 目录必须在此处 # 2. 检查 SKILL.md 是否存在 ls .openclaw/skills/my-skill/SKILL.md # 若输出No such file则是目录结构问题 # 3. 检查 YAML frontmatter 语法 head -20 .openclaw/skills/my-skill/SKILL.md # 确认格式--- 开头包含 name 和 description 字段常见原因目录多套一层如skills/my-skill/my-skill/SKILL.md问题二脚本执行报错依赖缺失现象Error: Cannot find module axios或ModuleNotFoundError: No module named requests# Node.js 依赖修复 cd .openclaw/skills/my-skill/ npm install # Python 依赖修复 pip3 install -r requirements.txt # 全局安装缺失模块临时方案 npm install -g axios pip3 install requests问题三权限拒绝Permission Denied现象zsh: permission denied: ./scripts/run.sh# 一键修复脚本权限 chmod x .openclaw/skills/my-skill/scripts/* # 若是 macOS 安全拦截先移除隔离属性 xattr -d com.apple.quarantine .openclaw/skills/my-skill/scripts/run.sh问题四环境变量未生效现象脚本提示请设置环境变量 XXX但已经 export 过# 确认变量在当前 shell 中生效 echo $MY_SKILL_API_KEY # 若为空重新 source 配置文件 source ~/.zshrc # zsh 用户 source ~/.bashrc # bash 用户 # 永久写入 shell 配置 echo export MY_SKILL_API_KEYyour_key ~/.zshrc source ~/.zshrc问题五Skill 间冲突现象加载多个 Skill 后AI 混淆触发逻辑解决方案# 检查是否有同名 Skill ls .openclaw/skills/ | sort | uniq -d # 重命名冲突 Skill mv .openclaw/skills/publisher/ .openclaw/skills/wechat-publisher/ # 同步修改 SKILL.md 中的 name 字段 sed -i s/^name: publisher/name: wechat-publisher/ \ .openclaw/skills/wechat-publisher/SKILL.md问题六Node.js / Python 版本不兼容# 检查当前版本 node -v amp;amp; python3 --version # 使用 nvm 切换 Node.js 版本 nvm install 20 nvm use 20 # 使用 pyenv 切换 Python 版本 pyenv install 3.11 pyenv local 3.11六、生产环境稳定运行建议6.1 目录结构规范.openclaw/ └── skills/ ├── wechat-publisher/ # 生产 Skill │ ├── SKILL.md │ ├── scripts/ │ ├── references/ │ └── _meta.json # 版本元信息 └── _disabled/ # 暂时禁用的 Skill前缀 _ 不会被加载 └── old-skill/6.2 错误处理与日志生产级脚本必须包含完整错误处理// Node.js 最佳实践 hljs-keywordasynchljs-keywordfunction main() { hljs-keywordtry { hljs-keywordconst result hljs-keywordawait doSomething(); console.log(✅ 执行成功:, result); } catch (err) { console.error(❌ 执行失败:, err.message); // 写入日志文件 fs.appendFileSync(skill-error.log, [${hljs-keywordnew Date().toISOString()}] ${err.stack}\n ); process.exit(1); } }6.3 定期健康检查脚本#!/bin/bash # health-check.sh - 每天运行一次 SKILLS_DIR.openclaw/skills FAIL_COUNT0 hljs-keywordfor skill_dir hljs-keywordin$SKILLS_DIR/*/; do skill_name$(basename $skill_dir) # 检查 SKILL.md 存在 hljs-keywordif [ ! -f $skill_dir/SKILL.md ]; then echo ⚠️ $skill_name: 缺少 SKILL.md FAIL_COUNT$((FAIL_COUNT 1)) fi # 检查依赖完整性 hljs-keywordif [ -f $skill_dir/package.json ]; then hljs-keywordif [ ! -d $skill_dir/node_modules ]; then echo ⚠️ $skill_name: node_modules 缺失请运行 npm install FAIL_COUNT$((FAIL_COUNT 1)) fi fi done hljs-keywordif [ $FAIL_COUNT -eq 0 ]; then echo ✅ 所有 Skill 健康检查通过 hljs-keywordelse echo ❌ 发现 $FAIL_COUNT 个问题请及时修复 fi七、官方推荐规范与避坑指南✅ 最佳实践清单✅ SKILL.md 描述精准、具体触发关键词明确 ✅ 脚本支持 --help 参数方便快速了解用法 ✅ 所有密钥通过环境变量传入不硬编码 ✅ 提供 README.md记录安装步骤和使用示例 ✅ 脚本有完整的错误处理和退出码 ✅ 使用语义化版本号v1.2.3管理 Skill 版本 ✅ 大型依赖文件加入 .gitignorenode_modules、__pycache__ ✅ 定期运行健康检查脚本提前发现问题❌ 常见坑点一定要避开❌ SKILL.md 描述太泛导致 AI 频繁误触发 ❌ 脚本路径写死用绝对路径换机器就失效 ❌ 忘记 chmod x脚本无法执行 ❌ 多个 Skill 的 name 字段重复互相覆盖 ❌ 依赖版本不固定package.json 用 ^升级后行为改变 ❌ 临时测试文件未清理污染 Skill 目录 ❌ 忘记处理 API 限流rate limit脚本崩溃没有重试逻辑目录命名规范# ✅ 正确命名kebab-hljs-keywordcase wechat-publisher pdf-processor># 安装新 Skill cp -r my-skill/ .openclaw/skills/ # 验证结构 ls .openclaw/skills/my-skill/SKILL.md # 更新 Skillgit 方式 cd .openclaw/skills/my-skill amp;amp; git pull # 修复权限 chmod x .openclaw/skills/my-skill/scripts/* # 修复 Node.js 依赖 cd .openclaw/skills/my-skill amp;amp; npm install # 修复 Python 依赖 pip3 install -r .openclaw/skills/my-skill/requirements.txt # 临时禁用 Skill重命名前缀 mv .openclaw/skills/my-skill .openclaw/skills/_my-skill # 健康检查 bash .openclaw/skills/health-check.sh做一个有深度的技术人历史精彩文章推荐从被动到主动主观能动性的力量复利滚雪球的魅力基于“第一性原理”的思路工作聊聊“晋升”到底该怎么做万能方法之如何使用MECE分析法高效解决问题
OpenClaw Skill 完全指南：安装、升级、管理与排错最佳实践
一句话介绍OpenClaw Skill 是 AI 编程助手的能力扩展包像给 AI 装插件一样让它在特定领域处理 PDF、操作数据库等变成专家级助手。一、什么是 OpenClaw SkillOpenClaw Skill 是一种模块化能力扩展机制每个 Skill 本质上是一个包含以下内容的目录SKILL.md技能说明文件告诉 AI 这个 Skill 能做什么、怎么做scripts/可直接执行的脚本Python / Node.js / Bashreferences/参考文档AI 需要时按需加载assets/模板文件、图片等静态资源与普通 prompt 的区别Skill 是可复用、可版本管理、可分发的完整知识包团队内部一次开发所有人一键复用。二、Skill 安装标准流程第一步下载 / 导入 Skill方式一从 zip 包导入推荐# 将 skill 包放置到项目 skills 目录 cp ~/Downloads/my-skill.zip /path/to/project/.openclaw/skills/ # 解压 cd .openclaw/skills/ unzip my-skill.zip # 验证目录结构 ls my-skill/ # 预期输出SKILL.md scripts/ references/ assets/方式二从源码克隆cd .openclaw/skills/ git clone https://github.com/your-org/my-skill.git # 安装 Skill 依赖如有 package.json cd my-skill npm install # 安装 Python 依赖如有 requirements.txt pip3 install -r requirements.txt方式三手动创建开发者# 使用官方初始化脚本需先加载 skill-creator skill python3 /path/to/skill-creator/scripts/init_skill.py my-hljs-keywordnew-skill \ --path .openclaw/skills/第三步启用 SkillSkill 放置到.openclaw/skills/目录后Openclaw 会自动扫描并加载无需手动注册。# 确认 Skill 目录结构正确 tree .openclaw/skills/my-skill/ # 输出示例 # .openclaw/skills/my-skill/ # ├── SKILL.md ← 必须存在 # ├── scripts/ # │ └── run.py # └── references/ # └── api-docs.md关键原则SKILL.md必须存在且包含有效的 YAML frontmatter否则 Skill 加载失败。第四步验证安装在 Openclaw 对话框中输入以下内容验证请列出当前已加载的所有 Skill或直接触发 Skill# 以 list-skill skill 为例 请用 list-skill skill 列出你所掌握的所有技能AI 若能正确识别并执行则安装成功。三、Skill 一键升级与批量更新最佳实践单个 Skill 升级# 方式一替换目录zip 包方式 cd .openclaw/skills/ rm -rf my-skill/ # 备份后再删除 unzip ~/Downloads/my-skill-v2.zip # 方式二git pull源码方式 cd .openclaw/skills/my-skill/ git pull origin main # 更新依赖 npm install # Node.js 项目 pip3 install -r requirements.txt --upgrade # Python 项目批量更新所有 git 管理的 Skill#!/bin/bash # 保存为 update-all-skills.sh赋权后执行 SKILLS_DIR.openclaw/skills echo 开始批量更新所有 Skill... hljs-keywordfor skill_dir hljs-keywordin$SKILLS_DIR/*/; do hljs-keywordif [ -d $skill_dir/.git ]; then skill_name$(basename $skill_dir) echo 更新: $skill_name cd $skill_dir git pull origin main 2amp;1 # 自动安装新增依赖 [ -f package.json ] amp;amp; npm install --silent [ -f requirements.txt ] amp;amp; pip3 install -r requirements.txt -q cd - /dev/hljs-keywordnull echo ✅ $skill_name 更新完成 fi done echo 所有 Skill 更新完毕chmod x update-all-skills.sh ./update-all-skills.sh版本管理建议# 升级前打标签备份 cd .openclaw/skills/my-skill/ git tag v1.0.0-backup git push origin v1.0.0-backup # 回滚到指定版本 git checkout v1.0.0-backup四、配置文件修改要点4.1 SKILL.md 核心配置SKILL.md的 YAML frontmatter 是 Skill 的身份证--- name: my-skill # 唯一标识只用小写字母和连字符 description: 一句话描述 Skill 的用途和触发场景越具体越好 metadata: version: 1.0.0 author: your-name requires: node: 18.0.0# 运行环境要求 python: 3.9 ---避坑name字段必须与目录名完全一致否则 Skill 识别异常。4.2 环境变量与密钥安全禁止将密钥硬编码在 SKILL.md 或脚本中# ❌ 错误做法 APP_SECREThardcoded_secret_123 # ✅ 正确做法使用环境变量 hljs-keywordexport MY_SKILL_API_KEYyour_key_here # 或写入 .env 文件确保加入 .gitignore echo MY_SKILL_API_KEYyour_key_here .env echo .env .gitignore在脚本中读取// Node.js hljs-keywordconst apiKey process.env.MY_SKILL_API_KEY; hljs-keywordif (!apiKey) { console.error(❌ 请设置环境变量 MY_SKILL_API_KEY); process.exit(1); }# Python hljs-keywordimport os api_key os.environ.get(MY_SKILL_API_KEY) hljs-keywordifhljs-keywordnot api_key: raise EnvironmentError(请设置环境变量 MY_SKILL_API_KEY)4.3 脚本权限配置# 为脚本添加可执行权限 chmod x .openclaw/skills/my-skill/scripts/.sh chmod x .openclaw/skills/my-skill/scripts/.py # 验证权限 ls -la .openclaw/skills/my-skill/scripts/ # 预期-rwxr-xr-x 1 user staff ...4.4 自启动与持久化配置对于需要后台服务的 Skill如本地 API 服务推荐使用系统服务管理# macOS使用 launchd cat ~/Library/LaunchAgents/com.myskill.plist EOF ?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN... plist version1.0 dict keyLabel/key hljs-keywordstringcom.myskill/hljs-keywordstring keyProgramArguments/key array hljs-keywordstring/usr/local/bin/node/hljs-keywordstring hljs-keywordstring/path/to/.openclaw/skills/my-skill/scripts/server.js/hljs-keywordstring /array keyRunAtLoad/key true/ /dict /plist EOF launchctl load ~/Library/LaunchAgents/com.myskill.plist五、常见失败原因与快速排错问题一Skill 未被识别加载失败现象让 AI 使用某 SkillAI 说没有找到该 Skill排查步骤# 1. 检查目录位置是否正确 ls .openclaw/skills/ # Skill 目录必须在此处 # 2. 检查 SKILL.md 是否存在 ls .openclaw/skills/my-skill/SKILL.md # 若输出No such file则是目录结构问题 # 3. 检查 YAML frontmatter 语法 head -20 .openclaw/skills/my-skill/SKILL.md # 确认格式--- 开头包含 name 和 description 字段常见原因目录多套一层如skills/my-skill/my-skill/SKILL.md问题二脚本执行报错依赖缺失现象Error: Cannot find module axios或ModuleNotFoundError: No module named requests# Node.js 依赖修复 cd .openclaw/skills/my-skill/ npm install # Python 依赖修复 pip3 install -r requirements.txt # 全局安装缺失模块临时方案 npm install -g axios pip3 install requests问题三权限拒绝Permission Denied现象zsh: permission denied: ./scripts/run.sh# 一键修复脚本权限 chmod x .openclaw/skills/my-skill/scripts/* # 若是 macOS 安全拦截先移除隔离属性 xattr -d com.apple.quarantine .openclaw/skills/my-skill/scripts/run.sh问题四环境变量未生效现象脚本提示请设置环境变量 XXX但已经 export 过# 确认变量在当前 shell 中生效 echo $MY_SKILL_API_KEY # 若为空重新 source 配置文件 source ~/.zshrc # zsh 用户 source ~/.bashrc # bash 用户 # 永久写入 shell 配置 echo export MY_SKILL_API_KEYyour_key ~/.zshrc source ~/.zshrc问题五Skill 间冲突现象加载多个 Skill 后AI 混淆触发逻辑解决方案# 检查是否有同名 Skill ls .openclaw/skills/ | sort | uniq -d # 重命名冲突 Skill mv .openclaw/skills/publisher/ .openclaw/skills/wechat-publisher/ # 同步修改 SKILL.md 中的 name 字段 sed -i s/^name: publisher/name: wechat-publisher/ \ .openclaw/skills/wechat-publisher/SKILL.md问题六Node.js / Python 版本不兼容# 检查当前版本 node -v amp;amp; python3 --version # 使用 nvm 切换 Node.js 版本 nvm install 20 nvm use 20 # 使用 pyenv 切换 Python 版本 pyenv install 3.11 pyenv local 3.11六、生产环境稳定运行建议6.1 目录结构规范.openclaw/ └── skills/ ├── wechat-publisher/ # 生产 Skill │ ├── SKILL.md │ ├── scripts/ │ ├── references/ │ └── _meta.json # 版本元信息 └── _disabled/ # 暂时禁用的 Skill前缀 _ 不会被加载 └── old-skill/6.2 错误处理与日志生产级脚本必须包含完整错误处理// Node.js 最佳实践 hljs-keywordasynchljs-keywordfunction main() { hljs-keywordtry { hljs-keywordconst result hljs-keywordawait doSomething(); console.log(✅ 执行成功:, result); } catch (err) { console.error(❌ 执行失败:, err.message); // 写入日志文件 fs.appendFileSync(skill-error.log, [${hljs-keywordnew Date().toISOString()}] ${err.stack}\n ); process.exit(1); } }6.3 定期健康检查脚本#!/bin/bash # health-check.sh - 每天运行一次 SKILLS_DIR.openclaw/skills FAIL_COUNT0 hljs-keywordfor skill_dir hljs-keywordin$SKILLS_DIR/*/; do skill_name$(basename $skill_dir) # 检查 SKILL.md 存在 hljs-keywordif [ ! -f $skill_dir/SKILL.md ]; then echo ⚠️ $skill_name: 缺少 SKILL.md FAIL_COUNT$((FAIL_COUNT 1)) fi # 检查依赖完整性 hljs-keywordif [ -f $skill_dir/package.json ]; then hljs-keywordif [ ! -d $skill_dir/node_modules ]; then echo ⚠️ $skill_name: node_modules 缺失请运行 npm install FAIL_COUNT$((FAIL_COUNT 1)) fi fi done hljs-keywordif [ $FAIL_COUNT -eq 0 ]; then echo ✅ 所有 Skill 健康检查通过 hljs-keywordelse echo ❌ 发现 $FAIL_COUNT 个问题请及时修复 fi七、官方推荐规范与避坑指南✅ 最佳实践清单✅ SKILL.md 描述精准、具体触发关键词明确 ✅ 脚本支持 --help 参数方便快速了解用法 ✅ 所有密钥通过环境变量传入不硬编码 ✅ 提供 README.md记录安装步骤和使用示例 ✅ 脚本有完整的错误处理和退出码 ✅ 使用语义化版本号v1.2.3管理 Skill 版本 ✅ 大型依赖文件加入 .gitignorenode_modules、__pycache__ ✅ 定期运行健康检查脚本提前发现问题❌ 常见坑点一定要避开❌ SKILL.md 描述太泛导致 AI 频繁误触发 ❌ 脚本路径写死用绝对路径换机器就失效 ❌ 忘记 chmod x脚本无法执行 ❌ 多个 Skill 的 name 字段重复互相覆盖 ❌ 依赖版本不固定package.json 用 ^升级后行为改变 ❌ 临时测试文件未清理污染 Skill 目录 ❌ 忘记处理 API 限流rate limit脚本崩溃没有重试逻辑目录命名规范# ✅ 正确命名kebab-hljs-keywordcase wechat-publisher pdf-processor># 安装新 Skill cp -r my-skill/ .openclaw/skills/ # 验证结构 ls .openclaw/skills/my-skill/SKILL.md # 更新 Skillgit 方式 cd .openclaw/skills/my-skill amp;amp; git pull # 修复权限 chmod x .openclaw/skills/my-skill/scripts/* # 修复 Node.js 依赖 cd .openclaw/skills/my-skill amp;amp; npm install # 修复 Python 依赖 pip3 install -r .openclaw/skills/my-skill/requirements.txt # 临时禁用 Skill重命名前缀 mv .openclaw/skills/my-skill .openclaw/skills/_my-skill # 健康检查 bash .openclaw/skills/health-check.sh做一个有深度的技术人历史精彩文章推荐从被动到主动主观能动性的力量复利滚雪球的魅力基于“第一性原理”的思路工作聊聊“晋升”到底该怎么做万能方法之如何使用MECE分析法高效解决问题
