AUTH-6795: teach skill about WorkOS Widgets - #42
Conversation
…gration contexts (AUTH-6795) The skill had no awareness of WorkOS Widgets, so in a Clerk-vs-WorkOS bake-off the agent reported WorkOS as lacking pre-built profile/account UI instead of recommending WorkOS Widgets as the equivalent of Clerk's <UserButton />. - workos-migrate-clerk.md: add "Replacing Clerk UI components" mapping table (UserButton/UserProfile/OrganizationSwitcher/OrganizationProfile -> widgets, hosted AuthKit for SignIn/SignUp), a gotcha banning the "no pre-built UI" claim, and widget setup basics (@workos-inc/widgets, WorkOsWidgets provider, CORS, authorization tokens/scopes) - Router SKILL.md: add Widgets + provider-comparison triggers to the skill description and a guardrail that WorkOS HAS pre-built account/profile UI (route implementation to the workos-widgets skill) - workos-terms.md: add a WorkOS Widgets terminology row for Rule 0 lookups - Add migrate-clerk eval cases covering the comparison and migration scenarios so the regression is measurable Refs: AUTH-6795
Greptile SummaryThe PR teaches the WorkOS skill to recommend WorkOS Widgets when users seek Clerk-style pre-built account and organization UI.
Confidence Score: 5/5The PR appears safe to merge. No blocking failure remains. Important Files Changed
Reviews (2): Last reviewed commit: "fix: use correct widget getToken method ..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| | `<OrganizationSwitcher />` | `<OrganizationSwitcher />` widget | | ||
| | `<OrganizationProfile />` / member admin UI | `<UsersManagement />` widget (invite/remove members, change roles) | | ||
|
|
||
| Setup basics for any widget: install `@workos-inc/widgets`, render the `WorkOsWidgets` provider at the app root, configure your app as an allowed web origin (Dashboard → Applications → Sessions tab) so widget requests pass CORS, and supply each widget an authorization token — the AuthKit access token when using `authkit-js`/`authkit-react`, or a backend-generated token via `workos.widgets.createToken({ userId, organizationId, scopes })` (expires after one hour; the User Management widget requires the `widgets:users-table:manage` scope). |
There was a problem hiding this comment.
🔴 Skill guidance names a token-creation call that does not exist, so generated code fails
The new widget setup guidance tells the assistant to fetch a widget authorization token with a call that does not exist (workos.widgets.createToken(...) at plugins/workos/skills/workos/references/workos-migrate-clerk.md:29), when the supported call is workos.widgets.getToken(...), so code produced from this skill breaks at runtime.
Impact: Users following the migration guidance get non-working backend token code and an invented API name — exactly the hallucination these skill files exist to prevent.
Contradiction with the widgets skill's documented SDK surface
The hand-crafted widgets skill documents the backend token call as workos.widgets.getToken({ userId, organizationId, scopes }) (plugins/workos/skills/workos-widgets/references/token-strategies.md:32-49). The two new references introduce createToken instead:
plugins/workos/skills/workos/references/workos-migrate-clerk.md:29plugins/workos/skills/workos/references/workos-terms.md:28
The new eval cases in scripts/eval/cases/migrate-clerk.yaml also do not list createToken as a hallucination, so this will not be caught by the eval gates.
Prompt for agents
The new Widgets guidance added to plugins/workos/skills/workos/references/workos-migrate-clerk.md (line 29) and plugins/workos/skills/workos/references/workos-terms.md (line 28) refers to a backend token call named workos.widgets.createToken. The hand-crafted workos-widgets skill (plugins/workos/skills/workos-widgets/references/token-strategies.md) documents the actual method as workos.widgets.getToken({ userId, organizationId, scopes }). Align both new references with getToken so the router skill does not teach a non-existent SDK method, and consider adding 'createToken' to the hallucinations list of the new eval cases in scripts/eval/cases/migrate-clerk.yaml so regressions are caught.
Was this helpful? React with 👍 or 👎 to provide feedback.
| | `<OrganizationSwitcher />` | `<OrganizationSwitcher />` widget | | ||
| | `<OrganizationProfile />` / member admin UI | `<UsersManagement />` widget (invite/remove members, change roles) | | ||
|
|
||
| Setup basics for any widget: install `@workos-inc/widgets`, render the `WorkOsWidgets` provider at the app root, configure your app as an allowed web origin (Dashboard → Applications → Sessions tab) so widget requests pass CORS, and supply each widget an authorization token — the AuthKit access token when using `authkit-js`/`authkit-react`, or a backend-generated token via `workos.widgets.createToken({ userId, organizationId, scopes })` (expires after one hour; the User Management widget requires the `widgets:users-table:manage` scope). |
There was a problem hiding this comment.
🔍 New guidance hardcodes a Dashboard click-path the router's own guardrail forbids
The setup sentence instructs the agent to configure allowed web origins at "Dashboard → Applications → Sessions tab". The router's guardrail in plugins/workos/skills/workos/SKILL.md:26 explicitly says never to state Dashboard click-paths unless verified against a just-fetched docs page, because the Dashboard reorganizes. Verify this path against https://workos.com/docs/widgets or describe the destination conceptually plus the docs URL.
Was this helpful? React with 👍 or 👎 to provide feedback.
| | Clerk component | WorkOS equivalent | | ||
| | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `<SignIn />` / `<SignUp />` | AuthKit hosted sign-in page (redirect-based, not an embeddable component); brand it in the Dashboard | | ||
| | `<UserButton />` | The account UI behind it maps to the `<UserProfile />` and `<UserSecurity />` widgets; sign-out is handled by AuthKit session helpers | | ||
| | `<UserProfile />` | `<UserProfile />`, `<UserSecurity />`, and `<UserSessions />` widgets (profile info, password/MFA, active sessions) | | ||
| | `<OrganizationSwitcher />` | `<OrganizationSwitcher />` widget | | ||
| | `<OrganizationProfile />` / member admin UI | `<UsersManagement />` widget (invite/remove members, change roles) | |
There was a problem hiding this comment.
🔍 Widget component names in the new mapping are broader than what the widgets skill documents
The mapping table asserts <UserSecurity />, <UserSessions />, <UsersManagement />, and <OrganizationSwitcher /> widgets exist, but the hand-crafted widgets skill only covers four widget targets (user-management, user-profile, admin-portal-sso-connection, admin-portal-domain-verification, see plugins/workos/skills/workos-widgets/SKILL.md:11) and its endpoint tables only expose UserManagement and UserProfile surfaces (plugins/workos/skills/workos-widgets/references/fetching-apis.md:58-87). If the extra component names are correct per current docs, the two skills now disagree on the catalog; if not, they are hallucinated exports. Worth confirming against https://workos.com/docs/widgets.
Was this helpful? React with 👍 or 👎 to provide feedback.
| antiPatterns: | ||
| - build that UI from scratch | ||
| - no pre-built UI | ||
| - no equivalent |
There was a problem hiding this comment.
🔍 Eval anti-pattern strings may be neutralized by the negation-aware scorer
antiPatterns entries like "no equivalent" and "no pre-built UI" are matched with isNegated lookback (scripts/eval/scorer.ts:290-310), which treats a preceding "not"/"never"/"don't" within 30 chars as a non-hit. A with-skill answer such as "it's not true that there is no equivalent" would be ignored, but so would many legitimate phrasings — more importantly, an incorrect answer phrased "WorkOS does not have an equivalent" contains "not ... equivalent" and could be suppressed, weakening these two cases' ability to detect the exact failure mode the PR targets.
Was this helpful? React with 👍 or 👎 to provide feedback.
…Dashboard click-path Addresses Greptile review comments on PR #42 (AUTH-6795): - Replace workos.widgets.createToken with workos.widgets.getToken in workos-migrate-clerk.md and workos-terms.md (per token-strategies.md) - Replace hardcoded Dashboard click-path with conceptual description and stable docs URL (https://workos.com/docs/widgets) - Add workos.widgets.createToken to migrate-clerk eval hallucinations so the regression is caught by eval gates
1 participant
bosun task: AUTH-6795: teach skill about WorkOS Widgets
Task id: task-msh08vze-pqej
Shape: ship
Project: workos/skills