🇺🇸English
WorkOS Widgets
Workflow Overview
- Identify widget target from the user request (
user-management, user-profile, admin-portal-sso-connection, admin-portal-domain-verification).
- Scan project files in this order:
- package/dependency manifests
- framework/router entrypoints
- auth/token utilities
- styling/component patterns
- Detect stack, data-layer style, styling, component system, and package manager using references/detection.md.
- Check for AuthKit/WorkOS presence:
- if detected, continue;
- if not detected, ask the user to run
npx workos@latest install, wait for confirmation, then continue.
- If detection is ambiguous or conflicting, ask one focused question, then continue.
- Load only the relevant reference files for the detected stack and widget.
- Implement integration based on stack shape:
- frontend route/page + widget component when widget UI lives in the same app
- token endpoint/service + client integration surface when backend-first/multi-app architecture is detected
- Validate routing/wiring, imports, and token/API usage before finishing.
Canonical Inputs
Accept these inputs from the user request when available:
- widget type (or infer from request intent)
- optional component path
- optional page/route path
- optional token endpoint/service preference
- optional constraints (for example: avoid broad refactors)
When input is missing, infer from existing project conventions and detected stack.
Detection and Ambiguity Protocol
- Apply detection heuristics from references/detection.md.
- Explore before asking. Ask only when ambiguity remains after checking manifests and route/auth entrypoints.
- Ask a single concrete question that resolves one decision.
- Default to the strongest detected ownership signals when no user response is available.
- When installs are required, use the package manager detected from project files/lockfiles.
Reference Loading Map
Always load these core references:
For React/TypeScript stacks (Next.js, React Router, TanStack Router, TanStack Start, Vite), also load:
Load stack-specific reference guidance:
Then load exactly one widget reference:
Global Widget Guidance
-
Implement widget operations using endpoint paths/methods from references/fetching-apis.md. When building request bodies or parsing responses, query the OpenAPI spec for the relevant widget's schemas:
node references/scripts/query-spec.cjs --widget <widget-name>
Use --list to see available widget groups.
- Keep loading, empty, and error states explicit and user-visible.
- Keep mutation outcomes visible and refresh/reload affected data after successful changes.
- Align table/list/action UI with existing project conventions.
- Keep behavior resilient for partial/optional data and avoid brittle UI assumptions.
Core Guidelines
- Reuse existing domain types from the host project and OpenAPI schemas; avoid duplicating model definitions.
- Build widget requests using references/fetching-apis.md for paths, methods, and schema queries.
- Use direct
fetch/HTTP calls (or equivalent server HTTP client) for endpoint calls.
- Implement a consistent authorization layer for widget requests, including elevated-token handling for sensitive endpoints when required.
- If the app already uses React Query or SWR, use them as orchestration/cache layers around those direct calls.
- For React/TypeScript widget code quality expectations, follow references/react-ts-standards.md.
- If AuthKit/WorkOS is missing, prompt the user to run
npx workos@latest install before continuing.
- Install additional dependencies only when strictly necessary, using the detected package manager/tooling.
- Keep server-state handling aligned with the selected data-layer approach.
- Use local state/reducers for UI interaction state as needed.
- Prefer existing design system and styling conventions.
- Avoid broad unrelated refactors and global style rewrites.
Completion Requirements
Before finishing, verify all relevant items:
- Widget component exists and accepts
accessToken: string when component-level integration is in scope.
- Route/page wiring is complete when route integration is in scope.
- Token source matches existing app architecture (AuthKit client flow or backend WorkOS token flow).
- API methods and paths match the bundled OpenAPI spec, and data-layer usage matches project conventions.
- Loading and error branches exist for required query/mutation flows.
Validation Checklist
- Confirm endpoint paths and HTTP methods come from the bundled OpenAPI spec.
- Confirm request/response handling follows schema expectations from the spec.
- Confirm query/mutation invalidation/refetch is applied after successful mutations where required.
- Confirm empty/error/loading states are explicit and user-visible.
- Confirm package installs (if any) used the detected package manager/tooling.
- Confirm implementation stays aligned with existing codebase conventions.
- Confirm no existing component has been passed
className or style props to override its built-in styling. Use each component as-is or via its own props API (variant, size, etc.).
Weekly Installs
54
Repository
workos/skills
GitHub Stars
6
First Seen
Feb 10, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
opencode54
codex53
gemini-cli52
github-copilot52
amp52
kimi-cli52
