Clerk Token Operations

Overview

This skill gives Claude Code agents a repeatable, zero-surprise playbook for generating Clerk JWTs, exporting them into the Windows PowerShell environment, and validating authentication against the FastAPI backend. It encodes the exact fixes from the November 2025 incidents (missing templates, parser errors, stale tokens) so future runs avoid the same failures.

Activation Signals

Use this skill whenever the task involves:

• Minting or refreshing Clerk JWTs for integration, smoke, or load tests.
• Investigating 401 responses due to expired or malformed tokens.
• Ensuring .env.local and PowerShell sessions stay in sync (CLERK_SECRET_KEY, CLERK_TOKEN).
• Listing or validating Clerk JWT templates (e.g., server-token).
• Teaching another agent how to run scripts/get_clerk_token.py or Set-ClerkToken.ps1 safely.

Guardrails (Do This Before Anything Else)

1. Never copy Markdown links into the terminal. Always use raw paths like scripts/Set-ClerkToken.ps1.
2. Use real Clerk user IDs (e.g., user_35KgiAcvIC0tdtFvJUN1vDkrNYc). Angle brackets or placeholders break PowerShell parsing.
3. Confirm .env.local exists and contains CLERK_SECRET_KEY, CLERK_ISSUER, CLERK_PEM_PUBLIC_KEY, and CLERK_ISSUER_ID.
4. Restart FastAPI after changing .env.local; environment variables load only once per process.
5. Tokens expire in ~60 seconds. Chain generation and testing without delay.