storefront-builder 是 Saleor 官方文档仓库中的一项 AI 技能，定位为“Saleor 店面数据 + UX 操作手册”。它不负责框架脚手架、CSS 环境搭建或环境变量加载的具体细节，这些需要由智能体从本地项目中自行发现。该技能通过解析 $ARGUMENTS 的第一个词确定步骤编号，只执行所选步骤，然后停止并等待用户请求下一步，不会自动串联步骤。若无步骤或步骤无法识别，则打印用法说明：步骤 1 为 Bootstrap（引导），连接 GraphQL 客户端、代码生成与 Saleor API；步骤 2 为设计美学，定义配色、字体与强调色；步骤 3 为目录，构建商品列表页与含变体选择的商品详情页。
步骤 1：项目引导。先询问用户是否已有 Saleor 实例；没有则到 https://cloud.saleor.io/ 创建（提供免费套餐）。随后读取 package.json 与框架配置文件，判断框架版本、包管理器、现有 GraphQL 设置、导入别名与源码目录布局，不就此提问。若仓库根目录没有 AGENTS.md，则创建并仅引用已安装技能的 AGENTS.md；随后安装 graphql-request、graphql 及 @graphql-codegen/cli、@graphql-codegen/client-preset（开发依赖），创建 codegen 配置（schema 为 Saleor API URL，documents 指向 GraphQL 文件目录，generates 使用 client preset 且 gqlTagName 为 graphql），并在 package.json 添加 codegen 脚本。它还要求采用双客户端模式：saleorClient（匿名、无鉴权头，适用于 RSC、SSG 与公开商品查询）和 saleorAuthClient（仅服务端、从环境变量读取 app token，绝不可进入浏览器包），以避免在公开或缓存查询中携带 app token 造成权限泄露与客户数据暴露。环境变量包括带公开前缀的 SALEOR_API_URL、SALEOR_CHANNEL，以及仅服务端的 SALEOR_APP_TOKEN。若有现成实例，可用 Configurator CLI 的 introspect 命令查看渠道、已发布商品与分类结构。最后运行 codegen 验证 schema 可达，并输出摘要后停止。
步骤 2：设计美学。先检查项目样式体系（Tailwind、CSS Modules、styled-components、UnoCSS 或原生 CSS 等）与现有设计令牌约定；再以对话方式询问用户参考、整体风格与强调色；然后确定背景、表面、边框、主次文本、强调色、悬停色、圆角、标题字体与正文字体等令牌，按项目约定写入主题模块并接入样式系统，最后输出摘要并停止。
步骤 3：目录页与详情页。先确认步骤 1 的客户端模块与渠道 slug 存在。随后编写 products.graphql，定义 ProductCard 片段（id、name、slug、thumbnail、pricing.priceRange.start、category，并说明 thumbnail、价格与分类均可为空需加保护）与 ProductDetails 片段（含 description、media、variants 的价格、selectionAttributes 与 quantityAvailable 等），并定义 ProductList 与 ProductBySlug 查询；channel 始终必填。数据处理规则包括：description 为 EditorJS JSON 不可直接渲染，需安全解析提取文本；价格用 Intl.NumberFormat 配合响应中的货币格式化，不硬编码货币符号；详情页优先用 media 首项，为空回退 thumbnail，缺失时显示占位图，alt 回退为商品名；quantityAvailable 为 null 视为有货、为 0 视为缺货、大于 0 为有货；变体选择显示全部变体但禁用缺货项，用 selectionAttributes 标注，单一变体且无选择属性时跳过选择器，选中变体后价格以变体价格覆盖；空列表、商品不存在、价格缺失分别处理。之后按框架路由约定写导航、商品列表页（可 SSG 的框架设合理再验证间隔，如 60 秒）、详情页与 VariantSelector 组件（加购按钮为占位、暂不可用），并启动开发服务器验证。该技能适用于在既有项目中为 Saleor 构建店面数据层与页面；限制是需要自备 Saleor 实例、具体路径与写法须遵循本地项目约定，且每步执行后须由用户显式请求下一步。