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.04（macOS 同理），全程离线可操作：

第一步：创建技能工作区
新建目录~/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.json）；
• JSON 中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 Code：VS 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 输出面板（Ctrl+Shift+U），选择Claude Code日志，看是否有Loaded 1 skill from /home/...字样；
• 确认hello-world.skills.json文件编码是 UTF-8（Windows 记事本保存时选“UTF-8 无 BOM”）。

3.4 进阶实战：将现有 CLI 工具改造为 agent-skills

这才是 agent-skills 的真正价值——盘活存量资产。我们以jq这个经典 JSON 处理工具为例，它本身不是为 AI 设计的，但加上.skills.json就能成为智能体的“数据透视镜”。

原始问题：用户说“提取这个 API 响应里所有用户的邮箱”，AI 得自己写一段 Python 解析，容易出错。而jq '.users[].email'一行命令就能搞定。

改造步骤：

1. 创建符号链接（避免复制二进制）：

   ln -s $(which jq) ~/my-agent-skills/jq

2. 编写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[].email'，AI 会自动将当前编辑器中的 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/json（JSON）、text/x-shellscript（Shell 脚本）；
• 如果技能读取文件，input_format应设为文件 MIME 类型（如image/png），AI 会自动将当前选中文件内容传入；
• output_format影响 AI 后续操作：设为application/json时，AI 可能尝试解析结果并用于下一步推理；设为text/plain则视为最终输出。

examples数组：AI 的“少样本学习”素材

• 至少提供 2 个不同复杂度的例子；
• 示例必须是完整可执行命令（含参数），不能省略--；
• 包含空格的参数要用双引号包裹（如"Bob Smith"），AI 会据此学习引号使用规则。

4.2 CLI 工具链的高频命令实操指南

Codex CLI 是 agent-skills 生态的瑞士军刀，但文档分散。以下是高频场景的命令清单：

特别提醒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 中按Ctrl+Shift+P，输入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”。最后发现：脚本把进度条输出到了 stdout（echo -ne "\rProgress: $i%"），而 agent-skills 协议规定 stdout 必须是最终结果。AI 把进度条当成了有效输出，导致后续解析失败。

避坑原则：

• 所有非最终结果的输出（日志、进度、调试信息）必须导向stderr（>&2）；
• exit 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 次调用）：

解决方案：

• 对稳定性要求高的技能，用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 的价值，正在于让不同角色用各自熟悉的方式协作。