agent-skills：可复用CLI技能的声明式设计与工程实践

1. 项目概述什么是 agent-skills它不是玩具而是开发者工作流的“肌肉记忆加速器”“agent-skills”这个词最近在前端、AI工程和CLI工具圈里反复刷屏但它既不是某个新出的框架也不是某家大厂刚发布的闭源产品——它是一类可复用、可组合、可声明式调用的原子化能力单元。简单说就像你手机里装的微信、地图、相机这些独立App但它们不跑在图形界面上而是跑在命令行里、跑在AI Agent的决策链路中、跑在自动化脚本的底层逻辑里。你敲npx skills list它返回一串可用技能你写npx skills git commit --messagefeat: add auth middleware它就自动执行 git 提交你配置claude agent skills: a first principles deep dive这样的提示词背后调用的正是经过标准化封装的git,curl,playwright,docker等真实 CLI 工具能力。它解决的核心问题非常朴素让开发者不再重复写 shell 脚本、不再手敲 8 行 curl 命令查 API、不再为每个新项目重写一遍“读取 env → 校验 token → 发请求 → 解析 JSON → 输出表格”的胶水代码。我从 2021 年开始在团队内部推动 CLI 工具链标准化最早是用yarn create封装项目模板后来用oclif写过一整套 DevOps 指令集直到去年看到 Codex CLI 和 Zcode CLI 的设计思路才真正意识到我们缺的不是更多命令而是一套能让命令“自我描述、自我注册、自我发现”的基础设施。agent-skills 正是这个基础设施的实践出口——它把git status变成一个可被 AI 理解的skills.git.status()函数把npx playwright install变成一个带依赖图谱和失败回退策略的skills.playwright.install()方法。它不替代 npm 或 yarn但让npx从“临时跑个包”升级为“按需加载能力”。对新手它是降低 CLI 使用门槛的阶梯对资深工程师它是把十年经验沉淀为可移植、可审计、可版本化的技能资产。你不需要懂 LLM 推理也能用skills find --categorytesting找到最适合当前项目的 E2E 测试工具链你不需要会写 TypeScript 类型定义也能通过skills compact --inputpackage.json自动生成精简版依赖清单。它不是魔法是把“人怎么干活”这件事用机器可读的方式重新刻录了一遍。2. 整体设计与思路拆解为什么 agent-skills 必须是“轻注册、重契约、零侵入”agent-skills 的设计哲学本质上是对过去十年 CLI 工具生态痛点的一次系统性回应。我们先看三个典型失败场景第一种是“全家桶式 CLI”比如早期的create-react-app它把 webpack、babel、eslint 全打包进一个二进制结果升级困难、定制受限、调试黑盒第二种是“插件地狱”像某些 IDE 的 CLI 扩展每个插件都要自己处理命令冲突、参数解析、错误格式化最终用户面对的是--verbose --debug --trace --log-leveldebug --enable-tracing这种参数爆炸第三种是“AI 胶水层”即用 LLM 把自然语言转成 shell 命令看似智能实则脆弱——“帮我部署到 staging”可能生成rm -rf / scp ...缺乏能力边界的硬约束。agent-skills 的破局点就在于它彻底放弃了“统一运行时”或“中心化调度器”的幻想转而构建一套基于契约Contract而非控制Control的协作协议。它的核心架构只有三层最底层是Skill Definition技能定义一个纯 JSON 文件必须包含id,name,description,command,args,outputSchema,requires六个字段。注意这里没有“入口函数”没有“生命周期钩子”没有“上下文对象”——它就是一个声明式说明书。比如skills.git.commit的定义里command是git commitargs是[{name:message,type:string,required:true},{name:amend,type:boolean,default:false}]outputSchema是{type:object,properties:{commitHash:{type:string},filesChanged:{type:number}}}。第二层是Skill Registry技能注册表它不是数据库而是一个可被npx直接拉取的 GitHub 仓库如github:skills-registry/core所有技能定义都以.skill.json文件形式存在按 category 分目录存放。第三层是Skill Runtime技能运行时这才是真正的“胶水”——它只做三件事校验输入参数是否符合args描述、拼接出合法 shell 命令、解析 stdout/stderr 是否匹配outputSchema。整个过程不修改用户环境变量不注入全局变量不 patch 任何原生命令完全零侵入。这种设计带来的实际好处极其实在。举个例子当npx playwright install失败时传统做法是让用户查文档、翻 issue、手动删 node_modules、重装 Chromium。而 agent-skills 的skills.playwright.install在定义里明确写了requires: [node18.0.0, python3]运行时会先执行node --version和python3 --version校验失败直接报错“Python 3 未安装”而不是等到 playwright 自己崩溃才吐出 200 行 traceback。再比如skills.find命令它不自己实现搜索逻辑而是调用gh api search/code?qrepo:skills-registryfilename:.skill.json把 GitHub 的搜索能力直接变成自己的技能。这解释了为什么热词里反复出现cli anything wps和superpower skills——它不是给 CLI 加功能而是让 CLI 成为调用一切能力的统一入口。我实测过在一个空文件夹里执行npx skills init --templatenextjs它会自动检测本地是否有 pnpm有则用pnpm create next-app没有则 fallback 到npx create-next-app整个过程无需用户干预因为skills.init的定义里包含了多引擎适配策略。这种“契约驱动”的设计让技能开发变得像写 Markdown 一样简单也让技能消费变得像查字典一样可靠。3. 核心细节解析与实操要点从零写出第一个可被 npx 调用的 agent-skill要真正理解 agent-skills 的运作机制最好的方式不是读文档而是亲手写一个最小可行技能MVP Skill。我们以skills.date.now为例——它应该返回当前时间戳和格式化日期且必须满足 agent-skills 的全部契约要求。整个过程分四步定义、验证、发布、消费每一步都有容易踩坑的关键细节。3.1 技能定义JSON 不是随便写的schema 是硬性门槛新建一个文件date.now.skill.json内容如下{ id: date.now, name: Get current timestamp and formatted date, description: Returns Unix timestamp and ISO 8601 formatted date string, command: date, args: [ { name: format, type: string, default: %s %Y-%m-%d %H:%M:%S, description: strftime format string } ], outputSchema: { type: object, properties: { timestamp: { type: number }, formatted: { type: string } }, required: [timestamp, formatted] }, requires: [] }注意三个易错点第一command字段必须是可被 shell 直接执行的命令名不能带路径如/bin/date也不能带参数参数必须严格定义在args里第二outputSchema必须是标准 JSON Schema v7且required数组不能为空——这是运行时做输出校验的依据第三args中的default值必须是字符串类型即使你期望传数字也要写成1000因为 CLI 参数本质都是字符串类型转换由运行时完成。我最初写skills.docker.run时把--memory的default设为512数字结果运行时报错expected string for arg memory花了半小时才定位到这个隐性规则。3.2 本地验证别急着 publish先用 runtime 模拟真实调用agent-skills 官方提供了一个轻量级验证工具skills/cli安装后即可本地测试npm install -g skills/cli skills validate ./date.now.skill.json这个命令会检查 JSON 结构合法性、schema 有效性、command 是否存在于 PATH。但更重要的是模拟执行skills run ./date.now.skill.json --format%s %a %b %d它会启动一个沙箱环境执行date %s %a %b %d捕获 stdout然后用outputSchema验证输出是否匹配。如果输出是1717023456 Tue May 28而 schema 要求{timestamp:1717023456,formatted:Tue May 28}就会失败——因为date命令的 stdout 是单行字符串不是 JSON 对象。这就引出了 agent-skills 最关键的设计约定所有技能的 stdout 必须是 JSON 格式。所以真正的date.now.skill.json的command应该是command: sh -c echo \{\\\timestamp\\\:$(date %s),\\\formatted\\\:\\\$(date)\\\}\这个细节决定了技能能否被其他技能组合调用。比如skills.git.log可能需要skills.date.now的 timestamp 做时间范围过滤如果输出不是 JSON上游就无法解析。我在写skills.curl.get时也栽过跟头原以为curl -s https://api.example.com返回 JSON 就够了结果发现有些 API 返回的是text/plain运行时校验失败。解决方案是在command里强制用jq或python -m json.tool做格式归一化。3.3 发布到 registryGitHub 是你的 CDN不是你的 Git 服务器agent-skills 的 registry 本质是一个 GitHub 仓库结构固定为skills-registry/ ├── core/ │ ├── date.now.skill.json │ └── git.commit.skill.json ├── testing/ │ └── playwright.install.skill.json └── README.md发布流程就是一次标准的 GitHub PRFork 官方 registry 仓库 → 在对应 category 目录下新增.skill.json文件 → 提交 PR → 维护者审核主要检查 command 安全性、schema 合理性、description 准确性→ 合并后自动触发 CI 构建索引。这里有个重要技巧不要在 skill 定义里写绝对路径或敏感信息。比如skills.aws.deploy如果写command: aws s3 cp ./dist s3://my-bucket就违反了零侵入原则——它假设用户已配置 AWS 凭据且 bucket 名硬编码。正确做法是把 bucket 作为args参数让使用者显式传入npx skills aws deploy --bucketmy-prod-bucket。我见过一个 PR 被拒三次就因为skills.npm.publish的定义里包含了command: npm publish --registryhttps://private-registry.com维护者坚持要求改为registry参数动态传入。3.4 消费技能npx 不是万能钥匙你需要理解它的缓存机制当技能发布成功后用户就能用npx skills date.now调用了。但这里有个性能陷阱npx默认每次都会重新下载 registry 索引约 2MB导致首次调用慢达 3-5 秒。解决方案有两个一是用npx skillslatest date.now --offline强制离线模式需提前npx skills cache update二是全局安装skills/cli它会自动维护本地 registry 缓存。更关键的是参数传递逻辑npx skills date.now --format%Y-%m-%d中的--format会被 runtime 解析为args中的format字段但如果你写成npx skills date.now -f %Y-%m-%d就会报错Unknown argument: -f——因为 agent-skills只支持长参数--xxx不兼容短参数-x这是为了保证参数名的可读性和 schema 映射的确定性。我在教团队新人时专门做了个对比实验用skills.find --categorydevops查到skills.docker.prune然后直接npx skills docker prune --force结果失败原因是prune技能定义里args的 name 是all而不是force正确命令是npx skills docker prune --all。这个细节说明技能消费不是盲打命令而是阅读契约。4. 实操过程与核心环节实现搭建属于你团队的私有 skills registry公开 registry 解决通用需求但企业级场景必然需要私有化部署。我去年帮一家金融科技公司落地 agent-skills他们有严格的合规要求所有 CLI 工具必须经过安全扫描、所有网络请求必须走代理、所有技能执行必须记录审计日志。整个私有 registry 的搭建核心就三件事镜像同步、权限控制、审计集成。4.1 镜像同步用 GitHub Actions 实现分钟级更新不是简单 fork私有 registry 不能只是 fork 公开仓库必须建立自动同步机制。我们在 GitHub 上创建了internal-skills-registry仓库并配置了以下 Actions 工作流name: Sync from upstream on: schedule: - cron: */30 * * * * # 每30分钟检查一次 workflow_dispatch: jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: token: ${{ secrets.PAT }} # 个人访问令牌有写权限 - name: Fetch upstream run: | git clone https://github.com/skills-registry/core.git upstream cd upstream git checkout main cd .. - name: Copy new files run: | rsync -av --delete upstream/core/ ./core/ --exclude*.md - name: Commit changes run: | git config --local user.email actiongithub.com git config --local user.name GitHub Action git add . git commit -m sync: update core skills from upstream $(date) || echo no changes git push关键点在于rsync --delete它确保私有仓库与上游保持精确一致删除上游已移除的技能避免僵尸技能残留。同时我们禁用了所有.md文件的同步因为私有 registry 不需要文档只保留.skill.json。这个方案比手动维护节省了 90% 的运维时间而且每次同步都有 commit 记录满足审计要求。值得一提的是skills.playwright.install在上游更新了 Chromium 版本后我们的私有 registry 会在 30 分钟内自动同步下游服务无需任何操作就能获得最新兼容性。4.2 权限控制用 GitHub Branch Protection CODEOWNERS 实现最小权限金融客户要求开发人员只能提交testing/目录的技能运维人员才能修改infra/目录安全团队拥有最终审批权。我们通过 GitHub 的两个原生功能实现Branch Protection Rules对main分支启用Require pull request reviews before merging并设置Required number of reviewers: 2其中至少 1 人必须是security-teamTeam。CODEOWNERS 文件/core/* infra-team /testing/* dev-team /infra/* ops-team /security/* security-team这样当开发人员提 PR 修改testing/jest.run.skill.json时GitHub 会自动要求dev-team成员 review如果 PR 包含infra/aws.deploy.skill.json的修改则必须ops-team和security-team同时 approve。我们还加了一条硬性规定所有技能的command字段必须通过正则校验^[a-z0-9.-_]$禁止出现;,$(),|等 shell 注入字符。CI 流程中嵌入了grep -q [;|$()] *.skill.json检查不通过直接 fail。这套机制让技能提交从“谁都能改”变成“谁改谁负责”上线三个月零安全事故。4.3 审计集成把每一次 skill 调用变成可追溯的日志事件客户要求所有 CLI 操作必须记录到 Splunk。我们在skills/cli的 runtime 层做了两处改造执行前钩子Pre-hook在拼接命令前生成唯一 trace ID记录调用者用户名、主机 IP、skill ID、参数摘要脱敏处理如--token***执行后钩子Post-hook捕获 exit code、stdout/stderr 截断防日志爆炸、执行耗时发送到内部日志网关。具体代码片段TypeScriptexport async function runSkill(skill: SkillDefinition, args: Recordstring, any) { const traceId crypto.randomUUID(); const startTime Date.now(); // 审计日志前置 auditLogger.info({ traceId, action: skill_run_start, user: os.userInfo().username, host: os.hostname(), skillId: skill.id, maskedArgs: maskSensitiveArgs(args), }); try { const result await executeCommand(skill.command, buildArgs(skill.args, args)); // 审计日志成功 auditLogger.info({ traceId, action: skill_run_success, durationMs: Date.now() - startTime, exitCode: result.exitCode, outputSize: result.stdout.length, }); return parseOutput(result.stdout, skill.outputSchema); } catch (error) { // 审计日志失败 auditLogger.error({ traceId, action: skill_run_failure, error: error.message, durationMs: Date.now() - startTime, }); throw error; } }这套审计体系上线后客户的安全团队第一次实现了对“开发者在生产环境执行了什么命令”的实时监控。比如他们发现某次skills.git.push调用耗时异常60s追溯发现是开发人员误将--force参数传给了skills.git.push导致大量分支被覆盖。如果没有审计日志这个问题可能数周后才被发现。4.4 团队协作用 skills.dev 作为内部技能市场不是共享文件夹光有 registry 不够团队需要发现和学习技能。我们基于skills list命令开发了一个内部 Web 界面skills.dev它有三个核心功能技能搜索支持按id,name,description,category全文检索结果高亮匹配关键词技能试用在浏览器里直接输入参数点击 Run后端调用npx skills id并返回结果沙箱环境隔离使用统计每项技能页面显示“本周调用次数”、“Top 3 调用者”、“平均耗时”帮助识别高频技能和潜在瓶颈。这个界面不是炫技而是解决真实协作痛点。以前新人入职要花半天时间问同事“部署命令是什么”现在打开skills.dev搜索deploy立刻看到skills.aws.deploy,skills.k8s.apply,skills.vercel.push三个选项点击查看详情页里面有每个技能的 usage example、参数说明、甚至录制的 30 秒 demo 视频。我们还做了个有趣的功能skills.dev会分析团队 Git 提交记录自动推荐“你最近修改的文件类型最常搭配的技能”比如你频繁改Dockerfile首页就会推送skills.docker.build和skills.docker.scan。上线首月内部 CLI 工具使用率提升 300%因为“找命令”的成本降到了零。5. 常见问题与排查技巧实录那些官方文档不会告诉你的 7 个真相在落地 agent-skills 的过程中我和团队踩过的坑远比文档里写的多。以下是七个最典型、最高频、最让人抓狂的问题以及我们总结出的实战解法。这些问题没有一个出现在官方 FAQ 里但每一个都曾让我们加班到凌晨两点。5.1 “npx skills install 失败Cannot find module ‘skills’” —— 不是网络问题是 npx 的缓存 bug现象在 CI 环境中npx skills list第一次执行总是失败报错Cannot find module skills但第二次执行就成功。本地复现不了只在 Docker 容器里发生。真相npx在首次运行时会创建一个临时目录如/tmp/npx-12345下载skills/cli并执行。但某些 Linux 发行版的/tmp目录设置了noexec标志导致下载的二进制无法执行。npx错误地把权限拒绝当成模块未找到。解法强制指定 npx 缓存目录# 在 CI 脚本开头添加 export NPM_CONFIG_TMP/home/node/.npm-tmp mkdir -p $NPM_CONFIG_TMP npx skills list或者更彻底全局安装npm install -g skills/cli skills list我们最终选择后者因为 CI 环境稳定且避免了每次npx的下载开销。5.2 “skills.playwright.install 失败Error: spawn EACCES” —— 不是权限不足是 Chromium 的沙箱限制现象npx skills playwright.install在 Ubuntu 22.04 的 Docker 容器里失败错误是spawn EACCES网上搜到的方案都是chmod x但无效。真相Playwright 的 Chromium 二进制需要--no-sandbox参数才能在容器里运行但skills.playwright.install的定义里没传这个参数导致安装后的二进制本身就不具备容器运行能力。解法不是改技能定义而是改调用方式npx skills playwright.install --no-sandbox前提是skills.playwright.install的args定义里包含noSandbox字段。我们给官方 registry 提了 PR增加了这个参数。这个案例说明技能定义必须预判所有部署环境的特殊性不能只考虑 macOS 或 Windows 开发机。5.3 “skills find 返回空列表” —— 不是 registry 没数据是本地缓存损坏现象npx skills find --categorytesting什么也不返回但curl https://raw.githubusercontent.com/skills-registry/core/main/testing/jest.run.skill.json能正常获取文件。真相npx skills会把 registry 索引缓存在~/.skills/cache/registry.json如果这个文件损坏比如磁盘满导致写入一半后续所有find命令都会返回空。解法一键清理缓存npx skills cache clear npx skills cache update我们把这个命令写进了团队的setup.sh脚本新人入职第一件事就是运行它。更进一步我们在skills.dev后端加了健康检查如果检测到缓存文件 size 1KB就自动触发cache update。5.4 “skills.git.commit --message‘fix: bug’ 失败fatal: empty commit message” —— 不是参数没传是 shell 的 quote 规则现象在 zsh 里npx skills git.commit --messagefix: bug正常但在 bash 里报错empty commit message。真相bash 和 zsh 对双引号内空格的处理不同。npx在 bash 下会把--messagefix: bug解析成两个参数--messagefix:和bug导致message参数值为空。解法统一用单引号包裹npx skills git.commit --messagefix: bug或者更稳妥用连接符npx skills git.commit --messagefix: bug但必须确保所有 shell 都支持。我们最终在团队文档里明确要求“所有 skills 命令的字符串参数必须用单引号包裹”。5.5 “skills.curl.get 返回 HTML 而不是 JSON” —— 不是 API 改了是 Accept 头缺失现象npx skills curl.get --urlhttps://api.example.com/data返回的是网页 HTML而不是预期的 JSON。真相curl默认的Accept头是*/*某些 API 会根据Accept头返回不同格式。skills.curl.get的定义里没设置headers参数导致没发Accept: application/json。解法扩展技能定义增加 headers 参数args: [ {name:url,type:string,required:true}, {name:headers,type:object,default:{Accept:application/json}} ]然后在command里用jq动态拼接command: sh -c curl -H \Accept: $(echo {{headers.Accept}} | jq -r .)\ {{url}}这个改动让skills.curl.get真正成为通用 HTTP 客户端而不是一个“碰运气”工具。5.6 “skills init --templatenextjs 卡住不动” —— 不是网络慢是 pnpm 的 store.lock现象在公司内网npx skills init --templatenextjs执行到Installing dependencies...就卡住CPU 占用 0%内存不涨。真相pnpm 默认使用全局 store但在内网环境下store 的lock文件被其他进程占用导致新进程阻塞等待。解法强制使用本地 storenpx skills init --templatenextjs --pnpm-store.pnpm-store前提是skills.init的定义里支持pnpmStore参数。我们给这个技能加了该参数并设为默认值./.pnpm-store彻底解决内网卡顿问题。5.7 “skills list 显示的技能 ID 和实际调用不一致” —— 不是 bug是 registry 的 category 优先级现象npx skills list显示skills.aws.deploy但npx skills aws.deploy报错command not found。真相agent-skills 的npx skills id解析逻辑是先查core/目录再查cloud/再查infra/。如果skills.aws.deploy同时存在于core/和cloud/skills list会显示core/aws.deploy但npx skills aws.deploy会优先匹配cloud/aws.deploy因为cloud在搜索路径中排更前。ID 显示和实际调用路径不一致。解法永远用完整 ID 调用npx skills cloud.aws.deploy或者在skills.dev的 UI 上每个技能卡片都显示“完整调用 ID”并提供一键复制按钮。这个设计缺陷提醒我们技能 ID 的命名空间管理比想象中更关键。6. 技能开发进阶如何写出能被 AI Agent 理解和编排的 production-ready skillagent-skills 的终极价值不在于人手动调用而在于成为 AI Agent 的“可执行 API”。要达到这个目标技能不能只是功能正确还必须满足三个更高阶的要求语义可推理、上下文可感知、失败可恢复。这已经超出了传统 CLI 工具的范畴进入了 AI 工程的新领域。6.1 语义可推理用 description 和 examples 让 LLM 看懂你的 skillLLM 调用技能时不会执行代码只会读取description和examples字段做意图匹配。所以skills.git.commit的 description 不能写“提交代码”而要写“将暂存区的变更永久保存到本地仓库生成新的 commit 对象支持 amend 模式覆盖上一次提交”。更关键的是examples字段它必须是真实的、可运行的命令序列examples: [ skills git commit --message\feat: add login button\, skills git commit --amend --message\chore: fix typo in README\, skills git commit --message\docs: update installation guide\ --no-verify ]我们做过 A/B 测试一组技能只有 description另一组加上高质量 examples被 Claude 3 调用的成功率从 62% 提升到 94%。原因很简单LLM 的 prompt engineering 严重依赖示例它需要看到--amend和--no-verify这样的参数组合才能理解这个技能支持哪些高级操作。另一个技巧是在description里加入领域术语比如skills.docker.scan的 description 写“使用 Trivy 扫描容器镜像中的 CVE 漏洞输出 SARIF 格式报告”而不是“扫描 Docker 镜像”。因为 LLM 在训练时见过大量 SARIF、CVE、Trivy 这些词匹配精度更高。6.2 上下文可感知skill 不是孤岛它必须知道“我在哪、和谁一起”一个 production-ready skill 应该能感知执行上下文。比如skills.git.commit在非 git 仓库目录下执行应该友好提示“Not a git repository”而不是抛出原始 git 错误。我们通过在command里加前置检查实现command: sh -c if [ ! -d .git ]; then echo \{\\\error\\\:\\\Not a git repository\\\}\; exit 1; else git commit {{args}}; fi更进一步skills.env.list这个技能它应该能区分“当前 shell 的 env”和“当前项目 .env 文件的 env”。我们在args里加了source参数args: [ {name:source,type:string,enum:[shell,dotenv],default:shell} ]然后command根据source值动态选择printenv或cat .env | grep \^\\w*\。这种上下文感知能力让 skill 不再是冷冰冰的命令封装而成了有“情境理解力”的协作者。6.3 失败可恢复skill 的退出码不是 0 或 1而是一张状态图传统 CLI 工具失败就报错但 AI Agent 需要知道“失败的原因”和“下一步该做什么”。我们为skills.playwright.install设计了三级退出码0: 成功安装1: 网络超时建议重试2: 磁盘空间不足建议清理/tmp3: Node.js 版本不兼容建议升级并在outputSchema里定义了errorType字段outputSchema: { type: object, properties: { status: { type: string, enum: [success, retry, fix, abort] }, errorType: { type: string, enum: [network, disk, version, permission] }, suggestion: { type: string } } }这样当 AI Agent 收到status: fix, errorType: disk时它可以自动执行skills.disk.clean --target/tmp然后再重试skills.playwright.install。我们称之为“自愈式技能链”它把原本需要人工介入的故障处理变成了自动化流水线的一部分。6.4 生产就绪 checklist发布前必须验证的 5 个硬性指标最后分享我们团队内部的skills release checklist任何技能上线前必须 100% 通过检查项标准不通过后果Schema 合法性outputSchema能被ajvv8 验证且required字段非空拒绝合并防止上游解析失败Command 安全性command字段不包含;,$(), ,, 等 shell 元字符参数完整性所有args必须有name,type,descriptiondefault值类型与type一致拒绝合并保障下游调用可靠性Examples 可执行性examples数组中每个命令在干净环境中能真实运行并返回符合outputSchema的结果拒绝合并确保 LLM 调用成功率Audit 日志完备性技能执行前后必须产生两条审计日志start/failure/success包含 traceId 和 maskedArgs拒绝合并满足金融级合规要求这张表贴在我们团队的物理白板上每次 PR Review 都要逐项勾选。它不是束缚创新的枷锁而是让技能从“能用”走向“敢用”的基石。毕竟在生产环境里一个不可靠的 skill比没有 skill 更危险。我在实际使用中发现最有效的