OpenClaw Skills 实战：Gemini CLI 无头模式技能（SKILL.md）解析与 OpenClaw 技能加载机制

OpenClaw Skills 实战Gemini CLI 无头模式技能SKILL.md解析与 OpenClaw 技能加载机制【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文基于 OpenClaw 仓库中内置的skills/gemini/SKILL.md系统讲解如何用 Gemini CLI 的无头headless一次性模式完成提问、摘要、JSON 生成与内容路由并深入结合 OpenClaw 的技能加载源码说明requires.bins门控、install安装规格、bundled 技能根目录发现等机制是如何把一个 SKILL.md 变成 Agent 可用的能力的。读完本文你既能直接复制命令使用 Gemini CLI也能理解 OpenClaw 是如何发现、校验并暴露这个技能的。技能定位Gemini CLI 无头一次性提示skills/gemini/SKILL.md是一份bundled skill随 OpenClaw 安装包一起发布的技能其核心目标是让 Agent 以无头一次性模式headless one-shot mode调用 Gemini覆盖三类典型任务——一次性问答one-shot prompts、内容摘要summaries、结构化内容生成generation以及技能skills、钩子hooks、MCP 服务的管理或将任务路由到 Gemma 系列模型。技能的第一条关键约定是位置参数文本会进入交互模式无头执行必须使用-p/--prompt。也就是说直接gemini 你好会启动一个交互式会话而脚本化、Agent 化的用法必须显式传入-p确保进程执行完即退出适合被 OpenClaw 的exec工具调用。快速上手命令原文档给出的 Quick start 全部命令如下均可直接复制运行# 基础一次性提问 gemini -p Answer this question... # 指定模型 gemini -m model -p Prompt... # 要求返回 JSON便于程序解析 gemini -p Return JSON --output-format json # stdin 内容会附加到 -p 提示之后 cat notes.md | gemini -p Summarize几个使用要点-m model用于在默认模型之外显式选择模型这也是原文档描述中 Gemma routing把请求路由到 Gemma 等模型的落点--output-format json使输出成为可解析的 JSONAgent 侧可以稳定提取字段而不是解析自由文本stdin 管道是摘要类任务的关键入口cat notes.md | gemini -p Summarize中管道内容会被追加到-p指定的提示之后因此提示词只写任务指令、把待处理内容从标准输入喂入即可避免长文本拼进命令行参数。扩展管理命令族Gemini CLI 自带一组子命令用于扩展能力技能中要求 Agent 熟记这一命令族gemini --list-extensions # 列出已安装的扩展 gemini extensions command # 管理扩展 gemini skills command # 管理 Gemini 侧的技能 gemini hooks command # 管理钩子 gemini mcp command # 管理 MCP 服务这里要区分两个层面的skillGemini CLI 自己的gemini skills是它内置的技能机制而本文档所在的skills/gemini/是OpenClaw 的技能用于教会 OpenClaw 的 Agent 如何驱动 Gemini CLI 这个外部工具。两者名称相同但职责不同——OpenClaw 技能是操作手册Gemini 技能是CLI 自身能力。前置条件依赖门控与安装规格SKILL.md的 YAML frontmatter 不只是描述文字它被 OpenClaw 的技能加载器解析为机器可执行的元数据--- name: gemini description: Gemini CLI one-shot prompts, summaries, generation, skills, hooks, MCP, or Gemma routing. homepage: https://ai.google.dev/ metadata: openclaw: emoji: ✨ requires: { bins: [gemini] } install: - id: brew kind: brew formula: gemini-cli bins: [gemini] label: Install Gemini CLI (brew) ---requires.bins二进制存在性门控requires: { bins: [gemini] }声明了这个技能的前置条件系统 PATH 中必须存在gemini可执行文件。从源码结构看技能在加载时会根据环境、配置和二进制存在性进行过滤见 Skills 总览 中 filters them at load time based on environment, config, and binary presence 的说明。这意味着未安装 Gemini CLI 的机器上该技能不会进入 Agent 的可用技能列表Agent 也就不会去尝试调用不存在的命令安装gemini之后技能自动变为可用无需改任何 OpenClaw 配置。install 规格可执行的安装声明metadata.openclaw.install数组中声明了一个kind: brew的安装项formula: gemini-cli。加载器对安装规格有严格的白名单式校验——从 frontmatter.ts 的parseInstallSpec可以看到支持的kind限定为brew、node、go、uv、download五种parseInstallSpecbrew 公式必须通过normalizeSafeBrewFormula的安全模式校验不允许以-开头、不允许\\和..公式gemini-cli通过BREW_FORMULA_PATTERN正则L34kind brew时若没有formula则整个规格被丢弃L184-L186所以formula: gemini-cli是这个安装项有效的关键bins字段则用于安装完成后的验证安装成功的判据是gemini出现在 PATH 中与requires.bins形成闭环。这一机制让缺依赖 → 声明安装方式 → 安装 → 门控通过 → 技能激活成为一条数据驱动的链路技能作者只需要在 frontmatter 里声明而不需要编写安装脚本。认证与安全注意事项原文档 Notes 部分给出两条必须遵守的运行时约定认证如果需要登录先交互式运行一次gemini并按登录流程完成授权之后再使用-p无头模式。因为 OAuth 等登录流程需要浏览器交互无法在无头进程中完成安全避免使用--yolo参数。该参数会放开 Gemini CLI 的自动执行限制在 Agent 自动化调用场景下等于给模型直接执行任意操作的权限OpenClaw 的技能文档明确建议回避。OpenClaw 如何发现并加载这个技能技能文件放在仓库根目录的 skills/gemini/SKILL.md与1password/、himalaya/、summarize/等数十个 bundled 技能并列。它被加载的路径由源码保证bundled 技能根目录解析bundled-dir.ts 的resolveBundledSkillsDir按序尝试环境变量OPENCLAW_BUNDLED_SKILLS_DIR覆盖 →bun --compile单文件可执行文件同级的skills/目录 → 以模块位置向上回溯最多 6 层寻找形如技能的skills/目录looksLikeSkillsDir要求目录内存在.md文件或包含SKILL.md的子目录见 L7-L28。仓库内skills/目录每个子目录都含SKILL.md满足该判定。加载优先级bundled 技能处于优先级第 5 档低于工作区技能workspace/skills、项目.agents/skills、个人~/.agents/skills和托管技能目录高于skills.load.extraDirs与插件技能见 docs/tools/skills.md 的加载顺序表。因此如果你在工作区放一个同名skills/gemini/SKILL.md会覆盖内置版本——这是定制该技能的官方方式例如补充你账号可用的模型列表或团队约定。frontmatter 解析frontmatter.ts 的parseSkillFrontmatter先解析 YAML 块并抛错于格式非法L25-L32随后resolveSkillManifestMetadata提取emoji、homepage、requires、install、os、always等字段L203-L223resolveSkillInvocationPolicy则解析user-invocable默认 true与disable-model-invocation默认 false两个调用策略开关决定技能是否可被斜杠命令直接调用、是否可被模型自主调用。本技能未设置这两项即默认同时支持用户/gemini斜杠调用与模型自主调用。加载验证写入或更新后运行openclaw skills list即可确认gemini出现在列表中前提是gemini二进制已安装否则会被门控过滤。OpenClaw 默认监听技能根目录下的SKILL.md变更若你修改了 bundled 版本或想立即生效可/new开新会话或openclaw gateway restart。一个典型的 Agent 使用场景综合以上机制OpenClaw 中这个技能的典型工作流是# Agent 收到总结这份周报并输出 JSON的请求后 # 依 SKILL.md 指令拼装无头命令 cat weekly.md | gemini -m gemini-2.5-pro \ -p Summarize into sections and action items. Return JSON. \ --output-format json门控保证只有装好gemini的机器才暴露此技能-p保证进程一次性退出不挂住 Agent 的执行工具stdin 注入长文档命令行保持短小--output-format json让下游解析可靠登录问题引导用户先交互式gemini一次而非在自动化流程里反复失败。小结与参考路径内容位置本技能定义frontmatter 操作指令skills/gemini/SKILL.md技能加载总览优先级、门控、节点技能docs/tools/skills.md自定义技能编写流程docs/tools/creating-skills.mdfrontmatter / 安装规格解析实现src/skills/loading/frontmatter.tsbundled 技能根目录发现实现src/skills/loading/bundled-dir.tsskills/gemini/SKILL.md体量虽小却展示了 OpenClaw 技能体系的完整闭环YAML frontmatter 声明依赖与安装方式markdown 正文提供 Agent 可直接执行的命令知识加载器负责发现、门控与优先级仲裁。理解了这一闭环你就能照着同样的模式为任意 CLI 工具编写自己的技能。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考