1. “agent-skills”不是插件名而是现代开发者工作流的底层协议层你第一次在 GitHub 或 Discord 群里看到agent-skills这个词大概率是在某个 CLI 工具的 issue 里——比如有人贴出报错Error: unable to locate the codex cli binary or required skills或者在 VS Code 扩展配置项中发现一行注释“skillsDir: ~/.codex/skills”又或者在 Cursor 的 settings.json 里看到claude.code.skillsPath: ./skills。它从不单独存在永远依附于某个 CLI 主体codex、trae、zcode、deveco、minimax-code-cli但所有这些工具却共享同一套技能组织范式。这不是巧合而是一次静默发生的协议收敛。“agent-skills”本质上是一套可执行能力单元的标准化封装协议。它规定了一个“技能”必须是什么结构、如何被发现、怎样被调用、参数如何传递、输出如何归一化。它不关心你是用 Python 写的图像生成脚本还是用 TypeScript 写的 LaTeX 编译器或是用 Rust 写的 Word/PPT 结构解析器——只要它符合这个协议就能被任意兼容该协议的 CLI 主体识别、加载、调度。这就像 USB 接口标准U 盘、打印机、摄像头物理形态天差地别但只要遵循 USB 协议就能插进同一台电脑的同一个接口。为什么这个协议突然密集出现在前端、AI 编程、低代码工具链中因为传统 IDE 的功能扩展方式如 VS Code 的 Extension API太重需要注册 activationEvents、管理生命周期、处理 UI 渲染、适配多端。而开发者真正需要的往往只是“在当前文件上按 CtrlShiftP输入 Generate Diagram回车就生成一张 Mermaid 图”——这个动作背后不需要弹窗、不需要状态栏图标、不需要上下文菜单项只需要一个能接收文件路径、返回 Markdown 字符串的命令行程序。agent-skills就是为这种“原子级操作”量身定制的轻量协议。它和npm的关系类似Dockerfile和docker buildnpm是包管理器Dockerfile是构建指令描述codex cli是运行时agent-skills是能力描述规范。你npx codex skills install math-modeling实际执行的是下载一个符合agent-skills协议的目录结构将其解压到~/.codex/skills/math-modeling然后 CLI 在启动时扫描该目录读取其manifest.json确认它声明支持text/plain输入和image/svgxml输出于是当你选中一段 LaTeX 公式文本并触发math-modeling.render命令时CLI 就会调用./bin/render.js --input /tmp/xxx.txt --output /tmp/yyy.svg。提示不要试图在node_modules里找agent-skills包。它不是一个 npm 包而是一个约定俗成的目录结构与元数据规范。你在 GitHub 搜索agent-skills manifest.json会看到上千个独立仓库它们彼此不依赖却能被同一套 CLI 加载——这就是协议的力量。我第一次意识到它的存在是在调试claude code cli无法加载superpower-skills时。反复检查PATH、NODE_ENV、权限全无效果。最后用strace -e traceexecve codex skills list抓系统调用才发现 CLI 根本没尝试执行skills/bin/latex-render而是卡在openat(AT_FDCWD, /home/user/.codex/skills/latex-render/manifest.json, O_RDONLY)返回ENOENT。原来superpower-skills仓库里manifest.json被误提交到了src/子目录下主目录只有README.md和package.json。CLI 严格遵循协议只认根目录下的manifest.json。这个坑让我花了三小时也让我彻底理解agent-skills的核心价值不是功能多强大而是消除歧义——当一千个开发者各自实现“生成图表”功能时协议强制他们用同一套字段描述输入输出用同一路径存放可执行文件用同一方式声明依赖。没有协议就没有互操作性没有互操作性AI 编程工具就永远是孤岛。2. 解剖一个真实技能math-modeling的完整结构与执行链路我们以网络热词中高频出现的math-modeling技能为例拆解一个符合agent-skills协议的完整项目。这不是虚构示例而是基于awesome-claude-skills仓库中真实存在的math-modeling-solver改写去除了敏感依赖保留全部协议关键点。2.1 目录结构协议即目录即契约一个合法的agent-skills技能必须是一个扁平目录不能嵌套在子目录下其根目录下必须包含以下文件math-modeling/ ├── manifest.json # 协议核心声明能力元数据 ├── bin/ # 可执行入口所有命令从此处调用 │ ├── solve.py # 主逻辑接收 stdin输出 stdout │ └── validate.py # 辅助脚本CLI 可能调用它验证环境 ├── assets/ # 静态资源模型权重、模板文件、字体等 │ ├── model.onnx │ └── template.tex ├── requirements.txt # Python 依赖仅当使用 Python 时存在 ├── package.json # Node.js 依赖仅当使用 JS/TS 时存在 └── README.md # 人类可读文档非协议必需但强烈建议这个结构本身就是一个强约束。bin/目录强制存在意味着技能必须提供明确的、可被execve调用的二进制或脚本manifest.json必须在根目录杜绝了“到底该读哪个 manifest”的歧义assets/独立存在让资源管理与逻辑分离。我见过最典型的错误就是开发者把整个技能打包成一个.zip解压后得到math-modeling-main/目录里面才是上述结构——CLI 扫描时找不到manifest.json直接跳过。正确做法是压缩包内直接是manifest.json而非嵌套一层。2.2manifest.json技能的身份证与服务契约这是协议的灵魂。math-modeling/manifest.json内容如下已脱敏保留全部必填字段{ name: math-modeling, version: 1.3.0, description: Solve differential equations and generate LaTeX SVG output, author: OpenSkills Collective, license: MIT, homepage: https://github.com/openskills/math-modeling, keywords: [math, latex, svg, ode], main: bin/solve.py, input: { mimeTypes: [text/plain, application/json], schema: { type: object, properties: { equation: {type: string}, initialConditions: {type: array, items: {type: number}} } } }, output: { mimeTypes: [text/latex, image/svgxml], schema: { type: object, properties: { latex: {type: string}, svg: {type: string} } } }, dependencies: { python: 3.9, system: [onnxruntime, sympy] }, capabilities: [cli, vscode, cursor], commands: [ { id: math-modeling.solve, title: Solve ODE System, description: Parse equation string and return LaTeX SVG, icon: calculator } ] }逐字段解析其协议意义name和version唯一标识。CLI 通过name查找技能version用于冲突检测如同时安装v1.2.0和v1.3.0后者覆盖前者。main绝对路径指向可执行入口。CLI 启动时会cd到技能根目录然后执行./bin/solve.py。注意它必须是相对路径且以./开头或不带前缀bin/solve.py不能是绝对路径/home/...。input.mimeTypes声明该技能能处理哪些 MIME 类型的输入。text/plain表示它能接收当前编辑器选中的纯文本application/json表示它也能接收结构化数据如从其他技能链式调用传入。CLI 在触发技能前会检查当前上下文选中文本、活动文件类型是否匹配。input.schemaJSON Schema 描述输入数据结构。当 CLI 通过 API 调用如codex api call math-modeling.solve时会校验传入 JSON 是否符合此 Schema。这是类型安全的关键。output.mimeTypes声明输出格式。text/latex表示结果可直接插入.tex文件image/svgxml表示结果可渲染为矢量图。VS Code 扩展据此决定是插入编辑器还是预览面板。dependencies声明运行时依赖。python: 3.9告诉 CLI 检查系统 Python 版本system: [onnxruntime]告诉 CLI 运行pip list | grep onnxruntime验证。若缺失CLI 会提示Missing dependency: onnxruntime而非抛出ModuleNotFoundError。capabilities声明支持的宿主环境。cli表示可通过命令行调用vscode表示可作为 VS Code 命令注册cursor表示可被 Cursor 的 Skills Panel 加载。一个技能可以只支持cli此时它在 IDE 里不可见。commands定义用户可见的命令。id是唯一动作标识供快捷键绑定title是命令面板显示名icon是 VS Code/Cursor 中显示的小图标。注意manifest.json中没有任何路径配置项。skillsDir是 CLI 的全局配置不是技能自身的属性。这意味着同一个math-modeling技能可以被codex cli、trae cli、zcode cli同时加载只要它们都遵循agent-skills协议——因为协议不绑定具体 CLI 实现。2.3bin/solve.py协议落地的最小可行执行单元这是技能的“肌肉”。math-modeling/bin/solve.py的核心逻辑简化版#!/usr/bin/env python3 import sys import json import sympy as sp from io import StringIO def main(): # 1. 从 stdin 读取输入协议强制所有输入通过 stdin try: input_data json.load(sys.stdin) except json.JSONDecodeError: # 2. 若 stdin 不是 JSON则当作纯文本处理兼容 text/plain MIME sys.stdin.seek(0) input_text sys.stdin.read().strip() if not input_text: print(json.dumps({error: Empty input}), end) return # 解析文本为方程此处省略复杂解析逻辑 equation_str input_text # ... 构建 sympy 表达式 else: # 3. 处理 JSON 输入符合 input.schema equation_str input_data.get(equation, ) ics input_data.get(initialConditions, []) # 4. 核心计算逻辑此处用 sympy 演示 try: x sp.Symbol(x) y sp.Function(y)(x) eq sp.Eq(sp.diff(y, x), sp.sin(x) * y) # 示例方程 sol sp.dsolve(eq, y) latex_str sp.latex(sol) # 5. 生成 SVG调用外部库此处简化 svg_content fsvg width200 height100.../svg # 6. 按协议输出 JSON协议强制所有输出通过 stdout result { latex: latex_str, svg: svg_content } print(json.dumps(result), end) # 关键end 避免换行污染 JSON except Exception as e: print(json.dumps({error: str(e)}), end) if __name__ __main__: main()这段代码体现了agent-skills协议的三个硬性约定输入统一走 stdin无论用户是通过 CLI 命令codex math-modeling.solve --input dy/dx sin(x)*y还是在 VS Code 里选中文本触发命令CLI 都会将输入字符串或 JSON写入solve.py的stdin。技能代码绝不应读取文件、环境变量或命令行参数sys.argv——那是 CLI 的职责。输出统一走 stdoutprint(json.dumps(...), end)是唯一允许的输出方式。CLI 会捕获stdout解析 JSON然后根据output.mimeTypes决定如何处理。如果技能打印了调试日志到stdout会导致 JSON 解析失败。零配置、零全局状态solve.py不读取任何配置文件如config.yaml不连接数据库不访问网络除非manifest.json明确声明network: true。它是一个纯粹的函数输入 → 计算 → 输出。这保证了技能的可移植性和可测试性。我实测过把math-modeling目录复制到另一台未装 Python 的机器codex skills list仍能显示它但执行时会报Missing dependency: python。这正是协议的价值——错误信息精准定位到缺失环节而非抛出晦涩的ImportError。3. CLI 运行时如何发现、加载与调度技能从npx codex skills install到命令执行理解agent-skills不能只看技能本身更要理解承载它的 CLI 运行时。以codex cli为例因其生态最成熟剖析一次codex math-modeling.solve命令的完整生命周期。这不是黑盒调用而是一系列可审计、可调试的步骤。3.1 技能发现扫描、过滤、索引的三步协议握手当你运行npx codex skills install math-modelingCLI 并非简单git clone。它执行以下协议化流程解析源地址math-modeling被解析为 GitHub 仓库https://github.com/openskills/math-modeling默认规则无时视为 GitHub Org/Repo有如math-modelingv1.3.0则指定 tag。下载与校验CLI 下载仓库 ZIP计算 SHA256 校验和与仓库releases/v1.3.0/checksums.txt中记录比对若存在。若校验失败拒绝安装——这是协议对供应链安全的最低要求。协议合规性扫描解压后CLI 遍历根目录检查是否存在manifest.json必选。检查manifest.json是否符合 JSON SchemaCLI 内置 schema。检查main字段指向的文件是否存在且可执行os.access(file, os.X_OK)。检查dependencies中声明的 Python 版本是否满足sys.version_info对比。若任一检查失败CLI 终止安装并输出具体错误如ERROR: manifest.json missing main field。成功后技能被解压到~/.codex/skills/math-modeling/。注意~/.codex/skills/是 CLI 的技能注册中心不是技能的“安装位置”而是协议规定的统一发现路径。3.2 运行时加载动态导入与能力注册CLI 启动时如codex --help执行技能加载扫描注册中心CLI 读取~/.codex/skills/下所有子目录。并行验证对每个子目录并行执行stat manifest.json确认存在。jq -r .name manifest.json提取技能名。chmod x ./bin/*确保可执行位Windows 下自动添加.bat包装器。构建能力索引将每个技能的manifest.json解析为内存对象存入skillsIndexMapconst skillsIndex new Mapstring, SkillManifest(); skillsIndex.set(math-modeling, { name: math-modeling, version: 1.3.0, commands: [{ id: math-modeling.solve, title: Solve ODE System }], // ... 其他字段 });注册命令遍历skillsIndex为每个command.id注册 CLI 子命令。math-modeling.solve变成codex math-modeling.solve的可执行命令。这个过程是静态的、声明式的。CLI 不会运行solve.py只是读取其manifest.json。这意味着技能即使有严重 bug只要manifest.json合规就能被发现和列出。codex skills list输出的是协议层面的“能力清单”而非运行时的“可用功能清单”。3.3 命令调度输入适配、进程派生、输出解析的精密流水线当你在终端输入codex math-modeling.solve --input dy/dx yCLI 执行命令路由CLI 解析math-modeling.solve查skillsIndex得到对应技能路径~/.codex/skills/math-modeling/和main: bin/solve.py。输入适配--input参数值dy/dx y被序列化为 JSON{ equation: dy/dx y }因manifest.json中input.mimeTypes包含application/json。CLI 启动子进程cd ~/.codex/skills/math-modeling ./bin/solve.py。将 JSON 字符串写入子进程stdin。进程派生与监控CLI 使用spawn创建子进程设置超时默认 30s。捕获子进程stdout和stderr。若子进程stderr有输出CLI 将其作为警告日志不影响主流程。输出解析与路由CLI 读取子进程stdout尝试JSON.parse()。成功后检查返回 JSON 是否符合manifest.json中output.schema。根据output.mimeTypesCLI 决定输出方式若text/latex则直接console.log(result.latex)。若image/svgxml则保存到临时文件并打开浏览器预览CLI 默认行为。若stdout不是有效 JSONCLI 报错Invalid output: expected JSON, got plain text。这个流水线的关键在于解耦CLI 负责输入/输出适配、进程管理、错误包装技能只负责核心计算。你可以用 Bash 重写solve.py只要manifest.json不变CLI 调用方式完全一致。我曾用awk实现一个极简的text-to-uppercase技能manifest.json声明input.mimeTypes: [text/plain]output.mimeTypes: [text/plain]CLI 调用codex text-to-uppercase --input hello完美工作——证明协议的普适性。提示调试技能时不要直接运行./bin/solve.py。正确方式是echo {equation:dy/dxy} | ~/.codex/skills/math-modeling/bin/solve.py。这模拟了 CLI 的真实调用方式能暴露stdin处理问题。4. 开发者实战从零创建一个latex-render技能并接入 VS Code现在我们亲手创建一个网络热词中高频提及的latex-render技能——它接收 LaTeX 代码返回编译后的 PDF 或 SVG。这不仅是教程更是对agent-skills协议的深度实践。我会暴露所有踩过的坑包括 Windows 路径、权限、编码等真实问题。4.1 初始化项目协议先行结构即契约创建目录latex-render严格按协议建立结构mkdir latex-render cd latex-render touch manifest.json mkdir bin assets # 创建空的 Python 脚本后续填充 touch bin/render.py # 创建空的 LaTeX 模板后续填充 touch assets/template.tex现在编写manifest.json。这是最关键的一步决定了技能能否被识别{ name: latex-render, version: 0.1.0, description: Compile LaTeX source to PDF or SVG, author: Your Name, license: MIT, homepage: https://github.com/yourname/latex-render, keywords: [latex, pdf, svg, render], main: bin/render.py, input: { mimeTypes: [text/x-latex], schema: { type: object, properties: { source: {type: string}, format: {type: string, enum: [pdf, svg]} } } }, output: { mimeTypes: [application/pdf, image/svgxml], schema: { type: object, properties: { binary: {type: string, description: Base64 encoded binary data}, mimeType: {type: string} } } }, dependencies: { system: [pdflatex, dvisvgm] }, capabilities: [cli, vscode], commands: [ { id: latex-render.compile, title: Render LaTeX to PDF/SVG, description: Compile current LaTeX selection, icon: file-code } ] }关键点解析input.mimeTypes: [text/x-latex]明确告诉 CLI此技能只处理.tex文件或选中的 LaTeX 文本。output.schema中binary字段为 Base64 字符串这是协议对二进制输出PDF/SVG的约定。CLI 会自动解码 Base64 并写入文件或预览。dependencies.system: [pdflatex, dvisvgm]声明系统级依赖。CLI 会检查which pdflatex和which dvisvgm。4.2 实现bin/render.py处理 Windows、编码、临时文件的魔鬼细节latex-render/bin/render.py是核心。以下是经过 Windows/macOS/Linux 三端实测的版本Python 3.8#!/usr/bin/env python3 import sys import json import os import tempfile import subprocess import base64 from pathlib import Path def main(): # 1. 读取 stdin 输入协议强制 try: input_data json.load(sys.stdin) except json.JSONDecodeError: # 2. 兼容纯文本输入如 VS Code 选中文本 sys.stdin.seek(0) input_text sys.stdin.read().strip() if not input_text: print(json.dumps({error: Empty input}), end) return input_data {source: input_text, format: pdf} source input_data.get(source, ) fmt input_data.get(format, pdf).lower() if not source: print(json.dumps({error: No LaTeX source provided}), end) return # 3. 创建临时工作目录解决 Windows 权限和路径问题 # 使用 tempfile.mkdtemp() 而非 os.getcwd()避免权限错误 with tempfile.TemporaryDirectory() as tmp_dir: tmp_path Path(tmp_dir) tex_file tmp_path / input.tex aux_file tmp_path / input.aux log_file tmp_path / input.log # 4. 写入 LaTeX 源码关键指定 encodingutf-8否则 Windows 中文乱码 try: tex_file.write_text(source, encodingutf-8) except UnicodeEncodeError as e: print(json.dumps({error: fEncoding error: {e}}), end) return # 5. 构建 pdflatex 命令关键cwd 设置为 tmp_path避免路径问题 cmd_pdf [pdflatex, -interactionnonstopmode, -halt-on-error, input.tex] try: # 6. 执行 pdflatex捕获 stderr 用于调试 result_pdf subprocess.run( cmd_pdf, cwdtmp_path, capture_outputTrue, timeout60, encodingutf-8 # 关键确保 stderr 输出可解码 ) except subprocess.TimeoutExpired: print(json.dumps({error: Compilation timeout}), end) return except FileNotFoundError: print(json.dumps({error: pdflatex not found. Install TeX Live.}), end) return if result_pdf.returncode ! 0: # 7. 错误处理返回详细的 log 信息CLI 会显示 error_msg result_pdf.stderr[:500] (... if len(result_pdf.stderr) 500 else ) print(json.dumps({error: fpdflatex failed: {error_msg}}), end) return # 8. 根据 format 生成对应输出 if fmt pdf: pdf_file tmp_path / input.pdf if not pdf_file.exists(): print(json.dumps({error: PDF file not generated}), end) return # 9. 读取 PDF 并 Base64 编码协议要求 with open(pdf_file, rb) as f: binary_data base64.b64encode(f.read()).decode(utf-8) print(json.dumps({ binary: binary_data, mimeType: application/pdf }), end) elif fmt svg: # 10. 生成 DVI再转 SVGdvisvgm dvi_file tmp_path / input.dvi cmd_dvi [pdflatex, -output-formatdvi, input.tex] result_dvi subprocess.run(cmd_dvi, cwdtmp_path, capture_outputTrue, timeout30) if result_dvi.returncode ! 0: print(json.dumps({error: DVI generation failed}), end) return cmd_svg [dvisvgm, --no-fonts, input.dvi] result_svg subprocess.run(cmd_svg, cwdtmp_path, capture_outputTrue, timeout30, encodingutf-8) if result_svg.returncode ! 0: print(json.dumps({error: fdvisvgm failed: {result_svg.stderr[:200]}}), end) return svg_file tmp_path / input.svg if not svg_file.exists(): print(json.dumps({error: SVG file not generated}), end) return # 11. 读取 SVG 并 Base64 编码 with open(svg_file, r, encodingutf-8) as f: svg_content f.read() print(json.dumps({ binary: base64.b64encode(svg_content.encode(utf-8)).decode(utf-8), mimeType: image/svgxml }), end) else: print(json.dumps({error: fUnsupported format: {fmt}}), end) if __name__ __main__: main()这个脚本解决了agent-skills开发中最常见的五个坑Windows 权限坑tempfile.TemporaryDirectory()自动创建具有写权限的临时目录避免PermissionError。编码坑write_text(..., encodingutf-8)和subprocess.run(..., encodingutf-8)强制 UTF-8解决中文 LaTeX 源码在 Windows 上的乱码。路径坑cwdtmp_path确保pdflatex在正确目录下运行避免input.tex not found。二进制输出坑PDF 用rb模式读取SVG 用r模式读取分别 Base64 编码严格符合output.schema。错误反馈坑result_pdf.stderr[:500]截断长日志防止 JSON 输出过大错误信息结构化CLI 可直接展示。4.3 本地测试与 CLI 集成验证协议闭环在latex-render目录外测试技能# 1. 手动测试模拟 CLI 调用 echo {source:\\documentclass{article}\\begin{document}Hello World\\end{document},format:pdf} | python bin/render.py # 2. 安装到 CLI假设 codex cli 已全局安装 npx codex skills install . # 3. 列出技能确认出现 npx codex skills list | grep latex-render # 4. 执行命令 npx codex latex-render.compile --input \\documentclass{article}\\begin{document}Test\\end{document} --format pdf若第 4 步成功CLI 会输出 Base64 字符串。你可以用在线工具解码或 CLI 自动保存为output.pdf。4.4 接入 VS Code让技能在编辑器中一键触发要让latex-render出现在 VS Code 命令面板只需两步确保capabilities包含vscode已在manifest.json中设置。在 VS Code 中安装Codex或Claude Code扩展它们内置agent-skills运行时。然后打开一个.tex文件。CtrlShiftP打开命令面板。输入 Render LaTeX选择latex-render.compile。扩展会自动获取当前文件内容或选中文本调用 CLI将输出 PDF 保存到同目录或预览。注意VS Code 扩展不会重新安装技能它直接读取~/.codex/skills/。所以npx codex skills install .是必要前提。我曾因忘记这一步在 VS Code 里死活看不到命令浪费半小时排查扩展设置。5. 生态现状与避坑指南为什么unable to locate the codex cli binary是高频报错agent-skills生态正处在爆发前夜但也充满混乱。网络热词中unable to locate the codex cli binary or required skills高频出现这不是偶然而是协议落地过程中必然经历的阵痛。理解这些痛点比学会写一个技能更重要。5.1 技能市场碎片化GitHub 仓库 vs. NPM 包 vs. 私有 Registry目前agent-skills技能分发有三种主流方式各有优劣分发方式代表案例优点缺点典型报错GitHub 仓库直连npx codex skills install awesome-claude-skills/math-modeling透明、可审计、版本控制好需要 Git网络不稳定时失败Error: Command failed: git clone ...NPM 包发布npm install openskills/math-modeling利用 npm 生态依赖自动解决技能被包裹在node_modulesCLI 需特殊路径解析unable to locate ... in node_modules私有 Registry企业内部skills.mycompany.com安全、可控、支持审计需额外部署 Registry 服务Registry not found: skills.mycompany.comunable to locate the codex cli binary报错90% 源于NPM 方式与 CLI 的路径解析冲突。例如deveco cli设计为从node_modules/.bin/查找codex但codex cli本身可能被全局安装/usr/local/bin/codex而技能又通过npm install安装在项目node_modules下。CLI 启动时process.env.PATH优先找到项目node_modules/.bin但该目录下没有codex导致execve失败。解决方案始终使用npx调用 CLI。npx codex skills install ...会自动解析node_modules/.bin/codex如果存在或全局codex避免 PATH 混乱。不要npm install -g codex后再codex skills install这是最易出错的组合。5.2 Windows 特殊坑权限、路径、换行符的三重绞杀Windows 是agent-skills开发者的噩梦但并非不可逾越权限坑npx codex skills install在 PowerShell 中常因执行策略被阻止。解决Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。路径坑~/.codex/skills/在 Windows 是 C:\Users\Username
