编写你的第一个nexu技能：SKILL.md规范、技能目录机制与热加载原理

编写你的第一个nexu技能SKILL.md规范、技能目录机制与热加载原理【免费下载链接】nexuThe simplest desktop client for OpenClaw — bridge your Agent to WeChat, Feishu, Slack Discord in one click. Works with Claude Code, Codex any LLM. BYOK, Oauth, local-first, chat from your phone 24/7.项目地址: https://gitcode.com/gh_mirrors/ne/nexunexu 是 OpenClaw 最简洁的桌面客户端把你的 Agent 一键桥接到微信、飞书、Slack 与 Discord。而nexu 技能Skill是它最核心的扩展机制——你只需要写一个SKILL.md文件就能给 Agent 加上联网搜索、文档生成、多维表格操作等全新能力且支持热加载保存即生效、无需重启。本文将带你完整走通从 SKILL.md 规范、技能目录机制到热加载原理。1. 什么是 nexu 技能Agent 的能力扩展卡技能本质上是一个文件夹 一份说明书文件夹里放一份SKILL.md里面告诉 Agent「这是什么能力、什么时候用、具体怎么干」。Agent 会自动扫描目录、读懂说明书并在对话中按需调用——你不需要写一行代码。在左侧导航栏点击Skills即可进入技能中心浏览 Explore可安装的公共技能与 Yours已安装技能官方技能仓库位于 nexu-skills/skills/共 8 个开箱即用的飞书技能多维表格、日历、文档读写等完整清单见 nexu-skills/skills.json。每个技能的目录结构都非常轻feishu-im-read/ └── SKILL.md # 唯一必需文件frontmatter 元信息 使用指南正文复杂技能可以附带references/子目录存放参考文档例如 feishu-bitable 就拆出了字段配置、记录值格式等参考文件由 SKILL.md 正文按指引引用。2. SKILL.md 规范一次读懂 frontmatter 六大字段SKILL.md 由两部分组成YAML frontmatter元信息Markdown 正文执行指南。以官方技能 feishu-im-read/SKILL.md 为例--- name: feishu-im-read description: | 飞书 IM 消息读取工具使用指南…… (1) 需要获取群聊或单聊的历史消息 (2) 用户提到聊天记录、消息、群里说了什么 tag: office-collab icon: MessageSquare source: official prompt: Help me read Feishu chat messages examples: - 帮我查看群里今天的聊天记录 requires: plugins: - larksuite/openclaw-lark ---各字段的作用一句话讲清字段作用新手要点name技能唯一标识slug必须与目录名一致用短横线小写英文description技能路由的核心写清「什么情况下触发」Agent 靠它判断是否调用你的技能tag分类标签如office-collab、file-knowledge影响市场分类展示icon卡片图标lucide 图标名如MessageSquareprompt默认唤起提示词用户点开技能时预填的指令examples触发示例短语3 条左右、口语化直接决定技能「好不好被选中」requires.plugins依赖的 MCP 插件声明后系统会检查依赖是否就绪正文则是 Agent 执行时的操作手册建议按官方技能的套路组织参考 feishu-im-read/SKILL.md执行前必读权限边界、参数互斥等硬性约束快速索引表用户意图 → 工具 → 必填参数让 Agent 少走弯路核心约束分页、时间范围、错误排查等「Schema 未透露的知识」场景示例常见场景给出可直接套用的参数 经验法则descriptionexamples决定技能能不能被触发正文质量决定技能执行得好不好。3. 编写第一个自定义技能最快配置方法第一步建目录、写 SKILL.md。在工作区的agents/botId/skills/下新建目录例如my-first-skill/SKILL.md按第 2 节规范填写即可。最小可用示例只有 frontmatter 加一小段正文。第二步放到正确的技能目录。nexu 支持三个可写层级优先级从高到低同名时高优先级覆盖低优先级层级路径可见范围代理工作区state/agents/botId/skills/仅该代理用户级~/.agents/skills/所有代理运行时级SkillHub 安装state/skills/所有代理系统内置OpenClaw 自带所有代理完整说明见架构文档 docs/plans/2026-03-28-skill-management-architecture.md。第三步从市场安装现成技能更省事。在 Explore 标签搜索关键词点击卡片上的Install按钮安装完成后在Yours标签查看已安装列表可随时用开关启用/禁用或点Uninstall卸载第四步在对话中直接用。技能生效后直接在微信、飞书等渠道对话中描述需求Agent 会自动选择合适的技能例如「帮我查看群里今天的聊天记录」4. 技能目录机制磁盘即真相nexu 对技能目录的识别规则非常直观目录扫描时只有包含SKILL.md的子目录才算一个技能目录名即技能 slug。核心扫描逻辑在 skill-dir-watcher.ts 的scanDirSlugsreaddirSync(skillsDir) → 过滤出存在 SKILL.md 的条目 → 得到技能 slug 列表在此基础上控制器维护一份技能账本skill-ledger.json记录每个技能的安装来源managed / custom / user / workspace、时间与启用状态。账本与磁盘之间持续双向对账磁盘上有、账本没有 → 补记为「已安装」覆盖你手动放入目录的技能账本有、磁盘没有 → 标记为「已卸载」保留安装历史对账入口是 SkillDirWatcher.syncNow()应用启动时执行一次保证升级、重装后状态不丢失。5. 热加载原理为什么保存即生效这是 nexu 技能机制最优雅的部分——三层监听 防抖 配置重写全程零重启文件监听SkillDirWatcher.start() 对共享技能目录、用户目录、各代理工作区目录分别建立递归fs.watch捕获任意层级的新增/删除。防抖合并事件先经 scheduleSync() 做500ms 防抖避免编辑器批量写文件时反复触发。对账 配置重写防抖结束后执行syncNow()更新账本onChange回调触发 config 编译器重写 OpenClaw 配置技能 allowlistOpenClaw 侧同样开启了watch: true的混合热重载约 2 秒内新技能即可被 Agent 识别。一句话总结数据流你放文件 → watch 事件 → 防抖 → 磁盘↔账本对账 → 配置重写 → Agent 加载新技能。所以答案是安装、导入、手动放入目录的 nexu 技能都无需重启 Agent。常见问题速查Q改了 SKILL.md 不生效确认文件里是完整的 frontmatter---闭合且目录名与name字段一致等 2 秒左右或观察 Yours 列表是否出现该技能。Q同名技能冲突怎么办工作区 用户级 运行时级 系统内置高优先级覆盖低优先级删掉高优先级副本即可回退。Q官方新手教程在哪见 docs/zh/guide/skills.md 技能安装指南以及技能服务源码目录 apps/controller/src/services/skillhub/。掌握 SKILL.md 规范后编写你的第一个 nexu 技能只需 10 分钟建目录、写 frontmatter、丢进技能目录——剩下的交给热加载。【免费下载链接】nexuThe simplest desktop client for OpenClaw — bridge your Agent to WeChat, Feishu, Slack Discord in one click. Works with Claude Code, Codex any LLM. BYOK, Oauth, local-first, chat from your phone 24/7.项目地址: https://gitcode.com/gh_mirrors/ne/nexu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考