clerk-orgs

整合 CI 检查并提高 clerk-setup 的准确性 将检查器移入 scripts/，置于根 package.json 之下，用 Test 和 Check 工作流替换 每个检查的工作流和复合操作，并用 concurrently 运行所有检查。 修正 clerk-setup 中关于脚手架和引导支持的声明，按平台对 auth-controls 步骤进行门控，将 Core 2 检测移到设置之前，并 全程使用 Markdown 链接。在不变式检查器中于 init 之前捕获内联代码登录。 重新指向过时的 README 和同级技能引用。 Co-Authored-By: Claude Opus 5.5

合并来自 clerk/feat/orgs-recommend-decision-block 的拉取请求 #71 feat(clerk-orgs)：帮助代理判断应用是否需要 Organizations

test(orgs)：为在没有 org 词汇的情况下推荐 orgs 添加评估 现有的九个用例都在提示中提到了 organizations、roles 或 RBAC， 因此没有一个能检验该技能是否首先被触达。新增一个提示中从未出现该词的 B2B 用例、一个不得触发推荐的 B2C 用例，以及一个模糊的共享用例， 该用例应呈现该选项而不启用任何内容。

feat(orgs)：帮助代理判断应用是否需要 Organizations 该技能只有在开发者已经使用 org 词汇后才会浮现，因此一个被描述为 “公司注册并邀请其团队”的项目从未触达它。将描述扩展到症状术语， 并添加一个决策块，该块读取仓库、区分强信号与弱信号， 并告诉代理去询问而不是静默启用。

fix(orgs)：使用内联查询字符串而不是 --query 标志 clerk api 将端点作为路径参数，没有 --query 选项， 因此所有三个 list 命令在到达网络之前就失败并报“unknown option '--query'”。 已针对 clerk@3.2.0 验证了替换方案。

docs(skills)：移除 keyless 品牌和已失效的 SDK keyless 流程 对应 clerk/clerk#3209：描述行为（临时开发密钥，无需账户） 而不是 keyless 品牌，并从设置文案中删除框架列表。 - clerk-setup：将 SDK 的 'Keyless (Automatic)' 密钥路径（已在 @clerk/nextjs 7.8.0 中移除）替换为 clerk init 流程；修正 frontmatter 兼容性行；将版本提升至 2.5.0 - clerk-setup 评估：按 'clerk init temporary development keys' 评分，而不是 'keyless dev mode' - clerk-cli + references：重命名 Keyless 章节/锚点，改写 文字；字面 CLI 表面（--keyless、.clerk/keyless.json、whoami 的 keyless 对象）有意保留 - clerk router、clerk-orgs、clerk-billing：单行改写

docs(skills)：keyless 是默认方式——无需登录 CLI PR clerk/cli#395 使 keyless 成为未认证 clerk init 的默认方式， 并允许在无账户的情况下配置 keyless 实例。更新那些仍声称 --keyless 是可选加入 或 auth login 是前置条件的技能。 Co-Authored-By: Claude Fable 5

refactor(orgs)：将 cli 命令从 config 换成 enable，以获得更清晰的启用说明

fix(orgs)：在更深入的路由器验证后修正 references 中的 CLI 端点 - 将已弃用的 /v1/saml_connections 替换为 /v1/enterprise_connections（现代路径）；注明付费计划的 SAML 功能门控 - 自定义角色：使用 POST /v1/organization_roles 创建（之前错误地使用 POST /v1/role_sets/.../roles，后者只是将现有角色添加到集合中） - 自定义权限：展示两步流程（先 POST /v1/organization_permissions 创建，再 POST /v1/organization_roles/.../permissions/... 附加）

fix(orgs)：在 references 中使用 clerk api 包装器而不是原始 BAPI References 现在一致地展示 clerk api 命令（对代理友好的包装器），而不是原始 BAPI URL。与 SKILL.md 的 Agent-first 侧边栏风格一致。

feat(orgs)：添加 agent-first CLI 侧边栏 - 新增 'Agent-first: Programmatic org management' 章节，展示： - 通过 PLAPI Instance Config PATCH 启用 Organizations + 设置（organization_settings.enabled / max_allowed_memberships / domains_enabled / admin_delete_enabled） - 通过 BAPI 进行 Org CRUD（POST/GET/PATCH/DELETE /v1/organizations） - 成员关系 CRUD（添加/列出/更新角色/移除） - 邀请（发送/列出/撤销） - 更新 STOP 提示框：启用开关也可通过 clerk config patch 完成 - 更新 Quick Start 第 1 步以展示两种路径 - 注明 org 订阅/计费通过 clerk-billing 技能处理 - 指向 references/ 以深入了解角色 + SSO

fix(orgs)：收紧 STOP 块中 Membership 模式的表述 原来的行声称选错模式会导致 PricingTable、 OrganizationSwitcher 和个人账户流程“静默中断”—— 这夸大了实际发生的情况。在 Membership required 模式下， 已登录用户会被引导通过 choose-organization 任务， 个人账户是按设计禁用的，而不是中断。改写为 描述每种模式的作用以及何时选择 optional，去掉 “静默中断”的表述。

fix(orgs)：第五轮排查——现代 signIn.sso + 多 SDK 认证访问器 又发现两处残留： enterprise-sso.md — Custom Sign-In Flow： - 示例使用了 signIn.authenticateWithRedirect()，它仍然可用 但属于旧路径。当前的 enterprise-connections 自定义流程 文档使用 signIn.sso({ strategy, identifier, redirectUrl, redirectCallbackUrl })。已更新为 Core 3 规范模式， 并添加一个小的 Core-2/旧版提示，说明旧方法仍存在 以保持向后兼容。 - 注意：redirectUrlComplete -> redirectUrl，以及新增的 redirectCallbackUrl 参数用于 additional-requirements 情况。 SKILL.md — §1 访问器说明： - 原来的行将 "getAuth(event)" 混为一谈，认为它同时覆盖 Nuxt 和 Astro 服务器，但 Astro 使用 context.locals.auth()（不是 getAuth）。按 SDK 拆分：Nuxt 用 auth(event)，Astro 用 context.locals.auth()， Express 用 getAuth(req)。客户端访问器保留为 useAuth（React） 或 composables（Vue/Nuxt）。

fix(orgs)：第四轮排查——TaskChooseOrganization SDK 列表 + verifyToken 引用 在第四轮交叉验证中又发现两处残留： SKILL.md §6（Session Task）： - 声称 TaskChooseOrganization "ships in @clerk/js-frontend" 作为 导入。包名实际上是 @clerk/clerk-js，并且 JS Frontend SDK 通过 clerk.mountTaskChooseOrganization / unmountTaskChooseOrganization 方法暴露任务 UI，而不是作为组件导入。 已改写以明确区分导入与挂载。 references/invitations.md 框架包装器表格： - @clerk/backend 行指向 clerk.verifyToken（方法式），但 verifyToken 是 @clerk/backend 的独立顶层导出， 不是客户端实例上的方法。已相应改写。

fix(orgs)：最终交叉验证排查——6 处残留不准确 对所有 4 个参考文件 + SKILL.md 进行全面排查，对照文档 参考页面 + @clerk/backend + @clerk/astro + @clerk/nuxt + @clerk/express 源码。 本轮发现： SKILL.md： - Enterprise SSO 简短章节仍声称 "Requires domain verification (DNS TXT)"。已改写以反映真实模型： SSO 连接直接拥有其域，不需要单独的 Verified Domain，这两个功能互斥。添加了 JIT Provisioning 作为真正的自动加入机制。 roles-permissions.md： - org:sys_domains:manage 描述声称覆盖 "Enterprise SSO connections"，但文档中没有。已收紧 为仅文档明确确认的内容（Verified Domains）。 invitations.md： - createOrganizationInvitationBulk 签名有误：技能中 是单个对象，内部有 invitations: [...]，但真实 方法将 organizationId 作为位置参数 + 一个 params 数组 作为第二个参数。遵循旧示例的代理会得到 TypeScript 错误或来自 BAPI 的 400。 - 批量端点速率限制从 250/hr（与单个相同） 更正为 50/hr（根据后端参考中批量特定的速率限制）。 - 框架包装器表格有两个错误的客户端获取器： @clerk/astro/server 使用了 `clerk(context)`（无效导入）—— 真实的是 `clerkClient(context)`。@clerk/nuxt/server 使用了 `useClerkClient(event)`——真实的是 `clerkClient(event)`。 已修正两个框架的认证上下文访问器。 nextjs-patterns.md：已对照 @clerk/nextjs/server 源码验证无误（auth.protect 重载、createRouteMatcher、clerkMiddleware）。 无需更改。

fix(orgs)：处理关于 enterprise-sso + invitations 参考的评审反馈 应用 PR 评审反馈： enterprise-sso.md： - 重写了 Configuration Flow。移除了 Verified Domains 的 DNS TXT 记录声明 （所有权通过 OrganizationSwitcher / OrganizationProfile 流程中的 电子邮件代码验证，依据 Verified Domains 指南）。移除了将 SSO 连接设置与 Verified Domains 混为一谈的内容——文档明确指出这两个功能 在同一域上互斥。 - 添加说明：目前 Dashboard 是唯一路径；将 CLI 标记为 未来发布后再重新审视。 - Verified Domains 章节重新表述为 "separate feature, short reference"，指向规范文档。 - 新增 JIT Provisioning 章节——这是将 SSO 用户自动加入 org 的 实际机制，而不是 Verified Domains。 - 修正 Key Rules：SSO 连接拥有其域（无需 Verified Domain 前置条件）；自动加入是 JIT Provisioning。 - 根据评审意见删除了自指的 "this is where the skill used to hallucinate" 措辞。 invitations.md： - 在顶部添加框架包装器提示。clerk.organizations.* 上的方法签名 在各 SDK 中相同——只有客户端获取包装器不同。表格涵盖 @clerk/nextjs、 @clerk/backend、@clerk/astro/server、@clerk/nuxt/server、 @clerk/express。保留 @clerk/nextjs 作为默认代码风格 （与 clerk-billing 先例一致），同时使跨 SDK 情况可发现， 回应关于框架分离的评审意见。

refactor(orgs)：将 nextjs-patterns 参考精简为 org 特定内容 通过移除已存在于 clerk-nextjs-patterns 技能中的内容， 精简 references/nextjs-patterns.md（146 -> 106 行）： - 文件命名说明（proxy.ts vs middleware.ts）——位于 clerk-nextjs-patterns/references/middleware-strategies.md - 通用 createRouteMatcher 介绍——同一位置 - 401 vs 403 响应策略——位于 clerk-nextjs-patterns/references/api-routes.md - 通用服务器操作形态——位于 clerk-nextjs-patterns/references/server-actions.md 保留 org 特定的适配： - 中间件中的 auth.protect({ role / permission }) - orgSlug === params.slug URL 安全不变式 - 服务器操作中按 orgId 作用域的数据库写入 - API 路由中的 getOrganizationMembershipList 用法 更新了 SKILL.md 中的路由 + 参考表格，以描述 该文件的范围，并引导代理到 clerk-nextjs-patterns 获取通用 Next.js 模式。

refactor(orgs)：准确性 + 渐进式披露调整 使 clerk-orgs 与 clerk-billing v2 和 clerk-nextjs-patterns 使用的结构保持一致：渐进式披露、兼容性 frontmatter、任务路由表、错误签名、仪表盘快捷方式。 内容改进（对照 clerk-docs 参考 页面 + clerk/javascript 中的 @clerk/backend + @clerk/shared 类型交叉引用）： - 权限 slug 与 docs/guides/organizations/control-access/roles-and-permissions.mdx 中的规范 System Permissions 目录对齐： org:sys_{memberships,profile,domains,billing}:{read,manage,delete}。 旧表格引用了非规范名称，在运行时无法匹配 has() 检查。 - createOrganizationInvitation 示例现在包含 inviterUserId， Backend API 参考将其列为人工发起 邀请所必需。 - Enterprise SSO 示例已更新为通过 enterpriseAccounts[i].enterpriseConnection?.provider 访问提供者元数据，与 EnterpriseAccountConnection 类型定义一致。直接对 EnterpriseAccount 使用 .provider 会返回 undefined。 - getOrganizationInvitationList 状态枚举已更新为包含所有 四个文档化值：pending、accepted、revoked、expired。 - 明确呈现 Membership required 与 Membership optional 模式 （自 2025 年 8 月 22 日起默认为 required）。这影响 B2C + B2B 共存，是值得在 错误签名表中指出的静默失败模式。 结构变更： - SKILL.md 423 -> 350 行。框架无关的表述， 以 @clerk/nextjs 作为默认代码风格，并指向其他 SDK （@clerk/react、@clerk/astro、@clerk/vue、@clerk/expo、...）。Next.js 中间件和 redirect() 模式移至 references/nextjs-patterns.md。 - 新增 references/：roles-permissions.md（120）、invitations.md（137）、 enterprise-sso.md（108）、nextjs-patterns.md（146）。均低于 300 行 阈值，符合 skill-creator 指南。 - Frontmatter：inputs: array -> compatibility: string（与 clerk-billing 模式 + skill-creator 约定一致）。版本 2.1.0 -> 3.0.0。 - 新增章节：STOP 前置条件块、Dashboard 快捷方式表、 Error Signatures 表（七行）、What Do You Need? 路由表。 评估： - 评估 2（RBAC）：要求规范的 System Permission slug。 - 评估 5（SSO）：要求 enterpriseConnection?.provider 路径。 - 评估 7（invitations）：要求 inviterUserId + 完整状态枚举。 - 评估 9（新增）：覆盖 Membership 模式前置条件。

fix：为剩余 5 个技能（orgs、backend-api、astro、expo、react-router）添加 See Also

fix：从评估运行同步技能更新 - clerk-chrome-extension-patterns：重大重写（新增引用：create-clerk-client、 headless-extension、sync-host；移除：background-scripts、popup-auth、storage-tokens） - clerk-backend-api：扩展 SKILL.md + 添加评估 - clerk-orgs：扩展 SKILL.md + 添加评估

chore：为重构后的技能提升版本

fix：使所有 18 个技能通过 skills-ref 验证 - 将 inputs/references 移到 metadata 下（非规范顶层字段） - 从 backend-api 移除 argument-hint - 为带冒号的描述加引号（YAML 解析修复） - 重命名文件夹以匹配技能名称（规范要求 clerk- 前缀） - 为 6 个有额外要求的技能添加 compatibility 字段 - 更新 marketplace.json 和文档路径 所有 18 个技能现在均通过：npx skills-ref validate 属于 AIE-750