Claude-skill-registry clerk-token-ops

Automates Clerk JWT token generation, validation, and export for FastAPI integration tests. Use when an agent must refresh tokens, verify JWT templates, or unblock authentication workflows without breaking environment state.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/clerk-token-ops" ~/.claude/skills/majiayu000-claude-skill-registry-clerk-token-ops && rm -rf "$T"

manifest: skills/data/clerk-token-ops/SKILL.md

source content

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

Set-ClerkToken.ps1

safely.

Guardrails (Do This Before Anything Else)

Never copy Markdown links into the terminal. Always use raw paths like
```
scripts/Set-ClerkToken.ps1
```
.
Use real Clerk user IDs (e.g.,
user_35KgiAcvIC0tdtFvJUN1vDkrNYc
). Angle brackets or placeholders break PowerShell parsing.

Confirm
.env.local
exists and contains

CLERK_SECRET_KEY

CLERK_ISSUER

CLERK_PEM_PUBLIC_KEY

, and

CLERK_ISSUER_ID

Restart FastAPI after changing
```
.env.local
```
; environment variables load only once per process.
Tokens expire in ~60 seconds. Chain generation and testing without delay.

Core Workflow

Validate Environment
- Run
```
Test-Path .env.local
```
  and open the file if missing keys.
- Ensure
```
CLERK_JWT_AUDIENCE
```
  stays commented out; session tokens lack
```
aud
```
  .
Inspect Available JWT Templates
- ```
powershell -File .\scripts\Set-ClerkToken.ps1 -ListTemplates
```
- Confirm
```
server-token
```
  exists; if missing, create it in the Clerk dashboard with RS256 signing.

Generate & Export Token

powershell -File .\scripts\Set-ClerkToken.ps1 -UserId <ACTUAL_USER_ID> -Template server-token [-Persist]

Expect: "CLERK_TOKEN exported..." and optional persistence notice.

Verify Token Availability

```
echo $env:CLERK_TOKEN
```

Optional:

python scripts/get_clerk_token.py --env-file .env.local --user-id ... --template server-token --print-session

for debugging.

Run Target Tests or API Calls Immediately

Example test harness:

uv run python main/scripts/test_clerk_auth.py "$env:CLERK_TOKEN" fixtures/test_urs.txt

For curl:

curl -H "Authorization: Bearer $env:CLERK_TOKEN" http://localhost:8000/jobs -d @payload.json -H "Content-Type: application/json"

Audit & Log Verification
- Tail
```
logs/audit/jobs/audit_*.jsonl
```
  to ensure the
```
sub
```
  (user ID) and
```
token_iat
```
  fields are captured (ALCOA+ compliance).

Quality Checklist

```
.env.local
```
contains correct Clerk keys and issuer URLs.
```
scripts/get_clerk_token.py
```
runs without HTTP errors and prints JWT.
```
scripts/Set-ClerkToken.ps1
```
outputs success messages (no
```
[System.Char]
```
errors).
```
$env:CLERK_TOKEN
```
is non-empty and recent (
```
token_iat
```
within 60 seconds).
FastAPI endpoint returns 201/200 with token, 401 without token (negative test).
Audit log entry includes
```
user_id
```
from JWT
```
sub
```
claim.

Troubleshooting Matrix

Symptom	Root Cause	Fix
`Method invocation failed because [System.Char] does not contain a method named 'Trim'`	PowerShell treated helper output as char array	Use the patched `Set-ClerkToken.ps1` (Nov 2025). If issue recurs, wrap extraction with `[string]` and ensure token line exists.
`Unable to parse JWT from helper output`	Helper didnt emit token (HTTP error, wrong template, or env vars missing)	Re-run helper with `--print-session` and check `.env.local` secrets; confirm template name matches exactly.
`Token validation failed: Token is missing the "aud" claim`	Audience verification enabled	Comment out `CLERK_JWT_AUDIENCE` and ensure JWT decode options set `verify_aud=False` .
`401 Unauthorized: Token expired`	Delay between generation and use	Regenerate token and chain tests immediately (<60s). Automate generation/test pipeline if needed.
`500 Internal Server Error: Authentication system not configured`	FastAPI didnt load `.env.local`	Load dotenv at the top of `main/api/app.py` before other imports; restart server.

Example Session (Copy/Paste Ready)

# 1. List templates (sanity check)
powershell -File .\scripts\Set-ClerkToken.ps1 -ListTemplates

# 2. Export fresh token for known test user
powershell -File .\scripts\Set-ClerkToken.ps1 -UserId user_35KgiAcvIC0tdtFvJUN1vDkrNYc -Template server-token -Persist

# 3. Verify environment
$env:CLERK_TOKEN

# 4. Exercise FastAPI endpoint (token expires fast!)
uv run python main/scripts/test_clerk_auth.py "$env:CLERK_TOKEN" fixtures/test_urs.txt

# 5. Tail audit logs for attribution
Get-Content logs/audit/jobs/audit_$(Get-Date -Format yyyyMMdd).jsonl -Tail 3

Extension Hooks

If tests require Docker Compose: run

docker compose -f docker-compose.dev.yml up --build api worker

after refreshing tokens.

CI usage: Wrap helper invocation inside a temporary PowerShell profile so
```
$env:CLERK_TOKEN
```
is available to downstream
```
pytest
```
or
```
uv run
```
commands.
Documentation updates: When procedures change, sync with
```
main/docs/guides/CLERK_INTEGRATION_TESTING.md
```
and note version in this skill.

References

```
scripts/get_clerk_token.py
```
- Python helper hitting Clerk Backend API.
```
scripts/Set-ClerkToken.ps1
```
- PowerShell wrapper for Windows devs.

main/docs/guides/CLERK_INTEGRATION_TESTING.md

- Deep dive guide.

Anthropic Agent Skills best practices (2025-10-02 spec) for structure and activation cues.

Maintainer: Compliance/Test Enablement Team
Last Updated: 2025-11-16
Status: ✅ Ready for Claude Code agents