AgentSkillsCN

workos-authkit-base

在监测OUC系统状态时，若发现异常或变化，可使用此技能。它能自动检测升级事件、审计员池变动、提案状态，并触发相应动作。此技能隶属于自我修正协议AI代理的基础架构。

SKILL.md
--- frontmatter
name: workos-authkit-base
description: Architectural reference for WorkOS AuthKit integrations. Fetch README first for implementation details.

WorkOS AuthKit Base Template

First Action: Fetch README

Before any implementation, fetch the framework-specific README:

code
WebFetch: {sdk-package-name} README from npmjs.com or GitHub

README is the source of truth for: install commands, imports, API usage, code patterns.

Task Structure (Required)

PhaseTaskBlocked ByPurpose
1preflight-Verify env vars, detect framework
2installpreflightInstall SDK package
3callbackinstallCreate OAuth callback route
4providerinstallSetup auth context/middleware
5uicallback, providerAdd sign-in/out UI
6verifyuiBuild confirmation

Decision Trees

Package Manager Detection

code
pnpm-lock.yaml? → pnpm
yarn.lock? → yarn
bun.lockb? → bun
else → npm

Provider vs Middleware

code
Client-side framework? → AuthKitProvider wraps app
Server-side framework? → Middleware handles sessions
Hybrid (Next.js)? → Both may be needed

Callback Route Location

Extract path from WORKOS_REDIRECT_URI → create route at that exact path.

Environment Variables

VariablePurposeWhen Required
WORKOS_API_KEYServer authenticationServer SDKs
WORKOS_CLIENT_IDClient identificationAll SDKs
WORKOS_REDIRECT_URIOAuth callback URLServer SDKs
WORKOS_COOKIE_PASSWORDSession encryption (32+ chars)Server SDKs

Note: Some frameworks use prefixed variants (e.g., NEXT_PUBLIC_*). Check README.

Verification Checklists

After Install

  • • SDK package installed in node_modules
  • • No install errors in output

After Callback Route

  • • Route file exists at path matching WORKOS_REDIRECT_URI
  • • Imports SDK callback handler (not custom OAuth)

After Provider/Middleware

  • • Provider wraps entire app (client-side)
  • • Middleware configured in correct location (server-side)

After UI

  • • Home page shows conditional auth state
  • • Uses SDK functions for sign-in/out URLs

Final Verification

  • • Build completes with exit code 0
  • • No import resolution errors

Error Recovery

Module not found

  • • Verify install completed successfully
  • • Verify SDK exists in node_modules
  • • Re-run install if missing

Build import errors

  • • Delete node_modules, reinstall
  • • Verify package.json has SDK dependency

Invalid redirect URI

  • • Compare route path to WORKOS_REDIRECT_URI
  • • Paths must match exactly

Cookie password error

  • • Verify WORKOS_COOKIE_PASSWORD is 32+ characters
  • • Generate new: openssl rand -base64 32

Auth state not persisting

  • • Verify provider wraps entire app
  • • Check middleware is in correct location

Critical Rules

  1. •Install SDK before writing imports - never create import statements for uninstalled packages
  2. •Use SDK functions - never construct OAuth URLs manually
  3. •Follow README patterns - SDK APIs change between versions
  4. •Extract callback path from env - don't hardcode /auth/callback