feat: multi-SDK expansion with auto-discovery registry

skills/workos-authkit-sveltekit/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: workos-authkit-sveltekit
+description: Integrate WorkOS AuthKit with SvelteKit. Server-side authentication with hooks and file-based routing.
+---
+
+# WorkOS AuthKit for SvelteKit
+
+## Step 1: Fetch SDK Documentation (BLOCKING)
+
+**STOP. Do not proceed until complete.**
+
+WebFetch: `https://github.com/workos/authkit-sveltekit/blob/main/README.md`
+
+The README is the source of truth. If this skill conflicts with README, follow README.
+
+## Step 2: Pre-Flight Validation
+
+### Project Structure
+
+- Confirm `svelte.config.js` (or `svelte.config.ts`) exists
+- Confirm `package.json` contains `@sveltejs/kit` dependency
+- Confirm `src/routes/` directory exists
+
+### Environment Variables
+
+Check `.env` or `.env.local` for:
+
+- `WORKOS_API_KEY` - starts with `sk_`
+- `WORKOS_CLIENT_ID` - starts with `client_`
+- `WORKOS_REDIRECT_URI` - valid callback URL
+- `WORKOS_COOKIE_PASSWORD` - 32+ characters
+
+SvelteKit uses `$env/static/private` and `$env/dynamic/private` natively. The agent should write env vars to `.env` (SvelteKit's default) or `.env.local`.
+
+## Step 3: Install SDK
+
+Detect package manager, install SDK package from README.
+
+```
+pnpm-lock.yaml? → pnpm add @workos-inc/authkit-sveltekit
+yarn.lock? → yarn add @workos-inc/authkit-sveltekit
+bun.lockb? → bun add @workos-inc/authkit-sveltekit
+else → npm install @workos-inc/authkit-sveltekit
+```
+
+**Verify:** SDK package exists in node_modules before continuing.
+
+## Step 4: Configure Server Hooks
+
+SvelteKit uses `src/hooks.server.ts` for server-side middleware. This is where the AuthKit handler is registered.
+
+Create or update `src/hooks.server.ts` with the authkit handle function from the README.
+
+### Existing Hooks (IMPORTANT)
+
+If `src/hooks.server.ts` already exists with custom logic, use SvelteKit's `sequence()` helper to compose hooks:
+
+```typescript
+import { sequence } from '@sveltejs/kit/hooks';
+import { authkitHandle } from '@workos-inc/authkit-sveltekit'; // Check README for exact export
+
+export const handle = sequence(authkitHandle, yourExistingHandle);
+```
+
+Check README for the exact export name and usage pattern.
+
+## Step 5: Create Callback Route
+
+Parse `WORKOS_REDIRECT_URI` to determine route path:
+
+```
+URI path          --> Route location
+/callback         --> src/routes/callback/+server.ts
+/auth/callback    --> src/routes/auth/callback/+server.ts
+```
+
+Use the SDK's callback handler from the README. Do not write custom OAuth logic.
+
+**Critical:** SvelteKit uses `+server.ts` for API routes, not `+page.server.ts`.
+
+## Step 6: Layout Setup
+
+Update `src/routes/+layout.server.ts` to load the auth session and pass it to all pages.
+
+Check README for the exact pattern — typically a `load` function that returns the user session from locals.
+
+```typescript
+// src/routes/+layout.server.ts
+import type { LayoutServerLoad } from './$types';
+
+export const load: LayoutServerLoad = async (event) => {
+  // Check README for exact API — session is typically on event.locals
+  return {
+    user: event.locals.user, // or similar from README
+  };
+};
+```
+
+## Step 7: UI Integration
+
+Add auth UI to `src/routes/+page.svelte` using the session data from the layout.
+
+- Show user info when authenticated
+- Show sign-in link/button when not authenticated
+- Add sign-out functionality
+
+Check README for sign-in URL generation and sign-out patterns.
+
+## Verification Checklist (ALL MUST PASS)
+
+Run these commands to confirm integration. **Do not mark complete until all pass:**
+
+```bash
+# 1. Check hooks.server.ts exists and has authkit
+grep -i "workos\|authkit" src/hooks.server.ts || echo "FAIL: authkit missing from hooks.server.ts"
+
+# 2. Check callback route exists
+find src/routes -name "+server.ts" -path "*/callback/*"
+
+# 3. Check layout loads auth session
+grep -i "user\|auth\|session" src/routes/+layout.server.ts || echo "FAIL: auth session missing from layout"
+
+# 4. Build succeeds
+pnpm build || npm run build
+```
+
+## Error Recovery
+
+### "Cannot find module '@workos-inc/authkit-sveltekit'"
+
+- Check: SDK installed before writing imports
+- Check: SDK package directory exists in node_modules
+- Re-run install if missing
+
+### hooks.server.ts not taking effect
+
+- Check: File is at `src/hooks.server.ts`, not `src/hooks.ts` or elsewhere
+- Check: Named export is `handle` (SvelteKit requirement)
+- Check: If using `sequence()`, all handles are properly composed
+
+### Callback route not found (404)
+
+- Check: File uses `+server.ts` (not `+page.server.ts`)
+- Check: Route path matches `WORKOS_REDIRECT_URI` path exactly
+- Check: Exports `GET` handler (SvelteKit convention)
+
+### "locals" type errors
+
+- Check: App.Locals interface is augmented in `src/app.d.ts`
+- Check README for TypeScript setup instructions
+
+### Cookie password error
+
+- Verify `WORKOS_COOKIE_PASSWORD` is 32+ characters
+- Generate new: `openssl rand -base64 32`
+
+### Auth state not available in pages
+
+- Check: `+layout.server.ts` load function returns user data
+- Check: Pages access data via `export let data` (Svelte 4) or `$page.data` (Svelte 5)

skills/workos-dotnet/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: workos-dotnet
+description: Integrate WorkOS AuthKit with .NET (ASP.NET Core). Backend authentication with DI registration, auth endpoints, and appsettings configuration.
+---
+
+# WorkOS AuthKit for .NET (ASP.NET Core)
+
+## Step 1: Fetch SDK Documentation (BLOCKING)
+
+**STOP. Do not proceed until complete.**
+
+WebFetch: `https://raw.githubusercontent.com/workos/workos-dotnet/main/README.md`
+
+The README is the source of truth for SDK API usage. If this skill conflicts with README, follow README.
+
+## Step 2: Pre-Flight Validation
+
+### Project Structure
+
+- Confirm a `*.csproj` file exists in the project root
+- Detect project style:
+  - **Minimal API** (modern): `Program.cs` with `WebApplication.CreateBuilder()` — .NET 6+
+  - **Startup pattern** (older): `Startup.cs` with `ConfigureServices()` / `Configure()` — .NET 5 and earlier
+
+This detection determines WHERE to register WorkOS services and middleware.
+
+### Environment Variables
+
+Check `appsettings.Development.json` for:
+
+- `WORKOS_API_KEY` — starts with `sk_`
+- `WORKOS_CLIENT_ID` — starts with `client_`
+
+## Step 3: Install SDK
+
+```bash
+dotnet add package WorkOS.net
+```
+
+**Verify:** Check the `*.csproj` file contains a `<PackageReference Include="WorkOS.net"` entry.
+
+If `dotnet` CLI is not available, stop and inform the user to install the .NET SDK.
+
+## Step 4: Configure WorkOS Client
+
+### Minimal API Pattern (Program.cs)
+
+Add WorkOS configuration to `Program.cs`:
+
+1. Read WorkOS settings from `IConfiguration`
+2. Register the WorkOS client in the DI container
+3. The WorkOS client needs API key for initialization
+
+```csharp
+// In Program.cs, after builder creation:
+var workosApiKey = builder.Configuration["WorkOS:ApiKey"];
+var workosClientId = builder.Configuration["WorkOS:ClientId"];
+```
+
+### Startup Pattern (Startup.cs)
+
+Add to `ConfigureServices()`:
+
+1. Read WorkOS settings from `IConfiguration`
+2. Register services
+
+Choose the pattern that matches the detected project structure.
+
+## Step 5: Create Authentication Endpoints
+
+Create auth endpoints following the WorkOS AuthKit pattern. Use minimal API `app.MapGet()` for minimal API projects, or a Controller for Startup-pattern projects.
+
+### Required Endpoints
+
+**GET /auth/login** — Redirect to WorkOS AuthKit:
+
+- Use the WorkOS SDK to generate an authorization URL
+- Include `clientId`, `redirectUri`, and `provider: "authkit"` parameters
+- Redirect the user to the authorization URL
+
+**GET /auth/callback** — Handle OAuth callback:
+
+- Extract `code` from query parameters
+- Exchange authorization code for user profile using the WorkOS SDK
+- Store user info in session or cookie
+- Redirect to home page
+
+**GET /auth/logout** — Clear session:
+
+- Clear the authentication session/cookie
+- Redirect to home page
+
+### Session Management
+
+Use ASP.NET Core's built-in session or cookie authentication:
+
+```csharp
+// Enable session middleware in Program.cs
+builder.Services.AddDistributedMemoryCache();
+builder.Services.AddSession();
+// ...
+app.UseSession();
+```
+
+## Step 6: Environment Setup
+
+Configure `appsettings.Development.json` with WorkOS credentials:
+
+```json
+{
+  "WorkOS": {
+    "ApiKey": "<WORKOS_API_KEY value>",
+    "ClientId": "<WORKOS_CLIENT_ID value>",
+    "RedirectUri": "http://localhost:5000/auth/callback"
+  }
+}
+```
+
+Use the actual credential values provided in the environment context.
+
+**Important:** Do NOT put secrets in `appsettings.json` (committed to git). Use `appsettings.Development.json` (gitignored) or `dotnet user-secrets`.
+
+## Step 7: Verification
+
+Run these checks — **do not mark complete until all pass:**
+
+```bash
+# 1. Check WorkOS.net is in csproj
+grep -i "WorkOS" *.csproj
+
+# 2. Check auth endpoints exist
+grep -r "auth/login\|auth/callback\|auth/logout" *.cs
+
+# 3. Build succeeds
+dotnet build
+```
+
+**If build fails:** Read the error output carefully. Common issues:
+
+- Missing `using` statements for WorkOS namespaces
+- Incorrect DI registration order
+- Missing session/cookie middleware registration
+
+## Error Recovery
+
+### "dotnet: command not found"
+
+- .NET SDK is not installed. Inform the user to install from https://dotnet.microsoft.com/download
+
+### NuGet restore failures
+
+- Check internet connectivity
+- Try `dotnet restore` explicitly before `dotnet build`
+
+### "No project file found"
+
+- Ensure you're in the correct directory with a `*.csproj` file
+
+### Build errors after integration
+
+- Check that all `using` statements are correct
+- Verify DI registration order (services before middleware)
+- Ensure `app.UseSession()` is called before mapping auth endpoints