home / skills / omer-metin / skills-for-antigravity / clerk-auth

clerk-auth skill

safe

This skill helps implement Clerk authentication and multi-tenant patterns with best-practice middleware, user sync, and webhooks across services.

npx playbooks add skill omer-metin/skills-for-antigravity --skill clerk-auth

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

1.2 KB

---
name: clerk-auth
description: Expert patterns for Clerk auth implementation, middleware, organizations, webhooks, and user syncUse when "adding authentication, clerk auth, user authentication, sign in, sign up, user management, multi-tenancy, organizations, sso, single sign-on, clerk, authentication, auth, user-management, multi-tenancy, organizations, sso, oauth" mentioned. 
---

# Clerk Auth

## Identity



## Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

* **For Creation:** Always consult **`references/patterns.md`**. This file dictates *how* things should be built. Ignore generic approaches if a specific pattern exists here.
* **For Diagnosis:** Always consult **`references/sharp_edges.md`**. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
* **For Review:** Always consult **`references/validations.md`**. This contains the strict rules and constraints. Use it to validate user inputs objectively.

**Note:** If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Overview

This skill provides expert implementation patterns for Clerk authentication in Python projects, covering middleware, organizations, webhooks, SSO, and user synchronization. It focuses on practical, secure patterns and points you to the exact reference files you must consult for creation, diagnosis, and validation. Use it to implement reliable sign-in/sign-up flows, multi-tenant organizations, and safe webhook handling.

How this skill works

When creating auth components, always follow the canonical patterns in references/patterns.md to build middleware, routes, and sync logic. For diagnosing failures or edge cases, consult references/sharp_edges.md to identify root causes and risks such as token replay, race conditions, or incorrect session handling. For any review or validation step, use references/validations.md to check constraints, required fields, and invariant rules before deployment.

When to use it

Adding Clerk to a new or existing Python web app (sign in / sign up flows)
Implementing organization or multi-tenant access control with Clerk
Building middleware to protect routes and enforce session or role checks
Syncing users between Clerk and an internal database or background jobs
Handling Clerk webhooks securely and reconciling user state

Best practices

Always follow references/patterns.md for implementation patterns; avoid ad-hoc solutions.
Validate incoming webhook payloads and signatures per references/validations.md before acting.
Use middleware to centralize session and role checks; keep handlers idempotent to avoid race conditions.
Design user-sync jobs with backoff and deduplication; record source-of-truth timestamps to resolve conflicts.
Test edge cases from references/sharp_edges.md (expired tokens, concurrent updates, deleted orgs) and document mitigations.

Example use cases

Protect API endpoints with Clerk session middleware that verifies tokens and sets user context.
Implement organization membership checks before granting access to tenant resources.
Build a webhook consumer that validates the signature, queues a user-sync job, and updates internal profiles safely.
Create an SSO integration flow that exchanges provider assertions for Clerk sessions and enforces MFA policies.
Run nightly reconciliation that compares Clerk users to internal records and resolves mismatches using validation rules.

FAQ

Which file should I consult to design auth flows?

Consult references/patterns.md first; it contains the canonical patterns for creating middleware, routes, and sync logic.

How do I diagnose strange session behaviors?

Use references/sharp_edges.md to identify common failure modes and their root causes; it lists precise scenarios like token replay and race conditions to check.