这次我们来看一个和 AI Agent 能力扩展直接相关的项目方向google / skills。严格说它不是一个需要显卡才能跑的本地模型项目而是一套围绕 Agent Skills 机制的技术方案。它解决的核心问题是让 Claude Code、Gemini CLI、Codex 这类 AI 编程助手不再只会“对话”而是能在固定目录结构下读取技能说明、执行脚本、调用外部工具完成批量化和专业化的任务。到了 2025 年skills 已经成为 AI 编程助手的标准扩展方式之一Google 生态里也有对应工具在跟进。从检索热度看关注这个方向的人普遍带着这些需求skills 推荐、skills 下载、skills 开发、superpower skills 安装、agent skills 推荐、claude code skills。也就是说大家已经过了“skills 是什么”的认知阶段开始关心“哪些 skills 值得装”“怎么装”“怎么自己写”。这篇文章就按这个顺序展开。我会先给一个核心能力速览然后讲环境准备、安装部署、功能测试、接口与批量任务、资源占用、问题排查和最佳实践。全程不含需要 GPU 的步骤绝大多数操作在普通开发机上就能完成。1. Google Skills 核心能力速览先给一张规格表方便快速判断方向。需要说明的是skills 生态迭代很快不同工具对 skills 的实现细节并不完全一致下表给出的是当前主流实现中的通用能力项能力项说明项目类型Agent Skills 技能包、开发规范与工具链解决的核心问题让 AI 编码助手按固定流程调用外部工具替代手工反复指令主流载体Claude Code、Gemini CLI、Codex、OpenCode、Cline 等 Agent CLI是否需要 GPU不需要运行环境以开发机和命令行为主显存占用无显存需求skill 本身是文本与脚本占用 KB 到 MB 级别是否支持 CPU是skills 执行取决于脚本不依赖 GPU是否支持批量任务是可通过 shell 循环、目录扫描或调度器批量触发是否提供 API 接口取决于底层 Agent 工具链可通过工具调用协议对外暴露启动方式配置目录 CLI 启动部分工具支持可视化配置技能格式SKILL.md scripts 脚本 assets 资源文件主要来源社区开源技能包、自定义技能、官方技能 hub适合场景代码审查、文档总结、批量录入、浏览器操作、研究辅助等这张表里最值得注意的两点第一skills 不是模型不需要考虑显卡和显存第二它真正的瓶颈在“上下文窗口”和“token 成本”因为每个技能的描述都会被 Agent 读入上下文技能数量越多占用越大。这一点在后面的资源占用部分会详细展开。2. Skills 的底层原理SKILL.md 与工具调用在讲安装前先搞清楚 skills 是怎么工作的。无论具体的 Agent 工具是 Claude Code、Gemini CLI 还是 Codex它们实现 skills 的方式都有共同点。2.1 SKILL.md 是技能的说明书一个 skill 通常是一个目录目录里必须有 SKILL.md 文件。这个文件的 frontmatter 包含技能名称 name 和描述 description。Agent 在启动时会扫描技能目录把每个技能的 name 和 description 读入上下文。当用户请求的内容与某个 description 匹配时Agent 就会读取完整的 SKILL.md按里面的指令执行。一个极简的 SKILL.md 结构如下--- name: pdf-summarizer description: 用于提取 PDF 文档内容并生成结构化摘要。当用户要求总结 PDF 文件时使用。 --- # PDF 总结技能 ## 执行步骤 1. 运行 python scripts/run.py pdf_path 2. 读取脚本输出的文本 3. 按 Markdown 格式输出摘要 ## 注意事项 - 只处理本地文件 - 不读取文件中的敏感信息这段结构说明有两层意思第一SKILL.md 本身就是给 Agent 看的“操作手册”不需要额外训练模型第二技能的核心执行逻辑可以落在任何语言写的脚本上Python、Node.js、Shell 都可以。2.2 Skills 与 MCP 的边界很多人在配置 skills 时容易和 MCP 混在一起。MCP 是模型上下文协议它解决的是“Agent 和外部数据源或工具之间的通信标准”skills 更偏“给 Agent 一组固定的、可复用的操作流程”。两者可以共存skill 内部的脚本可以调用 MCP 服务MCP 服务也可以把能力封装成 skill。实际使用中优先选择生态支持更好的那一种不要在这两个概念上死磕能跑通任务才是重点。3. 适用场景与使用边界3.1 适合谁用先说适合人群已经在使用 Claude Code、Gemini CLI、Codex 等命令行 AI 工具的人在 Google 开发环境或 Google 生态工具链中做前端、研究、文档处理的人需要把重复性操作代码检查、日报生成、批量文档总结沉淀成固定流程的团队对 MCP、Agent 编程感兴趣想低成本试水的人。skills 的价值不是让模型变强而是把“稳定的执行流程”固化下来。举例你每周都要让 AI 按固定格式整理一组文献每次都要写一长串提示词效果还不稳定做成 skill 后一句“跑一下文献整理技能”就能触发固定流程输出格式和检查点都是提前定义的。这种价值在重复性任务越多的地方越明显。3.2 不适合什么场景不想用命令行工具、只想要网页版聊天界面的人skills 的体验会打折扣追求零成本的人群因为技能执行本身仍然要消耗 LLM token需要实时视频、音频生成等高算力的场景skills 不解决这类问题对完全未知来源的技能包直接生产使用风险很高不建议。这里要特别说明skills 不是“万能插件”。它解决的是流程自动化问题不是模型能力不足的问题。如果模型本身对某个专业领域理解很差给它挂一个 skill 也不能从根本上改变输出质量。3.3 安全与合规边界skills 本质上是可执行代码安装来源不明的技能包可能带来数据泄露、命令执行等风险。建议优先选择公开可信、最近有更新维护的技能包安装前查看 SKILL.md 和 scripts 目录内容确认脚本行为涉及公司代码、客户数据、个人隐私时先在小环境隔离测试如果技能涉及人脸、声音、版权素材或品牌内容必须确认素材授权和肖像许可避免在未授权素材上做处理不要通过 skills 去绕过任何平台的限制或爬取需授权的数据。4. 环境准备与前置条件skills 的安装通常不依赖重型环境但需要准备一个能跑 Agent CLI 的机器。4.1 操作系统Windows、macOS、Linux 都行。命令行工具在主流的 Agent CLI 里均支持。需要注意的是Windows 下脚本路径、换行符、权限问题比 Linux/macOS 更多路径尽量不包含中文和空格脚本必须要有执行权限。Linux 服务器部署时还要额外注意当前用户是否有写权限避免技能目录创建失败。4.2 依赖项至少需要- 一个 AI 编码助手 CLIClaude Code、Gemini CLI、Codex、OpenCode 等任选其一 - 对应的 API Key 或本地推理服务地址 - Git用于拉取技能包 - 根据技能脚本情况安装 Python 3.10 或 Node.js 18版本号属于通用建议需要以实际工具说明为准。安装 CLI 的部分不需要展开各工具官网都有标准安装命令。如果你的网络环境无法直接访问模型服务商也可以选择本地推理方案但要注意本地模型对复杂技能指令的遵循能力通常弱于商用模型技能越复杂越明显。4.3 磁盘与端口skills 对磁盘要求很低单个技能通常几 KB 到几 MB。如果只是安装现成技能包预留 500MB 足够如果要存放大量 PDF、图片等素材磁盘按素材量规划。端口一般不用额外配置除非技能内部启动了本地 web 服务。启动本地服务时建议绑定 127.0.0.1避免暴露到局域网。5. 安装部署与启动方式由于“google / skills”并没有一份全行业统一的安装脚本实际操作需要区分两种方式一是安装现成技能包二是手动创建一个技能目录。下面给出通用流程具体目录名以你使用的 Agent 工具文档为准。5.1 方式一安装现成技能包以社区常用的目录拷贝方式为例# 1. 克隆或下载技能包仓库 git clone https://example.com/some-skills-repo.git ~/some-skills-repo # 2. 查看仓库里的 skills 目录例如 # ~/some-skills-repo/skills/pdf-summarizer # 3. 把技能目录拷贝到 Agent 的 skills 目录 # 不同工具的实际目录名不同需要按官方文档确认 cp -r ~/some-skills-repo/skills/pdf-summarizer ~/.config/agent-skills/ # 4. 重启 Agent CLI 会话让技能被重新扫描注意上方的仓库地址是占位示例实际使用时替换为技能包的官方地址。不同 Agent 工具的 skills 目录位置、配置文件名并不一致一定要先看对应工具文档不要照搬。安装完成后建议先用 ls 命令确认目录结构已经完整拷贝避免漏掉 scripts 或 assets 子目录。5.2 方式二手动创建一个 skill如果找不到合适的现成技能包直接手动创建这是最稳妥的方式。# 在技能目录下新建一个技能 mkdir -p ~/.config/agent-skills/pdf-summarizer/scripts cd ~/.config/agent-skills/pdf-summarizer创建 SKILL.md 文件--- name: pdf-summarizer description: 提取 PDF 文档内容并生成结构化摘要。当用户要求总结 PDF 文件时使用。 --- # PDF 总结技能 执行 python scripts/run.py pdf_path按照输出生成 Markdown 摘要。创建 scripts/run.pyimport sys import os def main(): pdf_path sys.argv[1] if not os.path.exists(pdf_path): print(fERROR: file not found: {pdf_path}) sys.exit(1) print(fProcessing: {pdf_path}) # 这里可以接入 pypdf、pdfplumber 等解析库 print(This is a placeholder output.) if __name__ __main__: main()然后给脚本加执行权限chmod x ~/.config/agent-skills/pdf-summarizer/scripts/run.py这个手动创建的 skill 已经满足“能被 Agent 识别”的基本条件。真正的解析逻辑可以在占位位置接入 PDF 解析库。这种做法的好处是不依赖任何第三方包路径清晰出问题容易排查。相比直接下载别人的技能包手动创建还能让你更快理解 SKILL.md、scripts、assets 三层结构之间的关系。5.3 启动方式大多数 Agent CLI 在对话中直接输入自然语言即可触发 skill不需要单独“启动服务”。例如在 CLI 里输入“用 pdf-summarizer 技能总结 ./report.pdf”。如果配置正确Agent 会读取技能目录并调用脚本。还有一部分工具支持预热或技能列表命令具体以工具官方文档为准。启动后如果发现技能没有被触发优先检查技能目录是否在 Agent 的扫描路径里而不是反复重装。6. 功能测试与效果验证安装完技能之后第一件事不是批量处理文件而是做一次最小验证。6.1 最小验证流程测试目的确认技能是否被 Agent 发现、SKILL.md 是否被读取、脚本是否能执行。操作步骤准备一个测试文件例如 test.pdf在 Agent CLI 中触发技能输入上面提到的自然语言指令观察 Agent 是否输出了脚本的执行结果而不是只做通用回答查看脚本是否真实运行可以在 run.py 里临时增加一行日志写入比如将输出重定向到日志文件检查输出是否符合 SKILL.md 里定义的格式。判断标准Agent 能调用技能脚本、脚本输出能被 Agent 正确引用并且最终回复格式符合预期视为验证通过。如果结果不对不要急着换技能先回到第 3 步确认执行链路。常见失败原因技能目录没有被 Agent 扫描到目录名或配置不对SKILL.md 的 frontmatter 格式错误description 缺失脚本执行权限不够或者依赖库没装路径中包含特殊字符导致脚本参数解析失败。6.2 多技能联调测试如果同时安装了多个技能建议做一次“技能路由”验证。输入一个模糊请求观察 Agent 是否会选中最相关的技能。例如同时装了 pdf-summarizer 和 code-reviewer输入“帮我看看这份 PDF 的报告结构”正确行为是调用 pdf-summarizer而不是 code-reviewer。如果 Agent 经常选错优先检查各技能的 description 是否足够具体。description 写得越含糊路由错误越常见。7. 接口 API 与批量任务7.1 技能内部如何暴露能力在“google / skills”生态里一个技能对外暴露能力的主要方式不是传统 REST API而是“工具调用”协议。用户输入自然语言Agent 解析后调用技能脚本脚本以 stdout 返回结构化结果。如果希望把技能包装成可被其他系统调用的服务可以选择两种路径在技能脚本里起一个 HTTP 服务接收 POST 请求并返回结果通过 MCP server 把技能包装成标准的工具接口供支持 MCP 的客户端调用。第二种方式更接近现代 Agent 工具链的做法也更通用。下面是一个 Flask 风格的技能服务示例仅作设计参考from flask import Flask, request, jsonify import subprocess import os app Flask(__name__) app.route(/summarize, methods[POST]) def summarize(): data request.get_json() pdf_path data.get(pdf_path, ) if not os.path.exists(pdf_path): return jsonify({error: file not found}), 404 result subprocess.run( [python, scripts/run.py, pdf_path], capture_outputTrue, textTrue ) return jsonify({ stdout: result.stdout, stderr: result.stderr, returncode: result.returncode }) if __name__ __main__: app.run(host127.0.0.1, port8000)这段示例说明技能脚本可以在内部启动本地服务。启动前建议绑定 127.0.0.1避免暴露到局域网。生产使用前要做鉴权不能裸奔在外网。如果技能需要接收外部回调也要在网关层做签名校验。7.2 批量任务设计批量处理是 skills 最常见的生产场景之一。最简单的批量任务就是写一个 shell 循环把目录下所有文件逐个交给 Agent#!/usr/bin/env bash mkdir -p outputs for file in ./docs/*.pdf; do echo Processing $file claude -p 使用 pdf-summarizer 技能处理 $file outputs/$(basename $file).md done这个命令里的 claude 是通用占位。实际使用时替换成你正在用的 Agent CLI 命令并确认它支持命令行非交互调用。批量任务要注意三点第一逐条执行时留意频率限制和 token 成本第二建议每处理一个文件就记录一次日志方便失败重试第三中间文件按批次命名避免覆盖。如果是更重度的批量任务建议写成 Python 队列脚本加入重试、超时和幂等控制。核心思路是不要让 Agent 自己管理批量而是由外部脚本控制文件列表Agent 每次只负责一个文件或一个批次。这样可以避免上下文串扰也让失败重试更可控。8. 资源占用与性能观察8.1 技能本身占用技能目录由文本和脚本组成单个技能通常只有 KB 到 MB 级别磁盘占用可以忽略。真正值得观察的是两类资源上下文窗口和 token 消耗。每添加一个技能Agent 都会把技能的 name 和 description 读入上下文。几十个技能还好如果装了上百个技能光是技能描述就可能占用几千 token。上下文窗口被技能描述占满后能留给实际任务的空间就会变少。这也是很多“技能装多了反而变笨”的现象来源。因此技能数量要克制不能只装不用。8.2 如何观察资源占用使用 Agent CLI 的 verbose 或 debug 模式查看每次请求中的系统提示词和技能描述长度在脚本里用 time 命令记录单次执行耗时time python scripts/run.py ./docs/test.pdf查看 token 用量大多数 CLI 工具会在会话结束时统计 token 消耗批量任务中监控进程数和网络请求数避免并发过高触发限流。以实际经验来看单次技能调用的 token 消耗大头在 SKILL.md 全文和目标任务的内容上脚本本身只占很小比例。如果发现 token 消耗异常高先看是不是 SKILL.md 里塞了过多背景知识这些内容每次都会被完整读入。8.3 如何降低占用精简 SKILL.md只保留必要指令描述信息尽量短而明确不常用的技能从扫描目录移出使用时再放回来技能拆分成“核心技能”和“按需加载技能”两类大批量任务优先用脚本内部处理不要每份文件都触发一次完整 Agent 对话。9. 常见问题与排查方法问题现象可能原因排查方式解决方案Agent 没有识别到技能技能目录不在扫描范围或目录名配置错误查看 Agent 的配置文件和扫描目录确认目录路径重启 CLI 会话SKILL.md 读取失败frontmatter 格式错误用文本编辑器检查文件头修正 name、description 字段去掉多余符号脚本调用失败脚本无执行权限在终端直接执行脚本看报错chmod x或直接用 python 调用路径不存在输入文件路径相对位置不对打印当前工作目录使用绝对路径或确认 CLI 的工作目录依赖库缺失技能脚本用了未安装的库运行 pip list 检查按技能文档安装依赖技能装多了上下文变长技能描述占用上下文太多查看 verbose 日志精简技能描述减少技能数量批量任务卡住某个文件让脚本死循环或等待输入加入超时参数脚本外层加 timeout 和重试输出格式不稳定技能指令颗粒度不够对比多次输出差异在 SKILL.md 中定义更严格的输出模板API 调用返回找不到端点技能服务端口未启动先 curl 健康检查启动本地服务确认监听端口来源不明的技能执行了危险命令脚本包含未审计操作检查 scripts 目录删除并替换为可信来源技能这张表里最常遇到的其实是前三个目录没扫到、格式错误、权限不够。这三个问题排查清楚大部分安装使用场景就不会卡住。10. 最佳实践与使用建议10.1 先小规模后批量第一次使用技能包时先用一个最小文件验证再扩大到整个目录。批量前在脚本里加上 --dry-run 模式打印将要处理的文件列表确认没有问题后再执行。这个习惯能避免批量任务跑了一半才发现技能行为不符合预期浪费 token 还污染输出目录。10.2 目录与文件管理建议按以下结构管理技能和素材agent-skills/ ├── pdf-summarizer/ ├── code-reviewer/ ├── research-helper/ ├── inputs/ # 待处理素材 ├── outputs/ # 结果输出 └── logs/ # 执行日志输入、输出、日志分离便于批量任务失败后重新定位问题。特别是日志目录即使是最简单的技能调用也值得保留一条执行记录方便回溯。10.3 版本化技能技能包本身是代码。将它纳入 Git 管理每次修改都记录变更。团队多人协作时技能目录放在共享仓库里统一版本。这样至少能回答“这个技能是谁改的、改了什么、为什么行为变了”这些问题。技能出问题时git bisect 同样适用先定位到具体提交再回滚。10.4 隔离敏感数据涉及公司代码、客户数据、个人隐私时不要直接把数据交给在线 Agent 处理。可以先在本地脚本里完成脱敏再把脱敏结果交给 Agent。技能脚本里也不要硬编码密钥使用环境变量。这个原则和传统后端开发完全一致数据面与控制面分离。10.5 定期审查第三方技能第三方技能包不是不能装而是装之前要审。具体做法打开 SKILL.md 通读逻辑检查 scripts 下是否有网络请求、文件删除、执行 shell 等敏感操作确认依赖列表。一旦发现未声明的网络外传或高危操作放弃使用。不要因为某个技能在社区里热度高就直接信任。11. 总结与下一步回到最初的问题google / skills 这个方向值不值得花时间从生态热度看答案是肯定的。Agent Skills 是目前把 AI 编码助手从“对话型”推向“生产型”的少数通用机制之一。它不需要 GPU不需要大改现有工作流只需要一个 Agent CLI、一个技能目录和一个可执行的脚本就能把重复操作固化成稳定的技能包。如果你准备开始尝试建议按下面的顺序验证先创建一个最简单的 SKILL.md 技能确认 Agent 能识别再让技能调用一个实际脚本验证执行链路加一个批量处理脚本跑通“目录输入 - 技能处理 - 结果输出”的完整流程最后再考虑从社区安装第三方技能包并在隔离环境里做安全审查。最容易踩的坑是以为装完技能就能完全自动化实际上技能的描述质量、脚本稳定性和批量调度逻辑决定了最终效果的上下限。先把最小闭环跑通再逐步扩展是性价比最高的路径。把这篇文章收藏备用等到真要配置 skills 时按目录结构走一遍就够了。