expo-cicd-workflows

expo-cicd-workflows skill 概览

expo-cicd-workflows skill 用于为 Expo 项目创建、编辑并校验 EAS workflow YAML。它最适合已经明确知道自己要自动化什么的开发者——比如构建、测试、提交、更新，或多阶段发布流水线——但又不想靠猜去拼当前 EAS workflow 的语法。

这个 skill 实际解决的是什么问题

这不是一个通用的 CI/CD 提示词合集。它真正要解决的问题，是把一个部署目标转成合法的 .eas/workflows/*.yml 文件，并且符合当前 Expo EAS workflow 的规则、job 类型、触发器、表达式和 schema 约束。

哪些人适合安装 expo-cicd-workflows

如果你符合以下情况，适合使用 expo-cicd-workflows：

• 你在发布 Expo 应用，希望把 CI/CD 放进 EAS Workflows
• 你需要有人帮你编写或修复 .eas/workflows/ 下的 YAML
• 你希望 agent 按 Expo 专属 workflow 语法来推理，而不是套用通用 GitHub Actions 模式
• 你在意的是基于实时 schema 的校验，而不是过期示例

为什么它比普通提示词更好用

它最核心的差异在于：这个 skill 会要求 agent 在生成 YAML 之前，先拉取最新的 Expo workflow schema 和文档。这个点非常关键，因为 EAS workflow 的配置项会持续演进，而无效的 enum 值或过期字段，正是普通提示方式里最常见的失败来源。

它具体包含什么

这个仓库体量不大，但很实用：

• SKILL.md 说明如何获取权威文档来源
• scripts/fetch.js 用 ETags 缓存远程文档
• scripts/validate.js 使用 ajv、ajv-formats 和 js-yaml 校验 workflow 文件

因此，expo-cicd-workflows 不仅适合从零生成，也很适合拿来修正已有的 workflow 文件。

需要提前知道的最大限制

这个 skill 关注的是 EAS workflow YAML，而不是你完整的移动端发布流程。它能帮助你设计 workflow 文件，但像应用环境、分支策略、凭据配置，以及团队内部“deploy”到底具体指什么，这些项目级信息仍然需要你自己提供。

如何使用 expo-cicd-workflows skill

expo-cicd-workflows 的安装环境要求

请在你的 coding agent 能读取 Expo 项目、并能写入 workflow 文件的环境中，从 Expo skills 仓库安装 expo-cicd-workflows skill：

npx skills add https://github.com/expo/skills --skill expo-cicd-workflows

如果你的 agent 支持本地 skill 发现机制，请确认它能访问已安装文件，并可运行基于 Node 的辅助脚本。

先读这几个文件

建议按这个顺序开始看：

1. plugins/expo/skills/expo-cicd-workflows/SKILL.md
2. plugins/expo/skills/expo-cicd-workflows/scripts/validate.js
3. plugins/expo/skills/expo-cicd-workflows/scripts/fetch.js

这个阅读顺序很重要：SKILL.md 说明整体操作流程，validate.js 展示了基于 schema 的校验模型，fetch.js 则解释了远程引用的缓存方式。

这个 skill 需要你提供哪些输入

想让 skill 给出真正可用的结果，最好提供以下信息：

• 你的 workflow 目标：build、test、submit、update，还是串联式 release 流程
• 触发规则：branch、PR、schedule、manual，还是由另一个 workflow 触发
• 平台范围：iOS、Android，或两者都要
• 环境需求：secrets、profiles、env vars、channels
• 期望输出：artifacts、updates、应用商店提交、通知
• 目标文件：通常是 .eas/workflows/<name>.yml

如果没有这些信息，agent 最多只能给你一个比较泛的草稿。

怎样把模糊需求变成高质量提示

弱提示：

• “Make me an Expo deployment workflow.”

更好的提示：

• “Use the expo-cicd-workflows skill to create .eas/workflows/release.yml for an Expo app. Trigger on pushes to main. Build Android and iOS production profiles, run tests first if supported, then submit both builds. Explain any required secrets and validate the final YAML against the current EAS schema.”

第二种写法能给 skill 足够多的结构化信息，让它更准确地选择触发器、job 顺序和校验步骤。

始终先拉取最新 Expo 参考资料

这个 skill 的设计前提是基于最新文档，而不是靠模型记忆。无论是新写还是修改 YAML，在动手前都应先获取 SKILL.md 中提到的最新参考资料，尤其是：

• https://api.expo.dev/v2/workflows/schema
• Expo EAS workflows syntax docs
• Expo pre-packaged jobs docs

在使用 expo-cicd-workflows for Deployment 时，这是最有价值的习惯，因为 schema 漂移是导致输出无效的最快路径。

在信任生成的 YAML 前，先做校验

最稳妥的使用方式是：

1. 先让 agent 生成 workflow 草稿
2. 将它保存到 .eas/workflows/
3. 运行校验脚本
4. 修复 schema 错误
5. 然后再填入项目特定值

示例校验流程：

cd plugins/expo/skills/expo-cicd-workflows/scripts
npm install
node validate.js /path/to/project/.eas/workflows/release.yml

如果你是在 skill 目录上下文里执行，校验器会拉取实时 schema，并用字段路径报告 YAML 或 schema 错误。

校验脚本实际检查了什么

validate.js 会解析 YAML、加载实时 EAS schema，并使用严格的 AJV 校验你的文件。这可以捕获：

• YAML 格式错误
• 缺失必填字段
• 不受支持的 enum 值
• 类型错误
• 顶层或嵌套结构不合法

这也是为什么 expo-cicd-workflows usage 这种用法，比直接复制旧博客里的示例要安全得多。

真实项目中推荐的 expo-cicd-workflows 工作流

一个比较实用的流程是：

1. 先检查你现有的 eas.json 和发布流程
2. 告诉 agent 你希望的触发方式和输出结果
3. 让它生成初版 workflow 文件，并解释有哪些前提假设
4. 校验 YAML
5. 再调整 secrets、profile 名称、channels 和分支过滤条件
6. 在它成为主发布流水线之前，先跑一个小范围 workflow

这样可以尽量避免最常见的落地问题：YAML 语法完全合法，但实际跑出来的流程和你的运营目标并不一致。

编辑现有 workflow 时，最好的提示方式

如果你是在修改已有文件，请把完整 YAML 和你的改动要求一起给出。示例：

• “Use expo-cicd-workflows to update this .eas/workflows/preview.yml. Keep existing build jobs, but only trigger on PRs to develop, add a step for preview updates, and preserve current environment variable names. Validate the result and call out any unsupported fields.”

这样能帮助 agent 保留原始意图，而不是把整个文件从头重写。

建议一并提供给 skill 的仓库细节

如果你能提供以下内容，agent 的表现通常会更好：

• eas.json
• 现有的 .eas/workflows/*.yml
• 分支命名规则
• 是否使用 EAS Update
• CI/CD 是否包含应用商店提交
• profiles 或 environments 的命名约定

这些输入会显著提升 expo-cicd-workflows guide 的实际质量，因为这个 skill 只负责语法和结构的正确性，而你的仓库才决定最终发布流程长什么样。

expo-cicd-workflows skill 常见问题

expo-cicd-workflows 只能用于新建 workflow 文件吗？

不是。expo-cicd-workflows 也很适合用于审查、排错和现代化升级已有的 EAS workflow YAML，尤其是那些基于旧版文档编写，或从不完整示例复制出来的文件。

它比直接让模型生成通用 CI/CD YAML 更好吗？

如果你的目标是 EAS Workflows，那么答案是肯定的。通用 CI/CD 提示很容易漂移到 GitHub Actions 的概念上，而这些概念并不能自然映射到 .eas/workflows/ 语法。这个 skill 是按 Expo 专属 workflow 结构和校验逻辑调过的。

我需要先懂 EAS Workflows 吗？

即使是新手也可以使用这个 skill，但如果你能回答一些基本发布问题，结果会更好：workflow 由什么触发、有哪些环境、最终部署步骤需要做什么。这个 skill 更擅长帮你处理语法和结构，而不是替你决定产品或发布策略。

什么情况下不该用 expo-cicd-workflows？

以下情况建议跳过：

• 你并没有使用 Expo EAS Workflows
• 你需要的是脱离 Expo 工具链的完整跨平台 CI 设计
• 你的主要问题是应用签名、凭据或商店政策，而不是 workflow YAML
• 你想要完全不做仓库级决策的一键部署

这个 skill 会安装项目依赖吗？

不会。expo-cicd-workflows install 这一步只会安装 skill 本身；但如果你要运行校验器，还依赖 scripts/package.json 里的 Node 脚本依赖。因此，如果你想在本地跑校验，请在脚本目录里安装这些依赖。

expo-cicd-workflows 能保证部署流水线一定可用吗？

不能。它可以提高 workflow 文件的正确性、减少 schema 错误，但最终部署能否真正跑通，仍取决于凭据、profiles、secrets、app config，以及你的 Expo 项目实际是如何配置的。

如何改进 expo-cicd-workflows skill 的使用效果

提供部署意图，而不只是文件名

想提高 expo-cicd-workflows 输出质量，最快的方法就是把发布意图说清楚，例如：

• “preview updates on PRs”
• “nightly internal builds”
• “production store submission from main”
• “manual hotfix release”

明确意图后，agent 才能更合理地选择触发器和 job 编排顺序。

把周边 Expo 配置一起给出来

请一并提供 eas.json、现有 workflow 文件，以及任何环境命名约定。很多质量不高的输出，根源都在于 agent 不得不自己臆造 profile 名称、channels 或项目中其实不存在的前提条件。

让 skill 明确写出假设条件

一个高质量提示词，结尾通常会加上：

• “List assumptions before finalizing YAML.”
• “Mark fields that depend on repo-specific values.”
• “Explain what secrets or profiles must already exist.”

这样做能让第一版草稿更容易审阅，也能减少隐藏故障。

使用 validate-fix 循环

想把 expo-cicd-workflows usage 用好，最好把它当成一个迭代过程：

1. 生成 YAML
2. 校验
3. 把原始错误信息完整贴回去
4. 要求给出修正版

由于校验器会返回具体的 schema 路径，第二轮修改通常会比第一轮明显更可靠。

留意这些常见失败模式

常见问题包括：

• 把 GitHub Actions 语法混进 EAS workflows
• 使用了过期字段名或 enum
• 缺少触发器细节
• job 依赖关系不清晰
• 假设仓库里已经有某些 profiles、channels 或 secrets，但实际上并没有

这些问题，大多都可以通过强制 skill 拉取最新文档，以及提供真实配置文件来避免。

先要最小可用 workflow，再逐步扩展

如果落地受阻是因为流程过于复杂，建议先让它生成一个最小可用、但结构正确的 workflow，先验证流水线形状，再逐步加功能。例如：

• 先创建一个手动触发的 Android build
• 再加 branch triggers
• 然后加 iOS
• 最后再加入 submission 或 update 步骤

这样能显著降低排错成本，也往往是采用 expo-cicd-workflows for Deployment 的最佳路径。

用约束更充分的提示提升输出质量

一个好的高级提示通常会包含：

• 目标文件路径
• 触发条件
• 平台范围
• 按顺序要求的 jobs
• profiles 或 channels
• 哪些内容必须保持不变
• 要求按实时 schema 做校验

相比一句话让它“生成完整 CI/CD workflow”，这种组合往往能产出更稳定、更可落地的结果。

把辅助脚本当作可信锚点来用

expo-cicd-workflows 的隐藏优势，不只是文字说明本身，更在于这些辅助工具：

• fetch.js 通过缓存和 ETags 降低文档过期风险
• validate.js 用实时 schema 强制校验正确性

如果你想拿到更好的结果，应该明确要求 agent 把这些脚本纳入实际工作流，而不是只把它们当成可有可无的附加选项。