夜雨聆风一句话介绍OpenClaw Skill 是 AI 编程助手的能力扩展包，像给 AI 装插件一样，让它在特定领域（处理 PDF、操作数据库等）变成专家级助手。
一、什么是 OpenClaw Skill？
OpenClaw Skill 是一种模块化能力扩展机制，每个 Skill 本质上是一个包含以下内容的目录：
SKILL.md：技能说明文件，告诉 AI 这个 Skill 能做什么、怎么做scripts/：可直接执行的脚本（Python / Node.js / Bash）references/：参考文档，AI 需要时按需加载assets/：模板文件、图片等静态资源
二、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-skillnpm install# 安装 Python 依赖（如有 requirements.txt）pip3 install -r requirements.txt方式三：手动创建（开发者）
# 使用官方初始化脚本（需先加载 skill-creator skill）python3 /path/to/skill-creator/scripts/init_skill.py my-"hljs-keyword">new-skill \ --path .openclaw/skills/第三步：启用 Skill
Skill 放置到 .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-keyword">for skill_dir "hljs-keyword">in"$SKILLS_DIR"/*/; do"hljs-keyword">if [ -d "$skill_dir/.git" ]; then skill_name=$(basename "$skill_dir") echo "📦 更新: $skill_name" cd "$skill_dir" git pull origin main 2>&1# 自动安装新增依赖 [ -f "package.json" ] && npm install --silent [ -f "requirements.txt" ] && pip3 install -r requirements.txt -q cd - > /dev/"hljs-keyword">null echo "✅ $skill_name 更新完成" fidoneecho "🎉 所有 Skill 更新完毕！"chmod +x update-all-skills.sh./update-all-skills.sh版本管理建议
# 升级前打标签备份cd .openclaw/skills/my-skill/git tag v1.0.0-backupgit 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_SECRET="hardcoded_secret_123"# ✅ 正确做法：使用环境变量"hljs-keyword">export MY_SKILL_API_KEY="your_key_here"# 或写入 .env 文件（确保加入 .gitignore）echo "MY_SKILL_API_KEY=your_key_here" >> .envecho ".env" >> .gitignore在脚本中读取：
// Node.js"hljs-keyword">const apiKey = process.env.MY_SKILL_API_KEY;"hljs-keyword">if (!apiKey) { console.error("❌ 请设置环境变量 MY_SKILL_API_KEY"); process.exit(1);}# Python"hljs-keyword">import osapi_key = os.environ.get("MY_SKILL_API_KEY")"hljs-keyword">if"hljs-keyword">not api_key: raise EnvironmentError("请设置环境变量 MY_SKILL_API_KEY")4.3 脚本权限配置
# 为脚本添加可执行权限chmod +x .openclaw/skills/my-skill/scripts/.shchmod +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：使用 launchdcat > ~/Library/LaunchAgents/com.myskill.plist << 'EOF'<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN""..."><plist version="1.0"><dict> <key>Label</key> <"hljs-keyword">string>com.myskill</"hljs-keyword">string> <key>ProgramArguments</key> <array> <"hljs-keyword">string>/usr/local/bin/node</"hljs-keyword">string> <"hljs-keyword">string>/path/to/.openclaw/skills/my-skill/scripts/server.js</"hljs-keyword">string> </array> <key>RunAtLoad</key> <true/></dict></plist>EOFlaunchctl load ~/Library/LaunchAgents/com.myskill.plist五、常见失败原因与快速排错
问题一：Skill 未被识别（加载失败）
现象：让 AI 使用某 Skill，AI 说"没有找到该 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 axiospip3 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_KEY="your_key"' >> ~/.zshrcsource ~/.zshrc问题五：Skill 间冲突
现象：加载多个 Skill 后，AI 混淆触发逻辑
解决方案：
# 检查是否有同名 Skillls .openclaw/skills/ | sort | uniq -d# 重命名冲突 Skillmv .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 && python3 --version# 使用 nvm 切换 Node.js 版本nvm install 20nvm use 20# 使用 pyenv 切换 Python 版本pyenv install 3.11pyenv 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-keyword">async"hljs-keyword">function main() {"hljs-keyword">try {"hljs-keyword">const result = "hljs-keyword">await doSomething(); console.log("✅ 执行成功:", result); } catch (err) { console.error("❌ 执行失败:", err.message); // 写入日志文件 fs.appendFileSync("skill-error.log",[${"hljs-keyword">new Date().toISOString()}] ${err.stack}\n ); process.exit(1); }}6.3 定期健康检查脚本
#!/bin/bash# health-check.sh - 每天运行一次SKILLS_DIR=".openclaw/skills"FAIL_COUNT=0"hljs-keyword">for skill_dir "hljs-keyword">in"$SKILLS_DIR"/*/; do skill_name=$(basename "$skill_dir")# 检查 SKILL.md 存在"hljs-keyword">if [ ! -f "$skill_dir/SKILL.md" ]; then echo "⚠️ $skill_name: 缺少 SKILL.md" FAIL_COUNT=$((FAIL_COUNT + 1)) fi# 检查依赖完整性"hljs-keyword">if [ -f "$skill_dir/package.json" ]; then"hljs-keyword">if [ ! -d "$skill_dir/node_modules" ]; then echo "⚠️ $skill_name: node_modules 缺失，请运行 npm install" FAIL_COUNT=$((FAIL_COUNT + 1)) fi fidone"hljs-keyword">if [ $FAIL_COUNT -eq 0 ]; then echo "✅ 所有 Skill 健康检查通过""hljs-keyword">else echo "❌ 发现 $FAIL_COUNT 个问题，请及时修复"fi七、官方推荐规范与避坑指南
✅ 最佳实践清单
✅ SKILL.md 描述精准、具体，触发关键词明确✅ 脚本支持 --help 参数，方便快速了解用法✅ 所有密钥通过环境变量传入，不硬编码✅ 提供 README.md，记录安装步骤和使用示例✅ 脚本有完整的错误处理和退出码✅ 使用语义化版本号（v1.2.3）管理 Skill 版本✅ 大型依赖文件加入 .gitignore（node_modules、__pycache__）✅ 定期运行健康检查脚本，提前发现问题❌ 常见坑点（一定要避开）
❌ SKILL.md 描述太泛，导致 AI 频繁误触发❌ 脚本路径写死（用绝对路径），换机器就失效❌ 忘记 chmod +x，脚本无法执行❌ 多个 Skill 的 name 字段重复，互相覆盖❌ 依赖版本不固定（package.json 用 ^），升级后行为改变❌ 临时测试文件未清理，污染 Skill 目录❌ 忘记处理 API 限流（rate limit），脚本崩溃没有重试逻辑目录命名规范
# ✅ 正确命名（kebab-"hljs-keyword">case）wechat-publisherpdf-processordata-query-tool# ❌ 错误命名WechatPublisher # 驼峰wechat_publisher # 下划线wechat publisher # 含空格八、快速参考卡片
# 安装新 Skillcp -r my-skill/ .openclaw/skills/# 验证结构ls .openclaw/skills/my-skill/SKILL.md# 更新 Skill（git 方式）cd .openclaw/skills/my-skill && git pull# 修复权限chmod +x .openclaw/skills/my-skill/scripts/*# 修复 Node.js 依赖cd .openclaw/skills/my-skill && 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做一个有深度的技术人
