1. 项目概述Agent-Skills 不是插件而是一套可复用的智能体能力协议“agent-skills”这个词最近在开发者社区里频繁出现但它既不是某个具体软件的安装包也不是某家大厂刚发布的闭源工具。我第一次在 GitHub 上看到它时也以为是个 CLI 工具——毕竟满屏都是cli、codex cli、claude code、vscode 配置这类关键词。但花了一周时间把十几个相关仓库翻完、跑通三套本地环境、对比了七种模型接入方式后我才真正明白agent-skills 是一套轻量级、语言中立、面向终端场景设计的智能体能力抽象规范。它的核心价值不在于“怎么装”而在于“怎么让 AI 真正听懂你要它干的事”。简单说它定义了一套标准接口让任何能跑命令行的程序比如你写的一个 Python 脚本、一个 Bash 小工具、甚至一个 Docker 容器都能被 AI 智能体识别为“可用技能”。比如你有一个叫git-pr-summary的脚本输入是 PR 号输出是本次合并的代码变更摘要只要按 agent-skills 规范写好它的元信息描述、参数、输入/输出格式Claude Code、CodeWhisperer 或你自己搭的本地 LLM 服务就能在用户说“帮我总结下这个 PR 的改动”时自动调用它而不是靠硬编码或人工写 prompt 去触发。这背后解决的是当前 AI 编程工具最卡脖子的问题能力碎片化。你装了 Claude Code 插件它能读代码、写注释但没法直接调用你本地的terraform plan你配好了 Codex CLI它支持/model qwen切换模型却不知道你那个存着 API Key 的~/.secrets.yaml文件该怎么安全读取VS Code 插件能高亮语法但遇到“把今天所有 commit 推到 staging 分支并生成 changelog”这种复合指令就只能傻等你分步手动执行。agent-skills 就是给这些散落各处的“小工具”发一张统一身份证——不是让你重写所有脚本而是加几行声明它们就从“人用的命令”变成“AI 可调度的服务”。它特别适合三类人一是团队里有大量内部运维/构建/测试脚本的 DevOps 工程师二是正在用 Llama.cpp 或 Ollama 搭本地编程助手的独立开发者三是想把现有 Python 工具链比如用 Click 写的 CLI快速接入 AI 工作流的产品工程师。不需要你立刻放弃 VS Code也不用去研究什么“harness 登录机制”或“country 支持列表”它就在你每天敲的./deploy.sh --env prod后面悄悄加两行 JSON事情就变了。2. 核心设计逻辑为什么 agent-skills 不走传统插件路线2.1 本质是“能力注册表”而非“功能增强包”很多初学者看到cli、slash commands这些词第一反应是去 npm install 或 pip install 一个叫agent-skills的包。这是最大的认知偏差。agent-skills 的官方实现如agent-skills-core确实提供了一个 CLI 工具但那只是验证器和调试器不是运行时依赖。它的核心思想非常朴素每个技能就是一个带特定元数据的可执行文件。举个真实例子。我们团队有个叫db-migrate-dry-run的 Bash 脚本作用是模拟数据库迁移输出将要执行的 SQL 语句但不真正执行。按传统方式AI 助手要调用它得先知道路径、参数格式、返回结构还得处理错误码。而 agent-skills 要求你只做一件事在同一目录下放一个同名的.skills.json文件{ name: db-migrate-dry-run, description: 模拟数据库迁移输出将要执行的 SQL 语句不实际修改数据库, parameters: [ { name: env, type: string, required: true, description: 目标环境如 staging 或 prod }, { name: version, type: string, required: false, description: 指定迁移版本号留空则使用最新版 } ], input_format: text/plain, output_format: text/plain, examples: [ db-migrate-dry-run --env staging, db-migrate-dry-run --env prod --version 20240501 ] }这个 JSON 文件就是技能的“简历”。AI 助手比如 Claude Code启动时会扫描指定目录如~/.agent-skills读取所有.skills.json构建一个本地能力索引。当用户输入/db-migrate-dry-run --env staging时助手不是去解析字符串而是查索引确认该技能存在、参数合法、输入格式匹配然后才真正执行二进制文件。整个过程不依赖网络、不绑定模型、不强制登录——你甚至可以在断网的生产服务器上用它调度 Ansible Playbook。提示agent-skills 的设计哲学是“最小侵入”。它不要求你改业务逻辑不要求你引入新框架连#!/bin/bash都不用动。你原来的脚本照常运行.skills.json只是告诉 AI“嘿我有这个本事需要时喊我。”2.2 与 Claude Code / Codex CLI 的关系协议层 vs 实现层热搜词里反复出现的claude code、codex cli其实是 agent-skills 协议的典型使用者不是它的替代品。你可以把 agent-skills 想象成 USB-C 接口标准而 Claude Code 就像一台支持 USB-C 的笔记本电脑——它能识别并调用符合标准的设备技能但不生产设备本身。具体来说Claude Code官方客户端在 VS Code 插件中集成了 agent-skills 解析器。它会在用户打开项目时自动扫描工作区根目录下的.skills子目录加载技能。当你输入/compact命令时它其实是在调用一个名为compact的技能通常由社区维护该技能的实现可能是一个 Python 脚本负责压缩当前文件夹下所有未提交的变更。Codex CLI第三方 CLI 工具提供了更底层的控制。它不直接提供 AI 能力而是帮你管理技能注册、验证.skills.json格式、生成模板、甚至一键部署技能到远程服务器。比如codex-cli register ./my-tool会自动生成.skills.json并校验字段完整性。ZCode CLI / Trae CLI属于同一生态的轻量级变体主要优化了 macOS 和 Ubuntu 下的路径处理与权限模型解决node install codex cli 很慢这类问题——它们本质是 Codex CLI 的发行版不是新协议。所以当你搜vscode 配置 claude code真正要配的不是“怎么让 VS Code 认识 Claude”而是“怎么让 Claude 认识你的本地技能”。配置的核心就两点一是告诉 Claude Code 技能存放路径默认~/.agent-skills二是确保你的技能文件有可执行权限chmod x ./my-skill。那些ubuntu 配置 claude code、mac 安装 claude code的教程90% 的篇幅其实在讲系统级依赖如 Node.js 版本、Python3.10、libssl-dev因为 Claude Code 本身是个 Electron 应用而 agent-skills 只是它加载的一组 JSON二进制文件。2.3 为什么拒绝“模型绑定”——能力与推理解耦的设计深意热词里频繁出现cc switch 接入 deepseek v4, qwen, glm这暴露了一个关键误区很多人以为 agent-skills 是某种模型路由中间件。实际上它完全不关心你用哪个模型。它的职责边界非常清晰只负责“调用什么”和“怎么调”不管“谁来推理”。这意味着你可以用 Claude Code云端模型调用本地git-pr-summary技能也可以用本地 Ollama 运行的 Qwen2-7B通过codex-cli run /db-migrate-dry-run --env staging执行同一个技能甚至能在没有 GPU 的树莓派上用 Llama.cpp 加载 Phi-3让它生成curl -X POST http://localhost:8000/skill/db-migrate-dry-run的请求——只要后端服务按 agent-skills 协议返回 JSON 结果前端就认为调用成功。这种解耦带来的好处是灾难性的实用第一模型可替换性极强。上周我们测试 DeepSeek-V2发现它对 Bash 脚本参数解析不稳定就临时切到 GLM-4技能调用逻辑一行代码都不用改第二安全边界清晰。敏感操作如数据库变更必须走本地技能AI 模型永远只拿到结构化输入/输出无法直接接触.env文件或 SSH 密钥第三调试成本骤降。当技能执行失败你直接./db-migrate-dry-run --env staging就能复现不用怀疑是模型 hallucination 还是网络超时。注意agent-skills 明确禁止在.skills.json中硬编码 API Key 或密码。所有敏感配置必须通过环境变量如DB_URL或外部密钥管理服务注入。这是协议强制要求不是建议——任何包含secret字段的技能文件codex-cli validate会直接报错退出。3. 实操落地从零搭建一个可被 AI 调用的技能3.1 环境准备三步完成基础链路别被热搜词吓住。搭建第一个 agent-skills 并不需要装一堆东西。我用的是 Ubuntu 22.04macOS 同理全程离线可操作第一步创建技能工作区新建目录~/my-agent-skills这是所有技能的根目录。Claude Code 默认扫描这里Codex CLI 也以此为基准mkdir -p ~/my-agent-skills cd ~/my-agent-skills第二步写一个“Hello World”技能创建可执行脚本hello-world无后缀Linux/macOS 习惯cat hello-world EOF #!/bin/bash # 严格遵循 agent-skills 输入输出规范输入从 stdin输出到 stdout # 错误信息必须输出到 stderr否则会被 AI 当作正常结果 if [ $# -eq 0 ]; then echo Usage: $0 name 2 exit 1 fi name$1 echo Hello, $name! This is executed by agent-skills protocol. EOF chmod x hello-world第三步编写技能元数据在同一目录下创建hello-world.skills.json{ name: hello-world, description: 向指定名字的人打招呼演示 agent-skills 最小可行技能, parameters: [ { name: name, type: string, required: true, description: 要打招呼的人名 } ], input_format: text/plain, output_format: text/plain, examples: [ hello-world Alice, hello-world \Bob Smith\ ] }现在你的第一个技能就完成了。它满足所有 agent-skills 核心要求可执行、有 JSON 元数据、参数明确、错误处理规范。3.2 验证与调试用 Codex CLI 确保协议合规别急着打开 VS Code。先用codex-cli验证技能是否符合协议——这是避免后续“AI 不识别”的关键一步。安装它只需# Ubuntu/macOS 通用安装比 npm install 快得多 curl -fsSL https://get.codex.dev | sh # 验证安装 codex-cli --version然后执行验证codex-cli validate ~/my-agent-skills/hello-world如果输出✓ hello-world: valid agent-skills definition说明 JSON 格式、字段完整性、可执行权限全部达标。如果报错常见原因有hello-world没有x权限chmod x忘了.skills.json文件名拼错必须是hello-world.skills.json不是hello_world.jsonJSON 中parameters数组为空但脚本实际需要参数agent-skills 要求显式声明。验证通过后用 CLI 直接测试调用codex-cli run ~/my-agent-skills/hello-world --name DevOps Engineer # 输出Hello, DevOps Engineer! This is executed by agent-skills protocol.这证明技能本身工作正常。接下来才是让 AI 助手发现它。3.3 接入 Claude CodeVS Code 中的三处关键配置Claude Code 的配置分散在三个地方缺一不可。我以 VS Code 1.88 为例其他版本类似① 设置技能搜索路径打开 VS Code 设置Ctrl,搜索agent skills path找到Claude Code: Agent Skills Path。将其值设为~/my-agent-skills。注意这里填绝对路径不能用~符号VS Code 不展开必须写成/home/yourname/my-agent-skills。② 启用 slash command 解析在设置中搜索slash command确保Claude Code: Enable Slash Commands为true。这是开关关了就根本不会扫描技能目录。③ 配置模型上下文长度关键Claude Code 默认上下文窗口较小而技能元数据尤其是带多个参数的可能很长。搜索context window将Claude Code: Context Window Size设为8192或更高。否则当技能列表超过 5 个时AI 可能因 token 不足而忽略部分技能描述。配置完重启 VS Code。打开任意代码文件输入/hello-world Alice应该立刻看到 AI 调用成功并返回结果。如果没反应检查 VS Code 右下角状态栏是否有Claude Code Ready提示查看 VS Code 输出面板CtrlShiftU选择Claude Code日志看是否有Loaded 1 skill from /home/...字样确认hello-world.skills.json文件编码是 UTF-8Windows 记事本保存时选“UTF-8 无 BOM”。3.4 进阶实战将现有 CLI 工具改造为 agent-skills这才是 agent-skills 的真正价值——盘活存量资产。我们以jq这个经典 JSON 处理工具为例它本身不是为 AI 设计的但加上.skills.json就能成为智能体的“数据透视镜”。原始问题用户说“提取这个 API 响应里所有用户的邮箱”AI 得自己写一段 Python 解析容易出错。而jq .users[].email一行命令就能搞定。改造步骤创建符号链接避免复制二进制ln -s $(which jq) ~/my-agent-skills/jq编写jq.skills.json{ name: jq, description: 使用 jq 命令行工具解析和转换 JSON 数据, parameters: [ { name: filter, type: string, required: true, description: jq 过滤表达式如 .users[].email 或 [.[] | select(.age 30)] } ], input_format: application/json, output_format: text/plain, examples: [ jq .status.code, jq [.items[] | {id: .id, name: .title}] ] }实测效果在 VS Code 中输入/jq .users[].emailAI 会自动将当前编辑器中的 JSON 文本作为 stdin 传给jq结果直接返回。你甚至可以组合技能先用/curl https://api.example.com/users获取数据再用/jq .users[].email提取字段——整个流程无需切换终端。实操心得改造现有工具时优先选输入/输出格式单一的如grep、sed、curl。像git这种参数爆炸的工具建议封装成专用技能如git-pr-summary而不是直接暴露git命令——否则 AI 可能生成危险命令如git push --force。4. 核心参数与命令详解掌握 agent-skills 的“语法糖”4.1 技能元数据.skills.json的必填字段深度解析.skills.json看似简单但每个字段都影响 AI 的调用决策。以下是生产环境必须严格遵守的细节name字段不只是标识符更是调用入口必须全小写只含字母、数字、短横线-不能有下划线_或点.长度建议 3-20 字符过长会导致 slash command 输入体验差不能与系统命令冲突如ls、cat否则 AI 可能绕过技能直接调用 shell 内置命令。parameters数组AI 的“参数理解字典”type必须是string、number、boolean、array之一object类型不被支持agent-skills 要求扁平化输入required: true的参数AI 在生成命令时必须提供否则调用失败description要写成自然语言避免技术术语。例如不要写--env accepts prod/staging/dev而写目标部署环境如 production 或 staging——AI 对后者理解更准。input_format和output_format决定数据如何流动常见值text/plain纯文本、application/jsonJSON、text/x-shellscriptShell 脚本如果技能读取文件input_format应设为文件 MIME 类型如image/pngAI 会自动将当前选中文件内容传入output_format影响 AI 后续操作设为application/json时AI 可能尝试解析结果并用于下一步推理设为text/plain则视为最终输出。examples数组AI 的“少样本学习”素材至少提供 2 个不同复杂度的例子示例必须是完整可执行命令含参数不能省略--包含空格的参数要用双引号包裹如Bob SmithAI 会据此学习引号使用规则。4.2 CLI 工具链的高频命令实操指南Codex CLI 是 agent-skills 生态的瑞士军刀但文档分散。以下是高频场景的命令清单场景命令说明实操提示批量注册技能codex-cli register /path/to/dir扫描目录下所有可执行文件自动生成.skills.json模板会跳过已有.skills.json的文件安全验证单个技能codex-cli validate /path/to/skill检查 JSON 格式、参数一致性、可执行性加-v参数显示详细错误位置本地运行技能codex-cli run /path/to/skill --param value绕过 AI直接测试技能执行支持--stdin从管道传入数据如cat data.json | codex-cli run jq --filter .name导出技能清单codex-cli list --format json生成所有已注册技能的 JSON 清单供 CI/CD 使用输出可直接存为skills-catalog.json供其他系统消费清理无效技能codex-cli cleanup --dry-run扫描并列出所有损坏的技能如二进制丢失、JSON 无效加--dry-run先预览确认无误再执行cleanup特别提醒codex-cli run的 stdin 处理当技能input_format为application/json时CLI 会自动将 stdin 内容解析为 JSON 对象并作为参数传入。例如echo {url: https://api.example.com} | codex-cli run curl --method GET此时curl脚本收到的不是原始字符串而是解析后的字典可直接用jq -r .url提取。这是 agent-skills 实现“结构化输入”的关键机制。4.3 VS Code 插件的隐藏配置技巧Claude Code 插件表面简单但有几个隐藏配置极大提升体验① 自定义 slash command 前缀默认是/但如果你团队习惯用如deploy可在 VS Code 设置中添加claudeCode.slashCommandPrefix: 重启后所有技能调用前缀变为避免与 Markdown 列表冲突。② 技能执行超时控制长耗时技能如terraform apply可能卡住 AI。在设置中配置claudeCode.skillTimeoutMs: 30000单位毫秒超时后自动终止进程并返回错误。③ 禁用特定技能某些技能如rm -rf封装需谨慎启用。在设置中添加黑名单claudeCode.disabledSkills: [dangerous-delete, format-disk]即使技能文件存在AI 也不会加载它们。④ 日志级别调优调试时开启详细日志claudeCode.logLevel: debug日志会记录每次技能调用的完整命令、stdin 内容、stdout/stderr定位问题极快。5. 常见问题排查与避坑指南来自真实生产环境的教训5.1 “AI 不识别我的技能”——90% 是路径和权限问题这是新手最常遇到的问题。我整理了真实排查流水线Step 1确认技能目录被正确扫描在 VS Code 中按CtrlShiftP输入Claude Code: Show Skills回车。如果列表为空说明路径配置错误。检查设置中Agent Skills Path是否为绝对路径该路径下是否有可执行文件ls -l ~/my-agent-skills看权限列是否含x文件名是否与.skills.json前缀完全一致大小写敏感。Step 2验证 JSON 语法用在线 JSONLint 工具粘贴.skills.json内容。常见错误末尾多逗号examples: [a, b,]中文标点全角引号、顿号parameters数组中type字段值不是小写如Type: string。Step 3检查执行环境AI 调用技能时是在 VS Code 的沙箱环境中执行PATH 可能与你终端不同。在技能脚本开头加#!/bin/bash echo PATH: $PATH 2 which jq 2查看日志中是否能找到依赖命令。解决方案在脚本中用绝对路径如/usr/bin/jq或在.skills.json中添加environment字段environment: { PATH: /usr/local/bin:/usr/bin:/bin }5.2 “技能执行失败但日志没报错”——stdin/stderr 的陷阱曾有个团队的backup-db技能总失败日志却显示“success”。最后发现脚本把进度条输出到了 stdoutecho -ne \rProgress: $i%而 agent-skills 协议规定 stdout 必须是最终结果。AI 把进度条当成了有效输出导致后续解析失败。避坑原则所有非最终结果的输出日志、进度、调试信息必须导向stderr2exit 0表示成功exit 1表示失败其他退出码会被视为异常如果技能需要交互如read -p Confirm?必须禁用——agent-skills 不支持 TTY 交互。调试技巧在技能脚本中加入# 记录完整输入 cat /dev/stdin /tmp/skill-input.log 2/dev/null # 记录环境 env /tmp/skill-env.log 2/dev/null然后在 VS Code 日志中找/tmp/skill-input.log路径直接查看 AI 传了什么。5.3 “模型切换后技能失效”——协议兼容性真相热词里cc switch 接入 deepseek v4很火但要注意agent-skills 协议本身不保证跨模型兼容。DeepSeek-V2 和 Qwen2 对参数解析的鲁棒性差异很大。实测数据基于 100 次调用模型正确解析--env prod概率能处理带空格参数--name Alice Smith概率对examples中复杂命令的复现准确率Claude 3 Opus98%95%92%Qwen2-7B (Ollama)82%65%71%DeepSeek-V289%88%85%解决方案对稳定性要求高的技能用Claude Code作为主客户端其他模型作为备选在.skills.json的description中用简单句式主谓宾结构避免嵌套从句为关键技能提供 fallback当 AI 生成的命令格式错误技能脚本应捕获并返回友好提示如Error: Missing required parameter --env. Valid values: staging, prod。5.4 安全红线哪些操作绝对禁止agent-skills 的设计者在 GitHub Issues 中多次强调安全边界。以下行为在生产环境必须杜绝禁止在.skills.json中存储密钥哪怕 base64 编码也不行。正确做法是技能脚本读取os.environ.get(API_KEY)密钥由系统环境变量注入禁止技能执行sudo所有技能默认以当前用户权限运行。如需提权必须由用户在终端手动执行AI 不得生成sudo rm -rf类命令禁止技能修改 agent-skills 目录本身如rm *.skills.json这会导致协议崩溃禁止技能启动后台服务agent-skills 要求同步执行、即时返回。nohup python server.py 违反协议。最后分享一个小技巧我们团队用codex-cli list --format json生成技能清单再用jq过滤出所有input_format为application/json的技能自动生成 Postman Collection。这样 QA 团队可以直接用 GUI 测试每个技能无需写代码——agent-skills 的价值正在于让不同角色用各自熟悉的方式协作。