企业官网建设流程全解析

Expo Skills 的 CI 如何自动校验技能质量？check-skill-limits 与版本管理脚本深度解析

【免费下载链接】skillsA collection of AI agent skills for working with Expo projects and Expo Application Services项目地址: https://gitcode.com/gh_mirrors/skills9/skills

Expo Skills 是面向 Expo 项目的 AI 代理技能（Agent Skills）合集，它的 CI 流水线通过check-skill-limits、插件版本检查等脚本，自动校验每一个技能的质量规范与四端插件版本同步。本文带你完整解析这套自动化质量门禁的设计思路与实现细节。

为什么技能仓库也需要 CI 校验？

这个仓库里住着25 个技能（plugins/expo/skills/下的expo-router、eas-hosting等）和4 个插件清单（Claude、Codex、Cursor、Grok 各一份plugin.json）。技能一旦触发，整个SKILL.md就会加载进 AI 的上下文窗口——所以质量不只是"代码能跑"，还包括：

• 📏体量克制：描述和正文不能无限膨胀
• 🏷️命名规范：expo-*（免费开源）与eas-*（付费 EAS 服务）的边界必须清晰
• 💰付费披露：收费技能必须提前告知成本
• 🔁版本同步：四端插件清单必须同步升级

靠人工 Review 很难盯住这些细节，于是项目把它们全部固化成了可重复执行的检查脚本。

CI 流水线总览：一个 Workflow 四道关卡

核心工作流定义在 .github/workflows/check.yml，它在每次提交到main分支的 PR 以及合并组触发时运行：

这里有一个巧妙的设计：四道关卡都配置了continue-on-error: true，让一次运行暴露所有失败，而不是修一个错、重跑一次才看到下一个错。最后由专门的 "Report check results" 步骤汇总各关卡结果、生成表格报告，并统一决定整个 Job 的成败（见 check.yml#L60-L108）。

关卡一：check-skill-limits 的七项体检

scripts/check-skill-limits.ts 会递归扫描plugins/下的所有SKILL.md，对每个技能做七项检查：

1. 体量上限（CI 强制）

• 描述（frontmatterdescription）最多1024 字符
• 正文（body）最多500 行

常量直接定义在 check-skill-limits.ts#L6-L7。"技能触发即全量加载进上下文"是这套上限的由来——更短的技能 = 更省上下文、更省费用。

2. 命名规范

技能目录必须叫expo-*或eas-*，且 frontmatter 里的name必须与目录名完全一致。前缀就是"免费/付费"的边界标识。

3. 分类前缀

每个技能的描述必须以分类标签开头：开源技能用Framework (OSS).，付费技能用EAS service (paid).（跨领域的expo-skill-feedback技能豁免）。

4. 付费披露

eas-*付费技能的正文必须包含 "EAS service - costs apply." 提示和官方定价页链接——成本信息前置，绝不藏着掖着。

5. Codex 元数据

每个技能必须携带 agents/openai.yaml（Codex 触发元数据）；付费技能的short_description还必须以Paid EAS service.开头。

6. 目录同步

技能必须在 skills.sh.json 中登记到正确的分组（Framework / Experimental / Services & paid distribution），脚本同时做双向校验：技能没登记会报错，目录里登记了但文件不存在也会报错。

7. 统一反馈块

每个SKILL.md结尾必须带有标准的 "Submitting Feedback" 反馈块，且块内的技能名要与自身匹配。忘了加或写错了？跑一下bun scripts/check-skill-limits.ts --fix-feedback即可自动修复全部技能。

全部通过时，脚本会打印一行确认："✓ All skills pass limits, naming, feedback, category labels, paid callouts, Codex metadata, and catalog sync."

关卡二：check-plugin-version-bump 版本管理深度解析

scripts/check-plugin-version-bump.ts 守护的是一条"四端同步升级"规则。

什么是"版本化路径"？脚本监控这些路径的变更（见 check-plugin-version-bump.ts#L37-L45）：

• plugins/expo/skills/（全部技能内容）
• 四个插件清单：.claude-plugin/、.codex-plugin/、.cursor-plugin/、.grok-plugin/下的plugin.json
• mcp.json/.mcp.json

只要其中任何文件变化，CI 就要求：

1. ✅ 四个清单的version必须全部改成同一个值（不允许只升 Claude 不升 Codex）
2. ✅ 新版本必须大于origin/main上的版本
3. ✅ 版本必须是合法 semver（脚本内置完整的 semver 正则校验）

目前四个清单都锁定在1.13.8，这正是该规则生效后的产物。

贴心设计：--set-version一键写回

改四个 JSON 文件容易漏，脚本提供了便利选项：

bun scripts/check-plugin-version-bump.ts --set-version 1.13.9

它会自动校验 semver 合法性、确认大于 base 分支版本，然后把四个清单一次性更新，并对已是该版本的清单跳过（"Unchanged"）。

Markdown 报告 + PR 评论

设置环境变量VERSION_CHECK_SUMMARY_PATH后，检查结果会以 Markdown 表格形式写出（对比每个插件在 main 与 PR 中的版本），CI 会把报告附加到 Job Summary，甚至直接在 PR 上留一条带标记的评论；检查通过后，之前失败留下的评论还会被自动删除——PR 讨论区始终保持干净。

脚本也要被测试：CI 里还专门有一步运行 check-plugin-version-bump.test.ts 测试套件，覆盖--help、--set-version等所有用例。测试会先备份四个清单、逐条还原，所以"检查者"本身也处于被检查状态。

关卡三：路由覆盖检查

scripts/check-overview-routing.ts 守护expo-overview这个"路由技能"：所有其他技能必须以行内代码（如expo-router）的形式出现在 expo-overview/SKILL.md 的 Skill Map 里，否则 AI 路由就"派单"不到新技能。漏登记的技能会被逐一列出，并提示修复位置。

失败如何被报告？

工作流的 "Report check results" 步骤会在 Job Summary 里生成这样一张表：

每行失败项都附上了本地复现命令，新手照着敲一遍就能在自己的机器上重现问题——这是"CI 友好型报错"的典型做法。

本地先跑一遍：提交 PR 前的 3 条命令

按照 CONTRIBUTING.md 的建议，打开 PR 之前先在本地执行：

claude plugin validate ./plugins/expo bun scripts/check-skill-limits.ts bun scripts/check-plugin-version-bump.ts origin/main

改过 JSON 的话再用python3 -m json.tool验证一下格式，就能确保 CI 一次通过。

进阶一瞥：技能评估 CI 与指纹缓存

除了静态检查，仓库还配套了面向"技能实际效果"的评估流水线脚本：

• scripts/ci.sh：Shell 侧的评估辅助函数（拉取私有 eval-harness 子模块、执行"生成应用 + 技能触发评估"、缓存命中判断等）
• scripts/ci.py：Python 侧的对应实现，提供fingerprint、bundle write/verify、print-outputs三个子命令

其中fingerprint的设计尤其值得新手学习：它把技能内容哈希、eval-harness 的 commit SHA、PRD/场景配置、Agent 与模型名全部揉进一个 SHA-256 指纹——只要任何一项输入变化，旧缓存立即失效，保证评估结果永远可比。脚本注释里还藏着一段真实踩坑记录：模型必须用 1M 上下文变体（sonnet[1m]），否则 200k 的模型会"丢掉"技能描述菜单，导致所有触发得分都是 0。

小结

这套 CI 的核心思想对任何维护"多 Agent 多格式分发"的团队都有借鉴意义：把 Review 清单变成可执行的脚本，把"一次暴露全部问题"变成默认行为，并给每个失败都附上本地复现命令——质量校验从此不再依赖人的记忆，而是依赖流水线的确定性。🚀

【免费下载链接】skillsA collection of AI agent skills for working with Expo projects and Expo Application Services项目地址: https://gitcode.com/gh_mirrors/skills9/skills