1. 目录结构

skill主要存放在三个地方：1）捆绑类skill，通过npm安装，一般在npm的modules目录下，看你是全局还是局部安装；2）本地skill，存放在OpenClaw主目录下的skills文件夹，目录为"~/.openclaw/skills"；3）workspace skill，存放在"<workspace>/skill"目录下。

优先级是类别3最高，即workspace下的skill拥有最高优先级，其次是2，然后是1默认捆绑的skill。同名skill冲突时，OpenClaw按照这个优先级进行处理。看官方文档，说是还可以关联外部目录，通过"~/.openclaw/openclaw.json"的"skills.load.extraDirs"参数进行配置，这个优先级最低。

除了优先级，还有一点不同的是，"workspace"下的skill相当于私有的，仅对当前的agent的有效，而类别2，就是根目录下的skills是共享的，所有agent的都可以使用。

注意：“~/.openclaw” 对应的是linux的目录，"~"代表当前用户的根目录，对于windows平台，也是一致的，对应"C:\Users[用户名]"目录，后面不再解释。

1.1 skill文件布局

my-skill/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

SKILL.md是必须存在的，其他都是可选的，如果说SKILL.md的内容过长，最好的办法就是分割成多个文件，放到“references”目录下，在SKILL.md文件中引用，这样做的好处是让模型在读取的时候，消耗的token少些，模型会按照需求读取引用的文件。

2. SKILL.md

这个文件是必须的，描述技能的功能和触发条件，需要采用yaml和markdown两种格式编写。
开始部分描述skill的主要功能，“—”开始，“—”结束，描述语言为yaml格式，有如下字段：

2.1 metadata配置

3. 更新

3.1 更新SKILL.md

name修改的更规范些，按照官方标注，修改为小写字母和“-”的组合，增加metadata字段，导入环境变量信息，其他非必要字段我都删除了，如下：

---
name: smart-plug-control
description: Smart plug control skill for turning plug on/off. Triggers on phrases like "turn off plug", "turn on plug", "打开插座", "关闭插座", or similar plug control commands.
metadata:
  {
    "openclaw":
      {
        "requires": { "env": ["SMART_PLUG_TOKEN", "SMART_PLUG_IP"] },
        "primaryEnv": "SMART_PLUG_TOKEN"
      }
  }
---

配置好以后，重启openclaw

openclaw gateway restart

切换到skill目录，发现已经能识别到环境变量没有配置，并且状态也被切换到“blocked”，这样我们就能把参数都放在环境变量中，避免泄露了。

”Save key“执行后，会将参数以明文的方式保存到”openclaw.json“文件中。如果不需要"Save
key"按钮，把"metadata"中"primaryEnv"去掉即可。

3.2 修改执行脚本

修改脚本，从环境变量获取这些参数，python代码进行一些微量修改：

def get_smart_plug_ip():
    return os.environ.get("SMART_PLUG_IP")

def get_smart_plug_token():
    return os.environ.get("SMART_PLUG_TOKEN")

# Device configuration
PLUG_IP = get_smart_plug_ip()
PLUG_TOKEN = get_smart_plug_token()

4. 执行测试

4.1 测试1

添加环境变量”SMART_PLUG_IP“和”SMART_PLUG_TOKEN“。

配置环境变量后，再次重启openclaw，效果如下，skill正常了！

执行控制插座指令，开关都正常（参数都配置在环境变量中）。

4.2 测试2

删除环境变量”SMART_PLUG_TOKEN“，重启openclaw，skill变为”blocked“状态。

通过”save key“配置token，会关联到”SMART_PLUG_TOKEN“，这是由SKILL.md中的”primaryEnv“实现的。比如这里我们配置为”123“，配置后，skill会变为”eligible“有效状态。

但是要提醒的是，这样是以明文配置在"~/openclaw.json"文件中。

TODO：官方文档说是可以用加密方式配置，暂时还不知道怎么配置，后续研究。