Communitygithub.com

deangilmoreremix/videoremix.vip2

Explorador y ejecutor de la API REST de Clerk Backend. Navega por etiquetas, inspecciona esquemas de endpoints y ejecuta solicitudes autenticadas. Úsalo para listar usuarios, gestionar organizaciones o llamar a cualquier endpoint de la API de Clerk.

¿Qué es videoremix.vip2?

Este skill está diseñado para interactuar con la API Backend de Clerk, permitiendo a un agente de IA (como Claude Code, Cursor o Codex) explorar, inspeccionar y ejecutar solicitudes de forma segura. Su función principal es agilizar el desarrollo con Clerk al proporcionar una interfaz directa para operaciones comunes —como listar usuarios, crear organizaciones, invitar miembros y actualizar metadatos— sin necesidad de obtener especificaciones previas. El skill sigue una serie de controles de seguridad obligatorios antes de cualquier operación de escritura (POST/PATCH/PUT/DELETE): verifica que la clave secreta (`CLERK_SECRET_KEY`) esté configurada, comprueba los alcances (`CLERK_BAPI_SCOPES`) y, en eliminaciones, exige una advertencia explícita sobre la irreversibilidad de la acción. Proporciona una "Ruta Rápida" con comandos `curl` directos y sus equivalentes en SDK para proyectos Next.js/TypeScript, así como una referencia completa de endpoints para usuarios y organizaciones. Además, el skill incluye modos de operación (ayuda, exploración, ejecución y detalle) que se activan según el prompt del usuario, y contempla consideraciones importantes como límites de tasa, diferencias entre metadatos (públicos, privados e inseguros) y la advertencia de que las actualizaciones de metadatos son reemplazos completos, no fusiones.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/deangilmoreremix/videoremix.vip2/tree/HEAD/.agents/skills/clerk-backend-api

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Contexto de opciones

Prompt del usuario: $ARGUMENTS

CRÍTICO: Verificaciones obligatorias antes de CADA solicitud de escritura

Antes de cualquier POST / PATCH / PUT / DELETE, DEBES hacer TODO lo siguiente en tu respuesta:

  1. Verificar CLERK_SECRET_KEY — comprueba que esté configurada:

    echo $CLERK_SECRET_KEY | head -c 10
    

    Si está vacía, detente y pregúntale al usuario. No continúes sin una clave válida.

  2. Verificar CLERK_BAPI_SCOPES — ejecuta:

    echo $CLERK_BAPI_SCOPES
    

    Inspecciona la salida. Si faltan alcances o no incluyen el permiso de escritura requerido, dile al usuario: "Esta es una operación de escritura y tus alcances actuales pueden no permitirla. ¿Reejecutar con --admin para omitir?" NO intentes la solicitud y falles: pregunta primero.

  3. Para solicitudes DELETE: advierte explícitamente que la acción es IRREVERSIBLE y enumera exactamente qué datos se destruirán permanentemente (registro de usuario, todas las sesiones, todas las membresías, todos los datos asociados). Requiere confirmación explícita antes de continuar. Esta advertencia es OBLIGATORIA: nunca la omitas.

  4. Para operaciones de metadatos: explica siempre qué tipo de metadato se está usando y por qué (consulta la sección Tipos de metadatos más abajo).


RUTA RÁPIDA: Operaciones comunes (úsalas directamente, sin necesidad de obtener especificaciones)

Para las siguientes operaciones, omite la obtención de especificaciones y ejecuta inmediatamente usando estas plantillas exactas. Sustituye $CLERK_SECRET_KEY, $USER_ID, $ORG_ID, $EMAIL según sea necesario del contexto del usuario.

Crear organización + invitar miembro (dos pasos)

# Paso 1 — Crear organización
ORG=$(curl -s -X POST "https://api.clerk.com/v1/organizations" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"Acme Corp\", \"created_by\": \"$USER_ID\"}")
echo "$ORG" | python3 -c "import sys,json; d=json.load(sys.stdin); print(json.dumps(d, indent=2))"

# Paso 2 — Extraer ID de la organización
ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# Paso 3 — Invitar miembro con rol
curl -s -X POST "https://api.clerk.com/v1/organizations/${ORG_ID}/invitations" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"email_address\": \"[email protected]\", \"role\": \"org:admin\"}" \
  | python3 -c "import sys,json; print(json.dumps(json.load(sys.stdin), indent=2))"

Roles: usa "org:admin" o "org:member" (siempre con el prefijo org:).

Equivalente en SDK (para proyectos Next.js / TypeScript con @clerk/nextjs o @clerk/backend)

import { clerkClient } from '@clerk/nextjs/server'
// O si usas @clerk/backend directamente:
// import { createClerkClient } from '@clerk/backend'
// const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })

// Paso 1: Crear organización
const org = await clerkClient.organizations.createOrganization({
  name: 'Acme Corp',
  createdBy: userId,  // requerido — el ID del usuario que crea la organización
})

// Paso 2: Invitar miembro a la organización
const invitation = await clerkClient.organizations.createOrganizationInvitation({
  organizationId: org.id,
  emailAddress: '[email protected]',
  role: 'org:admin',  // o 'org:member'
})

Actualizar metadatos de usuario

Explica siempre los tres tipos de metadatos antes de preguntar cuál usar:

TipoCampoLegible porEscribible porÚsalo para
Públicopublic_metadataCliente + ServidorSolo servidorNivel de plan, roles, flags de funcionalidad que el frontend lee
Privadoprivate_metadataSolo servidorSolo servidorIDs de Stripe, flags de cumplimiento, identificadores internos
Insegurounsafe_metadataCliente + ServidorCliente + ServidorEstado efímero de la interfaz, pasos de onboarding (escribible por el cliente: evita datos sensibles)

Para plan: 'pro' y onboarded: true — usa public_metadata (legible por el frontend, escribible por el servidor):

curl -s -X PATCH "https://api.clerk.com/v1/users/${USER_ID}" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public_metadata": {"plan": "pro", "onboarded": true}}' \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Usuario {d[\"id\"]} actualizado: public_metadata={d.get(\"public_metadata\")}')"

Equivalente en SDK:

import { clerkClient } from '@clerk/nextjs/server'
// O: import { createClerkClient } from '@clerk/backend'

await clerkClient.users.updateUser(userId, {
  publicMetadata: { plan: 'pro', onboarded: true },   // legible por el cliente, escribible solo por el servidor
  // privateMetadata: { stripeId: 'cus_xxx' },         // solo servidor para lectura y escritura
  // unsafeMetadata: { step: 'welcome' },              // escribible por el cliente, evita datos sensibles
})

Nota: La API REST usa snake_case (public_metadata). El SDK usa camelCase (publicMetadata).

Listar usuarios (últimos 7 días)

curl -s "https://api.clerk.com/v1/users?limit=100&offset=0&order_by=-created_at&created_at=gt:$(date -d '7 days ago' +%s 2>/dev/null || date -v-7d +%s)000" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY" \
  | python3 -c "
import sys, json
data = json.load(sys.stdin)
if isinstance(data, list):
    print(f'Se encontraron {len(data)} usuarios:')
    for u in data:
        print(f'  {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"sin correo\")}')
else:
    print(json.dumps(data, indent=2))
"

Eliminar usuario (confirmación requerida)

# SOLO ejecutar después de la confirmación explícita del usuario
curl -s -X DELETE "https://api.clerk.com/v1/users/${USER_ID}" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Eliminado: {d}')"

Referencia completa de endpoints de la API Backend de Clerk

URL base: https://api.clerk.com/v1 Autenticación: Authorization: Bearer $CLERK_SECRET_KEY en cada solicitud.

Usuarios

Listar usuarios

GET /v1/users
Parámetros de consulta: limit (máx. 500, predet. 10), offset, order_by (+/-created_at, +/-updated_at, +/-email_address, +/-web3wallet, +/-first_name, +/-last_name, +/-phone_number, +/-username, +/-last_active_at, +/-last_sign_in_at), email_address[], phone_number[], username[], web3wallet[], user_id[], query, created_at (rango ISO 8601: gt:TIMESTAMP o lt:TIMESTAMP en ms Unix)
Devuelve: array de objetos User

Obtener usuario

GET /v1/users/{user_id}
Devuelve: objeto User

Actualizar usuario

PATCH /v1/users/{user_id}
Cuerpo (JSON, snake_case): { public_metadata, private_metadata, unsafe_metadata, first_name, last_name, username, ... }

Eliminar usuario — IRREVERSIBLE

DELETE /v1/users/{user_id}
Destruye: registro de usuario, todas las sesiones, todas las membresías, todos los datos asociados
Devuelve: { id, object, deleted: true }

Siempre advierte al usuario que esto es permanente y confirma antes de continuar.

Organizaciones

Crear organización

POST /v1/organizations
Cuerpo: { name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? }
Devuelve: objeto Organization con { id, name, slug, ... }

Listar organizaciones

GET /v1/organizations
Parámetros de consulta: limit, offset, query, order_by

Invitar miembro

POST /v1/organizations/{organization_id}/invitations
Cuerpo: { email_address: string, role: string ("org:admin" o "org:member"), public_metadata?, private_metadata? }
Devuelve: objeto OrganizationInvitation

Cómo ejecutar solicitudes

Ejecuta SIEMPRE las solicitudes con comandos curl directos. Usa los scripts de extracción de especificaciones (api-specs-context.sh, extract-tags.js, extract-endpoint-detail.sh) para descubrir endpoints, pero realiza las llamadas reales a la API con curl. NO uses scripts/execute-request.sh — es una ayuda de desarrollo local, no para uso del agente.

Plantilla para solicitudes GET:

curl -s "https://api.clerk.com/v1${PATH}${QUERY_STRING}" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY"

Plantilla para solicitudes POST/PATCH:

curl -s -X ${METHOD} "https://api.clerk.com/v1${PATH}" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '${BODY_JSON}'

Plantilla para solicitudes DELETE:

curl -s -X DELETE "https://api.clerk.com/v1${PATH}" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY"

Después de recibir la respuesta: Analízala y muéstrala claramente. Usa python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))" para mostrar el JSON formateado. Extrae los campos clave (id, email, nombre, etc.) y resúmelos para el usuario.


Contexto de especificaciones de la API

Antes de hacer cualquier cosa fuera de la RUTA RÁPIDA, obtén las versiones y etiquetas disponibles de la especificación ejecutando:

bash scripts/api-specs-context.sh

Usa la salida para determinar la última versión y las etiquetas disponibles.

Almacenamiento en caché: Si ya obtuviste el contexto de la especificación anteriormente en esta conversación, NO lo obtengas de nuevo. Reutiliza la versión y las etiquetas de la llamada anterior.


Reglas

  • Para operaciones comunes (listar usuarios, crear organización, invitar, actualizar metadatos, eliminar usuario): usa la RUTA RÁPIDA anterior — NO obtengas especificaciones primero.
  • Ignora siempre los endpoint/esquemas relacionados con platform.
  • Confirma siempre antes de realizar solicitudes de escritura (POST/PUT/PATCH/DELETE).
  • Para operaciones DELETE, advierte siempre al usuario que la acción es irreversible y menciona qué datos se perderán (registro de usuario, sesiones, membresías). Esta advertencia es OBLIGATORIA: nunca la omitas.
  • Para operaciones de escritura (POST/PUT/PATCH/DELETE), verifica CLERK_BAPI_SCOPES antes de intentar la solicitud. Si faltan o son insuficientes, pregúntale al usuario directamente. NO intentes y falles: pregunta antes de ejecutar. Esta verificación es OBLIGATORIA.
  • Para operaciones de metadatos, explica siempre los tres tipos (público, privado, inseguro) y recomienda el más adecuado.
  • Paginación: usa siempre limit + offset y menciona que los resultados pueden estar paginados para conjuntos de datos grandes.
  • Usa comandos curl directos para todas las llamadas a la API — nunca uses scripts/execute-request.sh.

Límites de tasa y aspectos a tener en cuenta

Límites de tasa

EntornoLímite
Producción1,000 solicitudes / 10 segundos
Desarrollo100 solicitudes / 10 segundos
Invitaciones individuales100 / hora
Invitaciones masivas25 / hora
Invitaciones de organización250 / hora
Creación de inicio de sesión en Frontend API5 / 10 segundos
Intentos de inicio de sesión en Frontend API3 / 10 segundos
Máximo de usuarios por página en lista500

currentUser() realiza una llamada real a la API que cuenta contra los límites de tasa. Usa auth() para solo las reclamaciones de sesión: lee del token sin una llamada a la API.

Sobrescritura de metadatos (no se fusionan)

updateUser({ publicMetadata: { role: 'admin' } }) REEMPLAZA todos los metadatos públicos, no los fusiona. Para agregar un campo sin perder datos existentes: primero lee, luego expande y después escribe.

Incorrecto:

await clerkClient.users.updateUser(userId, { publicMetadata: { newField: 'value' } })

Esto ELIMINA todos los demás campos de publicMetadata.

Correcto:

const user = await clerkClient.users.getUser(userId)
await clerkClient.users.updateUser(userId, {
  publicMetadata: { ...user.publicMetadata, newField: 'value' },
})

Modos

Determina el modo activo según el prompt del usuario en Contexto de opciones:

ModoDisparadorComportamiento
helpEl prompt está vacío, o contiene solo help / -h / --helpMuestra ejemplos de uso (paso 0)
browseEl prompt es tags, o un nombre de etiqueta (ej. Users)Lista todas las etiquetas o los endpoints de una etiqueta
executeEndpoint específico (ej. GET /users) o acción en lenguaje natural (ej. "obtener usuario john_doe")Busca el endpoint, ejecuta la solicitud
detailEndpoint + help / -h / --help (ej. GET /users help)Muestra el esquema del endpoint, no ejecuta

Tu tarea

Usa la ÚLTIMA VERSIÓN de Contexto de especificaciones de la API de forma predeterminada. Si el usuario especifica una versión diferente (ej. --version 2024-10-01), usa esa versión.

Determina el modo activo y sigue los pasos aplicables a continuación.


0. Mostrar uso

Modos: solo help — Saltar para browse, execute y detail.

Muestra los siguientes ejemplos al usuario textualmente:

Explorar
  /clerk-backend-api tags                         — listar todas las etiquetas
  /clerk-backend-api Users                        — explorar endpoints de la etiqueta Users
  /clerk-backend-api Users version 2025-11-10.yml — explorar usando una versión diferente

Ejecutar
  /clerk-backend-api GET /users             — obtener todos los usuarios
  /clerk-backend-api get user john_doe      — funciona también con lenguaje natural
  /clerk-backend-api POST /invitations      — crear una invitación

Inspeccionar
  /clerk-backend-api GET /users help        — mostrar esquema del endpoint sin ejecutarlo
  /clerk-backend-api POST /invitations -h   — ver detalles de solicitud/respuesta

Opciones
  --admin                            — omitir restricciones de alcance para escritura/eliminación
  --version [fecha], version [fecha] — usar una versión específica de la especificación
  --help, -h, help                   — inspeccionar el endpoint en lugar de ejecutarlo

Detente aquí.


1. Obtener etiquetas

Modos: browse (cuando el prompt es tags o no se ha especificado una etiqueta) — Saltar para help, execute y detail.

Si se usa una versión que no es la última, obtén las etiquetas para esa versión:

curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js

De lo contrario, usa las ETIQUETAS que ya están en Contexto de especificaciones de la API.

Comparte las etiquetas en una tabla y solicita al usuario que seleccione una consulta.


2. Obtener endpoints de una etiqueta

Modos: browse (cuando se proporciona un nombre de etiqueta) — Saltar para help, execute y detail.

Obtén todos los endpoints de la etiqueta identificada:

curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}"

Comparte los resultados (endpoints, esquemas, parámetros) con el usuario.


3. Obtener detalle del endpoint

Modos: execute, detail — Saltar para help y browse.

Para prompts en lenguaje natural en el modo execute, primero verifica si hay una coincidencia directa con la RUTA RÁPIDA; si no, ejecuta:

curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-endpoint-detail.sh "${method}" "${path}"

En el modo detail, muestra la información del esquema sin ejecutar.


4. Ejecutar solicitud

Modos: solo execute — Saltar para help, browse y detail.

Usa las plantillas de curl de la sección Cómo ejecutar solicitudes.


5. Formatear respuesta

Modos: solo execute — Saltar para help, browse y detail.

Analiza la respuesta JSON y preséntala formateada.

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

deangilmoreremix/videoremix.vip2

Implement Clerk authentication for native Android apps using Kotlin and Jetpack Compose with clerk-android source-guided patterns. Use for prebuilt AuthView/UserButton or custom API-driven auth flows. Do not use for Expo or React Native projects.

deangilmoreremix/videoremix.vip2

Astro patterns with Clerk — middleware, SSR pages, island components, API routes, static vs SSR rendering. Triggers on: astro clerk, clerk astro middleware, astro protected page, clerk island component, astro API route auth, clerk astro SSR.

deangilmoreremix/videoremix.vip2

Clerk Billing for subscription management - render Clerk's PricingTable and in-app checkout drawer, configure subscription plans, seat-limit plans for B2B, feature entitlements with has(), and billing webhooks. Use for SaaS monetization, plan gating, checkout flows, trials, invoicing, and subscription lifecycle management.

deangilmoreremix/videoremix.vip2

Chrome Extension auth with @clerk/chrome-extension -- popup/sidepanel setup, syncHost for OAuth/SAML via web app, createClerkClient for service workers and headless extensions, stable CRX ID. Triggers on: Chrome extension auth, Plasmo clerk, popup sign-in, syncHost, background service worker token, createClerkClient, headless extension.

deangilmoreremix/videoremix.vip2

>- Operate the Clerk CLI (`clerk` binary) for authentication, user/org/session management, deploy verification, instance config, env keys, and any Clerk Backend or Platform API call. Use when the user mentions Clerk management tasks, "list clerk users", "create a clerk user", "update organization", "pull clerk config", "clerk env pull", "clerk doctor", "clerk deploy", "clerk deploy status", "clerk api", or any ad-hoc Clerk API request. Prefer the CLI over raw HTTP: it handles auth, key resolution, app/instance targeting, and formatting automatically.

deangilmoreremix/videoremix.vip2

Custom authentication flows and component appearance - hooks (useSignIn, useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance styling, visual customization, branding.

deangilmoreremix/videoremix.vip2

Agent skill / project related to launch or product demo video: deangilmoreremix/videoremix.vip2

Skills relacionados