1. 项目概述为Gemini CLI注入“技能”的扩展如果你和我一样日常重度依赖命令行工具并且对Google的Gemini CLI命令行界面的潜力感到兴奋但又觉得它和Claude Code那种能调用特定工具技能的“智能体”体验相比还差点意思那么这个项目可能就是你要找的答案。gemini-cli-skillz是一个官方扩展它巧妙地将一个名为skillz的 MCP模型上下文协议服务器打包进来让Gemini CLI也能理解和调用那些为Claude设计的“Agent Skills”。简单来说它打破了工具壁垒。以前那些由Anthropic社区或你自己编写的、格式为文件夹加SKILL.md文件的技能只能在Claude生态里运行。现在通过这个扩展你可以把它们直接搬到Gemini CLI里使用。这意味着当你在终端里对Gemini说“帮我把这个PDF里的表格数据提取成CSV”时它不再只是给你一段理论上的Python代码而是能自动调用对应的PDF处理技能直接帮你完成这个任务。这本质上是在扩展CLI工具的能力边界让它从一个对话式代码助手进化成一个能真正“动手做事”的自动化伙伴。2. 核心原理与架构拆解要理解这个扩展如何工作我们需要拆解两个核心概念MCPModel Context Protocol和 Skill的格式。这能帮你明白为什么它能“桥接”两个不同AI公司的产品。2.1 MCP模型与工具之间的“通用插座”你可以把MCP想象成家电的“通用电源插座”标准。不同的电器AI模型如Gemini、Claude和不同的工具技能如文件操作、网页搜索如果都遵循这个标准那么它们就可以通过一个标准的“插头”MCP服务器连接在一起。skillz项目就是一个实现了MCP协议的服务器它的专职工作就是读取和管理那些按照特定格式编写的技能Skill。gemini-cli-skillz扩展的作用就是在Gemini CLI这个“电器”上安装了一个兼容skillz这个“插头”的插座。安装后Gemini CLI就具备了通过MCP协议与skillz服务器通信的能力从而获取到服务器管理的所有技能列表和功能描述。2.2 Skill格式技能的统一“说明书”技能本身并不是可执行程序而是一份结构化的“说明书”。每个技能都是一个独立的文件夹其核心是一个SKILL.md文件。这个文件采用“YAML Frontmatter Markdown描述”的格式。YAML Frontmatter部分是机器可读的元数据定义了技能的基本信息、输入参数和工具调用规范。例如一个PDF处理技能的Frontmatter可能会这样定义name: pdf_text_extractor description: Extract and analyze text from PDF files. inputs: - name: pdf_file description: The path to the PDF file to process. type: string required: trueMarkdown描述部分则是给人看的详细说明了这个技能能做什么、怎么用有时还会包含一些示例。skillz服务器会解析这些SKILL.md文件将其中定义的“工具”通过MCP协议暴露给连接的AI模型。当你在Gemini CLI中输入一个请求时Gemini模型会先分析你的意图然后查询通过MCP连接可用的工具列表。如果发现某个技能比如PDF提取的描述与你的请求匹配它就会自动生成符合MCP规范的调用指令通过skillz服务器执行该技能背后的实际逻辑可能是调用一个Python脚本或一个API。注意技能本身不包含在扩展里。扩展只提供了运行技能的“引擎”skillz服务器和与Gemini CLI的连接器。技能需要你单独准备并放入指定的目录。2.3 工作流程全景图安装扩展通过gemini extensions install命令将桥接器装入Gemini CLI。启动连接重启Gemini CLI后它会自动启动uvx skillzlatest命令运行最新的skillzMCP服务器并告诉服务器从哪个目录默认是~/.skillz加载技能。技能加载skillz服务器扫描技能目录解析所有有效的SKILL.md文件将技能列表注册到自身。会话交互你在CLI中输入请求。意图匹配Gemini模型分析你的请求并向MCP服务器查询可用的工具寻找匹配项。自动调用若找到匹配技能Gemini生成调用命令服务器执行该技能对应的实际代码并将结果返回给Gemini。结果呈现Gemini将服务器返回的结果整理后输出给你。这套流程的关键在于“自动”。你不需要显式地输入“请使用某某技能”模型会根据上下文自动判断并调用体验非常流畅。3. 从零开始的完整安装与配置指南让我们一步步搭建这个环境。我会假设你从一个全新的系统开始涵盖所有可能遇到的细节。3.1 前置条件检查与安装首先确保你的系统已经具备以下基础Gemini CLI必须是已安装且较新的版本。你可以通过gemini --version检查。如果未安装需要先前往Google AI Studio或相关开发者页面获取安装方法。uv 包管理器这是安装Python工具的新兴利器比传统的pip更快捷、更隔离。skillz服务器通过uvx命令运行而uvx是uv工具的一部分。安装uv如果尚未安装在终端中执行以下命令。这是一条通用安装脚本适用于大多数Unix-like系统Linux, macOS。curl -LsSf https://astral.sh/uv/install.sh | sh安装完成后关闭并重新打开你的终端或者执行source ~/.bashrc或source ~/.zshrc来让uv和uvx命令生效。验证安装uvx --help应该能显示帮助信息。3.2 安装 gemini-cli-skillz 扩展这是核心步骤命令非常简单gemini extensions install https://github.com/intellectronica/gemini-cli-skillz执行后Gemini CLI会从GitHub仓库获取扩展并安装。这里有一个非常重要的坑点需要你注意实操心得网络问题与备用方案由于从GitHub Releases下载资产时可能遇到网络波动或CDN问题你可能会看到类似HTTP 415 Unsupported Media Type的错误。别担心这并非扩展本身有问题。安装脚本贴心地提供了备用方案。当错误出现时安装程序会交互式地询问Would you like to try installing via git clone instead? [y/N]。这时务必输入大写的Y或小写的y并按回车。这个备用方案会通过git clone方式直接克隆源码仓库来安装扩展通常能绕过下载问题。我实测在几次网络不畅的环境下通过这个方式都成功安装了。3.3 技能目录的初始化策略安装扩展后你需要一个存放技能的地方。扩展默认会寻找~/.skillz目录。这里你有两个选择第二个选择对于双修Claude和Gemini的用户尤其高效。方案A创建全新的技能目录默认如果你之前没用过Claude Code的技能或者想为Gemini单独管理一套技能执行mkdir -p ~/.skillz-p参数确保如果~目录下的.skillz父目录不存在也会一并创建。方案B符号链接共享Claude技能目录推荐给双修用户如果你已经在使用Claude Code并且技能都放在默认的~/.claude/skills目录下那么复制一份既占空间又难同步。最优解是创建一个符号链接可以理解为快捷方式。ln -s ~/.claude/skills ~/.skillz执行这条命令后~/.skillz将不再是真实文件夹而是一个指向~/.claude/skills的链接。你对其中任何一个目录的操作增删改技能都会实时同步到另一个。这实现了技能的“一处维护两处使用”极大地简化了管理。验证链接是否创建成功ls -la ~ | grep .skillz你应该看到类似这样的输出行首有一个l代表link并且箭头指向.claude/skillslrwxr-xr-x 1 user staff 18B Apr 10 10:00 .skillz - .claude/skills3.4 安装示例技能以Anthropic官方PDF技能为例现在你的技能目录准备好了但里面是空的。让我们从Anthropic的官方技能库中安装一个实用的技能作为例子。这里我们安装pdf技能它包含了一系列PDF处理功能。逐行解析以下命令块# 1. 进入你的技能目录 cd ~/.skillz # 2. 使用 git sparse-checkout 技巧克隆特定子目录避免下载整个庞大的技能仓库 git clone --depth 1 --filterblob:none --sparse \ https://github.com/anthropics/skills.git temp # 3. 进入临时克隆的仓库 cd temp # 4. 设置“稀疏检出”只下载 document-skills/pdf 这个路径下的内容 git sparse-checkout set document-skills/pdf # 5. 将下载好的pdf技能文件夹移动到上一级目录即你的 ~/.skillz mv document-skills/pdf ../ # 6. 返回技能目录并删除临时的克隆仓库 cd .. rm -rf temp命令参数解读与避坑指南--depth 1只克隆最近一次提交的历史大大减少下载数据量。--filterblob:none在克隆过程中先不下载文件内容blob只下载目录结构结合sparse-checkout使用。--sparse初始化一个稀疏检出仓库允许你只检出部分文件。git sparse-checkout set ...这是关键它告诉git你只关心document-skills/pdf这个子目录下的文件。执行完毕后检查你的技能目录ls -la ~/.skillz/pdf/你应该能看到SKILL.md文件以及其他相关的Python脚本等资源文件。3.5 重启Gemini CLI并验证所有配置和技能就绪后必须重启Gemini CLI以加载新的扩展和技能。如果你是在终端交互式会话中运行gemini直接按CtrlD退出当前会话。重新输入gemini启动一个新的会话。启动后你可以使用内置命令验证MCP服务器和技能是否加载成功/mcp list这个命令会列出所有已连接的MCP服务器。你应该能看到一个名为skillz的服务器条目状态为已连接。更进一步的验证是你可以直接开始使用。将一份PDF文件例如invoice.pdf放在某个已知路径然后在Gemini CLI中尝试 请总结一下 /Users/yourname/invoice.pdf 这个PDF文件的内容。如果配置正确Gemini会识别出这个请求与PDF技能匹配并自动调用它来处理文件最终将总结结果返回给你。首次调用时可能会因为要安装技能所需的Python依赖而稍有延迟。4. 高级配置自定义技能目录与路径问题详解默认的~/.skillz目录可能不适合所有人。也许你想把技能放在Dropbox同步文件夹、另一个硬盘分区或者一个团队共享的目录中。这就需要自定义配置。4.1 定位扩展配置文件扩展的配置文件位于一个固定的路径下~/.gemini/extensions/skillz/gemini-extension.json这个文件在安装扩展时自动生成。你需要用文本编辑器如nano,vim, 或VSCode来编辑它。4.2 编辑配置文件的正确姿势用你熟悉的编辑器打开文件。它的初始结构可能类似这样{ mcpServers: { skillz: { command: uvx, args: [ skillzlatest ] } } }为了指定自定义技能目录你需要向args数组中添加两个参数目录路径和一个可选的日志标志。修改后的配置示例{ mcpServers: { skillz: { command: uvx, args: [ skillzlatest, /Volumes/ExternalDrive/MyAISkills, --verbose ] } } }关键参数解析skillzlatest固定参数告诉uvx运行最新版的skillz服务器。/Volumes/ExternalDrive/MyAISkills这是你必须修改的部分替换成你的绝对路径。--verbose可选参数。加上它skillz服务器会输出更详细的日志有助于调试技能加载失败的问题。4.3 绝对路径与环境变量必须掌握的细节这是配置过程中最容易出错的地方请务必仔细阅读。绝对路径是必须的MCP服务器在启动时是由Gemini CLI直接调用uvx执行的它不会经过你的Shell因此Shell的路径扩展功能如~代表家目录是无效的。你必须提供完整的绝对路径。错误示例~/my-skills,$HOME/my-skills正确示例macOS/Linux:/Users/alice/my-skills,/home/bob/sync/ai-skillsWindows (假设在WSL或配置正确环境下):C:/Users/Alice/Documents/skills如何获取一个目录的绝对路径在终端中进入你的目标技能目录然后使用pwdPrint Working Directory命令cd /your/custom/skills/folder pwd终端会输出该目录的绝对路径直接复制这个路径填入配置文件即可。关于环境变量的有限使用虽然$HOME在配置文件中通常不展开但有一种情况可能可行如果你的Shell在启动Gemini CLI时已经将环境变量导出并且Gemini CLI的启动方式能继承这个环境变量。然而这并不可靠。最稳妥的方法仍然是使用绝对路径。一个取巧但稳定的方法适用于Unix-like系统你可以在配置文件中使用$(echo ~)/custom-skills这种命令替换吗答案是不行因为JSON配置文件中不能执行Shell命令。但是你可以通过一个间接的方式写一个简单的包装脚本。创建一个脚本文件例如~/start_skillz.sh#!/bin/bash uvx skillzlatest $HOME/custom-skills --verbose赋予脚本执行权限chmod x ~/start_skillz.sh修改配置文件将command和args替换为执行这个脚本{ mcpServers: { skillz: { command: /bin/bash, args: [ /Users/yourusername/start_skillz.sh ] } } }这样脚本会在你的Shell环境中执行$HOME就能正确展开了。不过对于大多数用户直接使用绝对路径更简单。4.4 应用配置与故障排查保存gemini-extension.json文件后同样需要重启Gemini CLI以使新配置生效。如果重启后技能没有加载请按以下步骤排查检查路径是否存在在终端中手动ls一下你配置的绝对路径确认目录可访问。ls -la “/你/配置的/绝对路径”检查配置文件语法JSON格式非常严格多一个逗号或少一个引号都会导致解析失败。可以使用在线JSON校验工具或python -m json.tool your_file.json来验证。查看详细日志确保配置中包含了--verbose参数然后在Gemini CLI中观察启动时的输出或者尝试触发一个技能看是否有更详细的错误信息打印出来。验证MCP连接在Gemini CLI中使用/mcp list命令确认skillz服务器是否在列表中以及其状态。5. 技能的使用模式、创作与管理进阶掌握了安装和配置我们来深入看看技能在实际中如何被调用以及如何管理和创作你自己的技能。5.1 技能调用的两种模式技能调用主要是隐式、自动的但也存在一些交互细节。1. 全自动隐式调用主要模式这是设计的核心。你只需用自然语言描述任务。Gemini模型在理解你的请求后会自行查询可用的MCP工具即技能如果某个技能的描述SKILL.md中的description和inputs与任务高度匹配模型就会自动规划并调用它。示例“将 /tmp/report.pdf 中的第3页转换成PNG图片。”幕后Gemini发现pdf技能中有一个工具描述为“Convert a page of a PDF to an image”输入需要pdf_path和page_number。于是它自动调用该工具传入对应参数。2. 手动查询与引导如果你不确定有哪些技能可用或者想明确指定可以尝试更直接的询问“你现在可以调用哪些工具来处理文件”“有没有能帮我读写数据库的技能”Gemini会列出skillz服务器提供的工具列表。你也可以在请求中稍加引导“使用PDF技能提取这个文件中的所有文本./contract.pdf”5.2 技能目录的管理与更新技能目录本质上就是一个普通的文件夹。你可以用任何文件管理方式来操作它。添加新技能从社区如Anthropics的skills仓库、其他开源仓库下载技能文件夹直接复制到你的技能目录如~/.skillz/下即可。更新已有技能进入具体的技能文件夹如~/.skillz/pdf/如果该技能是通过git clone安装的你可以使用git pull来更新。如果是直接复制文件则需要手动下载新版覆盖。禁用技能不想用某个技能最简单的方法不是删除而是重命名其文件夹或其中的SKILL.md文件。例如将pdf文件夹改名为pdf_disabledskillz服务器在扫描时就会忽略它。这便于你随时恢复。技能冲突如果两个不同技能提供了同名工具后加载的可能会覆盖先加载的。管理时应注意技能来源避免冲突。5.3 动手编写你的第一个自定义技能社区技能虽好但自定义技能才能最大化发挥其价值。创建一个技能比想象中简单。目标创建一个名为file_info的技能它提供一个工具能返回指定文件的大小和最后修改时间。步骤创建技能文件夹mkdir -p ~/.skillz/file_info cd ~/.skillz/file_info创建SKILL.md文件这是技能的核心。--- name: file_info description: A skill to get basic information (size and modification time) of a file. inputs: - name: file_path description: The absolute path to the file. type: string required: true --- # File Information Skill This skill provides a tool to retrieve basic metadata of a file on the local filesystem. ## Tool: get_file_info Returns the size (in bytes) and the last modification time of the specified file. ### Example Invocation by the AI: The AI model will call this tool when the user asks about file details.YAML部分解析name: 技能标识。description: 技能整体描述。inputs: 定义工具所需的输入参数。这里定义了一个名为file_path的必填字符串参数。创建技能执行脚本skillz默认会寻找与技能同名的Python模块或tool.py。我们创建一个tool.py。# ~/.skillz/file_info/tool.py import os import json import time from typing import Any, Dict def get_file_info(file_path: str) - Dict[str, Any]: Retrieves size and modification time of a file. Args: file_path: Absolute path to the file. Returns: A dictionary containing file stats or an error message. try: stat_info os.stat(file_path) return { “file_path”: file_path, “size_bytes”: stat_info.st_size, “size_human”: f“{stat_info.st_size / 1024:.2f} KB”, “modified_time”: time.ctime(stat_info.st_mtime), “modified_timestamp”: stat_info.st_mtime } except FileNotFoundError: return {“error”: f“File not found: {file_path}”} except Exception as e: return {“error”: f“An error occurred: {str(e)}”} # skillz 服务器会寻找并注册这个函数 __all__ [“get_file_info”]这个Python文件定义了一个函数get_file_info它接收file_path参数与SKILL.md中定义的inputs对应并返回一个包含文件信息的字典。重启Gemini CLI并测试 重启后在Gemini CLI中尝试 告诉我 /etc/hosts 这个文件有多大什么时候修改的Gemini应该会自动调用你刚创建的file_info技能并返回类似这样的信息根据文件信息工具查询/etc/hosts 文件大小为 1234 字节约 1.21 KB最后修改时间为 Wed Apr 10 09:30:00 2024。注意事项技能开发的边界自定义技能赋予了Gemini CLI访问本地系统的能力因此安全第一。在编写技能时务必做好输入验证防止路径遍历攻击如../../../etc/passwd。限制危险操作避免提供直接执行任意Shell命令、删除关键文件等高风险功能的技能。明确权限技能以启动Gemini CLI的用户权限运行。确保你了解其潜在影响。 最佳实践是从简单的、只读的、处理用户明确指定路径文件的技能开始。6. 深度故障排查与性能优化即使按照指南操作你也可能会遇到一些问题。这里汇总了常见问题的根源和解决方案。6.1 技能加载失败从表象到根源问题现象重启Gemini CLI后使用/mcp list看不到skillz服务器或者服务器状态异常技能无法被调用。排查清单检查uvx是否可用which uvx如果命令未找到说明uv安装或环境变量配置有问题。重新执行安装uv的步骤并确保重启终端。手动运行skillz服务器 在终端中直接运行以下命令可以绕过Gemini CLI直接测试skillz服务器和技能目录。uvx skillzlatest ~/.skillz --verbose如果运行成功你会看到服务器启动日志并停留在等待连接的状态。这说明skillz和技能目录本身没问题问题可能出在Gemini扩展的配置上。如果运行失败会打印具体的错误信息。常见错误技能目录不存在按错误提示创建目录。SKILL.md 格式错误检查技能文件夹内的SKILL.md其YAML frontmatter部分必须格式正确。可以使用在线YAML校验器检查。特别注意缩进和冒号后的空格。Python依赖缺失某些技能如PDF处理需要pypdf2或pdfplumber有额外的Python依赖。skillz通常会在首次调用时尝试安装但网络问题可能导致失败。查看错误日志尝试手动在技能目录下安装pip install pypdf2。检查Gemini扩展配置文件 再次确认~/.gemini/extensions/skillz/gemini-extension.json文件JSON格式正确。路径是绝对路径。文件路径存在且有读取权限。查看Gemini CLI日志 以调试模式启动Gemini CLI有时能提供更多信息。查阅Gemini CLI的官方文档看是否有启用详细日志的启动参数。6.2 技能被识别但调用失败问题现象Gemini表示要调用某个技能但随后报错例如“Tool call failed”或“Skill execution error”。排查思路参数传递错误这是最常见的原因。在SKILL.md中定义的inputs名称必须与后端Python函数接收的参数名完全一致包括大小写。检查你的请求是否能让模型正确提取出技能所需的所有参数。技能脚本自身错误直接运行技能里的Python脚本进行测试。例如进入技能目录用Python直接调用相关函数传入模拟参数看是否有语法错误或运行时异常。权限问题例如你的技能试图读取一个当前用户没有权限访问的文件或者写入一个受保护的目录。网络依赖问题如果技能需要访问外部API如天气查询、网络搜索请确保网络连通且API密钥如果有已正确配置。这些配置通常放在技能目录的.env文件或单独的配置文件中。6.3 性能优化与使用技巧技能目录不要过大skillz服务器在启动时会扫描整个技能目录并解析所有SKILL.md文件。如果目录中有成百上千个技能文件夹可能会略微增加启动时间。建议只保留常用的技能不用的可以移出目录或禁用重命名。利用符号链接组织技能你可以将技能按类别存放在不同位置然后在~/.skillz目录下创建对应的符号链接。这样既便于管理又不影响加载。# 假设技能按类别存放 ln -s ~/Documents/AI-Skills/Productivity ~/.skillz/productivity ln -s ~/Documents/AI-Skills/Development ~/.skillz/dev关注技能更新社区技能尤其是那些依赖外部API的可能会更新。定期关注你所用技能的源Git仓库获取更新和Bug修复。组合使用技能Gemini可以在一个对话中连续调用多个技能。你可以设计复杂的任务比如“先下载这个网页调用网页抓取技能然后提取主要内容并总结调用文本总结技能最后保存到我的笔记中调用文件写入技能”。通过自然语言描述多步任务Gemini可以尝试自动规划这些技能调用链。这个扩展将Gemini CLI从一个被动的代码建议者转变为一个能主动调用工具、执行复杂任务的智能体界面。它的价值在于利用成熟的MCP生态和Claude技能格式快速扩展了Gemini的能力范围。无论是处理本地文件、查询网络信息还是与开发工具链集成自定义技能都提供了无限的可能性。