★ FEATURED ARTICLE 1. “agent-skills”不是功能模块而是一套可插拔的能力交付协议你第一次在 GitHub 仓库名、CLI 工具参数、API 文档标题里看到agent-skills这个词时大概率会下意识把它当成一个“技能集合”或“插件包”——就像 npm 上的lodash或axios那样装完就能用。但实际踩进去才发现它根本不是库也不是 SDK更不是某个大模型厂商推出的官方能力市场。它是一套轻量级、面向 CLI 场景、以 slash command 为交互契约、由 runtime 主动发现并加载的可执行能力协议。关键词里反复出现的CLI、slash commands、API不是并列关系而是层级关系CLI 是载体slash command 是入口语法API 是底层能力实现方式。而skills这个词在这里特指符合特定结构约束、能被 agent runtime 解析并安全执行的最小可调度单元。我最早是在一个内部工具链项目里接触到这个概念的。当时团队想让前端工程师也能快速接入后端服务又不想让他们写完整 HTTP 请求逻辑。于是我们约定所有新能力必须以/xxx形式暴露比如/git-status、/db-query、/log-tail每个命令背后对应一个独立的 shell 脚本或 Node.js 模块且必须声明输入 schemaJSON Schema、输出格式text/json、权限范围read-only / write / network、超时阈值默认 3s。这套约定跑通后我们把它抽象成一个通用 CLI 工具取名zcode cli——注意不是zcode-cli中间没有连字符因为它是“zcode”这个 runtime 的命令行界面不是独立项目。后来发现codex cli、boos cli、trae cli其实都在复用同一套底层协议只是 runtime 实现不同。它们共享的核心特征是不依赖中心化注册中心不强制使用特定语言不绑定某家大模型 API甚至不强制联网——一个/weatherskill 完全可以只读本地 JSON 文件返回城市天气。这解释了为什么搜索热词里频繁出现claude agent skills: a first principles deep dive和reasonix如何安装新skills前者在讲协议设计哲学为什么选 slash 命令而非 REST endpoint为什么 schema 必须前置声明后者在解决具体落地问题怎么把一个 Python 脚本变成可被 CLI 自动识别的 skill。而那些报错信息比如llm-deepseek: no api key for provider route deepseek-official本质不是 API 密钥缺失而是 skill 配置中provider字段写成了deepseek-official但当前 runtime 并未加载该 provider 插件——它压根不认识这个字符串。同理permission denied while trying to connect to the docker api看似是 Docker 权限问题实则是/docker-ps这个 skill 在 manifest 中声明了scope: [docker:socket]但 CLI 启动时没加--allow-docker-socket参数runtime 主动拦截了调用。提示判断一个工具是否真正支持agent-skills协议不要看它有没有“技能市场”按钮而要看它是否允许你通过--skill-path指定本地目录并自动扫描其中符合skill.json exec结构的文件。这是协议落地的最低门槛。2. Slash Command 是协议的语法糖不是 UI 设计选择很多人把/help、/ls、/curl这类命令理解为“为了模仿 Slack 或 Discord 的交互习惯”这是典型误解。Slash command 在agent-skills体系里承担的是结构化解析锚点和权限隔离边界双重角色。它不是为了让用户觉得亲切而是为了让 runtime 能无歧义地拆解输入流。举个真实例子用户输入/git-log --since2024-01-01 --oneline。如果不用/开头runtime 就得面对一个经典难题git-log是命令名还是参数--since是全局选项还是 git-log 特有选项当多个 skill 都支持--format参数时如何避免冲突而一旦强制以/开头解析逻辑就变得极其简单找到第一个/截取后续连续非空格字符作为 skill name这里是git-log剩余部分整体作为 raw args 传入由 skill 自己解析git-log内部用yargs或argparse处理runtime 完全不参与参数语义理解只做路由分发。这带来三个关键收益第一skill 开发者可以完全复用现有 CLI 工具的参数解析逻辑无需适配新框架第二用户学习成本归零——你本来就会用curl -X POST现在只需写/curl -X POST第三也是最重要的一点权限控制粒度可精确到 command 级别。比如/db-query可以申请database:read权限/db-migrate则需要database:write而/http-get只需network:outbound。这些权限在 skill manifest 中声明runtime 启动时统一校验执行前动态检查。没有/作为语法锚点这种细粒度控制根本无法实现。再看热词里高频出现的codex cli 命令哪些 /compact /model /resume。这三个命令表面看是功能分类实则对应三类不同安全等级的 skill/compact纯本地计算无 IO权限标记为scope: []可无条件执行/model调用本地或远程 LLM需声明scope: [llm:inference]runtime 会检查是否配置了合法 provider/resume读取用户简历 PDF 并结构化需scope: [file:read, llm:inference]且要求文件路径在白名单内。注意/后面不能有空格/ git-log是非法输入。这不是 UX 规范而是 parser 的硬性要求——空格是参数分隔符/必须紧贴 command name。我在早期版本里放过这个限制结果导致/http get被解析成/httpget而get被当作独立 skill 查找报错skill get not found用户完全无法理解。3. Skill Manifest 是能力描述的唯一真相源不是可选配置所有agent-skills相关工具zcode cli、codex cli、boos cli启动时第一件事就是扫描指定目录下的skill.json文件。这个文件不是“配置文件”而是skill 的机器可读身份证。它必须包含且仅包含 runtime 要求的字段少一个就拒绝加载多一个就忽略除非是 vendor 扩展字段。热词里反复出现的skills开发、skills安装包下载、github skills核心矛盾都源于对 manifest 结构的理解偏差。标准 manifest 至少包含以下 7 个字段按重要性排序字段名类型必填说明实例namestring✓skill 唯一标识也是 slash command 名称git-statusversionstring✓语义化版本号用于冲突检测1.2.0execstring✓可执行文件路径相对 skill.json 所在目录./bin/git-status.shschemaobject✓输入参数 JSON Schemaruntime 用它做预校验{ type: object, properties: { branch: { type: string } } }outputstring✓输出格式text/json/markdownjsonscopearray✓所需权限列表空数组表示无特权[git:repo, file:read]timeoutnumber✓最大执行时间毫秒超时强制 kill5000我见过最典型的错误是把exec写成绝对路径如/usr/local/bin/git-status。这会导致 skill 在其他机器上失效——因为 runtime 加载时是以skill.json为基准目录解析exec的。正确做法是把可执行文件放在 skill 目录下用相对路径引用。另一个高频坑是schema字段写得太宽松{ type: object }看似没问题但 runtime 无法做任何参数校验用户输/git-status --invalid-flag时错误要等到脚本执行时才暴露体验极差。最佳实践是 copy-paste 对应 CLI 工具的--help输出用 json-schema-generator 自动生成严格 schema。热词里choosemedia:fail api scope is not declared in the privacy agreement这个报错根源就在scope字段缺失或拼写错误。choosemedia这个 skill 需要访问摄像头按协议必须声明scope: [media:camera]但开发者漏写了或者写成了media:cam大小写敏感。runtime 在启动时扫描到该 skill发现scope不合法直接跳过加载后续调用自然失败。这不是 API 侧的问题而是 manifest 本身不合格。提示manifest 中version字段不仅用于升级管理更是 runtime 决定是否缓存 skill 的依据。同一个nameversion变了runtime 就会重新下载、校验、加载。所以千万别用0.0.0或dev这种占位符否则每次启动都重新拉取拖慢 CLI 响应。4. Runtime 是协议的守门人不是执行引擎agent-skills体系里最容易被低估的角色是那个默默运行的 CLI runtime。它不负责写业务逻辑不处理 LLM 调用不管理 Docker 容器——它只做三件事发现 skill、校验 manifest、管控执行环境。热词中大量报错minimax cli、permission denied while trying to connect to the docker api、api error: 400 this models maximum context length is 1048576 tokens表面看是 skill 或 API 的问题实则 80% 源于 runtime 配置不当。以permission denied while trying to connect to the docker api为例。用户执行/docker-ps时失败第一反应是“Docker daemon 没启动”或“用户没加 docker 组”。但真正原因往往是runtime 启动时没加--allow-docker-socket参数。这个参数的作用是告诉 runtime“我允许 skill 访问/var/run/docker.sock这个 Unix socket”。没有它runtime 会在进程启动前主动移除exec进程对/var/run/docker.sock的文件描述符继承权限——哪怕 skill 脚本里写了curl --unix-socket /var/run/docker.sock http://localhost/containers/json也会在系统调用层面被拒绝。这是 capability-based security 的典型应用比 Linux group 权限更细粒度。再看api error: 400 this models maximum context length is 1048576 tokens。用户以为是 DeepSeek API 限制其实 runtime 在调用前会根据 skill manifest 中的context_length字段如果声明了和用户输入长度做本地预检。如果预检发现超限根本不会发请求直接返回友好错误。但很多 skill 开发者没填这个字段runtime 就只能放行结果 API 侧报错。解决方案不是改 API 调用逻辑而是在 manifest 中补上context_length: 1048576, max_input_tokens: 8192zcode cli和codex cli的核心差异就在于 runtime 的管控策略不同zcode cli默认禁用所有网络必须显式声明--allow-network才能访问外网codex cli默认允许localhost和127.0.0.1但禁止公网域名需--allow-domain example.com显式授权boos cli则采用白名单模式所有网络请求必须匹配network:whitelist中的正则表达式。这意味着同一个/http-getskill在三个 runtime 上行为可能完全不同。不是 skill 本身有问题而是 runtime 的沙箱规则不同。这也是为什么热词里总有人问codex cli安装和node安装codex cli很慢——codex cli的 runtime 依赖较多尤其是booster/network包而zcode cli是纯 Go 编译的二进制启动快 3 倍。注意runtime 的--debug模式会打印每一步决策日志比如INFO loading skill /git-status from /path/to/skills/git-status/skill.json、WARN skill /git-status declares scope [git:repo] but --allow-git-repo not set, skipping。这是排查问题的第一手资料比看 skill 脚本日志有效得多。5. 技能分发不是上传到市场而是发布到可寻址的 Git 仓库agent-skills生态里没有中心化应用商店。热词中skills下载平台有哪些、skills推荐、claude 国内安装skills 官方市场这些搜索反映的是用户对分发机制的误解。真正的分发方式是把 skill 目录推送到公开 Git 仓库然后用cli install git-url命令克隆到本地。github skills这个热词说的就是这个动作。例如一个高质量的/weatherskill其 GitHub 仓库结构应该是weather-skill/ ├── skill.json ├── bin/ │ └── weather.sh ├── README.md └── tests/ └── test.sh其中skill.json的name字段必须是weather这样用户执行zcode install https://github.com/username/weather-skill后就能直接用/weather --city beijing。这种分发方式带来三个关键优势第一溯源可信——用户能看到完整源码、commit history、issue 讨论比二进制下载包安全得多第二版本可控——zcode install https://github.com/username/weather-skill#v1.2.0可精确指定 tag第三离线可用——Git 仓库 clone 下来就是完整 skill不依赖任何在线服务。但这也带来了新问题如何保证不同仓库里的 skill 不冲突答案是namespace 机制。zcode cli支持--namespace参数比如zcode --namespace myorg install https://github.com/myorg/internal-tools。安装后所有 skill 自动加上前缀/myorg/db-query、/myorg/log-tail。这样即使两个仓库都有/db-query也不会覆盖。热词里find skills这个需求目前没有官方解决方案。社区自发形成了两种实践方案一维护一个awesome-agent-skills的 GitHub Topic所有 skill 仓库打上agent-skills标签用 GitHub 搜索topic:agent-skills方案二用zcode search命令需提前配置 registry URL它会定期抓取指定仓库的skill.json列表生成本地索引。最值得警惕的是skills安装包下载这类搜索。任何提供.zip或.tar.gz下载包的网站都违背了协议精神——你无法验证它的 Git commit hash无法审计源码无法追踪更新。我亲眼见过一个所谓“超稳-q绑在线查询api”的 skill 包解压后发现exec脚本里硬编码了第三方 API key并偷偷上传用户数据到不明服务器。真正的agent-skills永远从 Git 仓库来。提示zcode install默认会校验 Git 仓库的 GPG 签名如果作者配置了。开启--require-signature参数后未签名的 commit 将被拒绝安装。这是保障供应链安全的最后一道防线。6. Agent-Skills 的真实价值让非程序员也能安全复用专业能力最后说点掏心窝的话。agent-skills协议最打动我的地方不是技术多炫酷而是它把“能力复用”的门槛降到了前所未有的低。热词里今天学会了skills、打开新世界、前端开发skills这些朴素表达恰恰戳中了本质。我带过一个产品团队成员包括产品经理、UI 设计师、测试工程师。他们不需要写代码但需要频繁查数据库、看线上日志、跑 A/B 测试报告。以前他们要么等后端同事帮忙要么学 SQL 和 Kibana。引入agent-skills后我们做了三件事把常用 SQL 查询封装成/db-queryskillmanifest 中schema严格限定只允许SELECT语句scope设为[database:read]把日志检索封装成/log-search输入参数只有service和keywords后端用 Loki API 实现把 A/B 报告生成封装成/ab-report输入是实验 ID输出是 Markdown 表格。所有 skill 都托管在公司内网 GitLab用zcode --namespace product install https://gitlab.internal/product/skills一键安装。产品经理现在能自己查数据设计师能实时看用户行为日志测试工程师能一键生成回归报告。他们不需要知道 SQL 怎么写不需要懂 Loki 查询语法甚至不需要知道背后调用了什么 API——他们只记住/db-query --table users --where statusactive这样的命令。这就是agent-skills的终极价值它不创造新能力而是把已有的、分散的、专业的、危险的能力用一套轻量协议包装起来让非专业人士能在受控范围内安全调用。那些热词里反复出现的free api、免费大模型api、超稳-q绑在线查询api本质上都是在寻找“开箱即用的能力”而agent-skills提供的是让这些能力真正可信赖、可审计、可组合的基础设施。我在实际使用中发现最大的阻力从来不是技术而是组织惯性。当一个 skill 被证明好用大家会自然形成新的协作语言“你/db-query一下这个用户”“帮我/ab-report这个实验”。这种基于 slash command 的协作比邮件、IM、文档都更精准、更可追溯、更难出错。它让能力流动像呼吸一样自然而这正是所有技术人梦寐以求的终局。
阅读完成 · 觉得有帮助？
