菜单
Collect comprehensive debug information for Clerk issues. Use when troubleshooting complex problems, preparing support tickets, or diagnosing intermittent issues. Trigger with phrases like "clerk debug", "clerk diagnostics", "clerk support ticket", "clerk troubleshooting".
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/ComeOnOliver/skillshub --skill clerk-debug-bundle命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Review product and feature risk before an AI coding agent starts implementation.
Use Xquik for X data and confirmation-gated X actions: tweet search, user lookup, follower export, media download, monitors, webhooks, MCP, and SDK workflows.
Canton Network open-source ecosystem guide covering DAML SDK, Canton runtime, and Splice applications. Use when working with Canton Network, DAML smart contracts, or building decentralized applications.
基于 SOC 职业分类
正在显示 SKILL.md
| name | clerk-debug-bundle |
| description | Collect comprehensive debug information for Clerk issues. Use when troubleshooting complex problems, preparing support tickets, or diagnosing intermittent issues. Trigger with phrases like "clerk debug", "clerk diagnostics", "clerk support ticket", "clerk troubleshooting". |
| allowed-tools | Read, Write, Edit, Bash(npm:*), Bash(node:*), Grep |
| version | 1.0.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| compatible-with | claude-code, codex, openclaw |
| tags | ["saas","clerk","debugging"] |
!node --version 2>/dev/null || echo 'N/A'
!npm list @clerk/nextjs @clerk/clerk-react @clerk/express 2>/dev/null | grep clerk || echo 'No Clerk packages found'
Collect all necessary debug information for Clerk troubleshooting and support tickets. Generates an environment report, runtime health check, client-side debug panel, and support bundle.
// scripts/clerk-debug.ts
import { createClerkClient } from '@clerk/backend'
async function collectDebugInfo() {
const info: Record<string, any> = {
timestamp: new Date().toISOString(),
nodeVersion: process.version,
platform: process.platform,
env: {
hasPK: !!process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,
hasSK: !!process.env.CLERK_SECRET_KEY,
pkPrefix: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY?.slice(0, 8) + '...',
nodeEnv: process.env.NODE_ENV,
},
}
{
clerk = ({ : process..! })
users = clerk..({ : })
info. = { : , : users. }
} (: ) {
info. = { : , : err., : err. }
}
{
pkg = ()
info. = .(pkg. || {})
.( k.())
.( ({ ...acc, [k]: v }), {})
} {
info. =
}
.(.(info, , ))
info
}
()
Run with:
npx tsx scripts/clerk-debug.ts
// app/api/clerk-health/route.ts
import { auth, clerkClient } from '@clerk/nextjs/server'
export async function GET() {
const checks: Record<string, { status: string; detail?: string }> = {}
// Check 1: SDK loaded
checks.sdk = { status: 'ok', detail: 'Clerk SDK loaded' }
// Check 2: Auth function works
try {
const { userId } = await auth()
checks.auth = { status: 'ok', detail: userId ? `Authenticated as ${userId}` : 'Not authenticated (expected for health check)' }
} catch (err: any) {
checks.auth = { status: 'error', detail: err.message }
}
// Check 3: Backend API connectivity
try {
const client = await clerkClient()
await client.users.getUserList({ limit: 1 })
checks.backendApi = { status: 'ok', detail: 'API reachable' }
} catch (err: any) {
checks.backendApi = { status: 'error', detail: err.message }
}
// Check 4: Environment variables
checks.envVars = {
status: process.env.CLERK_SECRET_KEY ? 'ok' : 'error',
detail: process.env.CLERK_SECRET_KEY ? 'Secret key configured' : 'CLERK_SECRET_KEY missing',
}
const allOk = Object.values(checks).every((c) => c.status === 'ok')
return Response.json({ healthy: allOk, checks }, { status: allOk ? 200 : 503 })
}
'use client'
import { useAuth, useUser, useSession } from '@clerk/nextjs'
import { useState } from 'react'
export function ClerkDebugPanel() {
const { userId, isLoaded: authLoaded, getToken } = useAuth()
const { user, isLoaded: userLoaded } = useUser()
const { session } = useSession()
const [tokenPreview, setTokenPreview] = useState<string | null>(null)
if (process.env.NODE_ENV === 'production') return null // Hide in prod
const inspectToken = async () => {
const token = await getToken()
if (token) {
const payload = JSON.parse(atob(token.split('.')[1]))
setTokenPreview(JSON.stringify(payload, null, 2))
}
}
return (
<details style={{ position: 'fixed', bottom: 10, right: 10, background: '#1a1a2e', color: '#eee', padding: 12, borderRadius: 8, fontSize: 12, zIndex: 9999 }}>
<summary>Clerk Debug</summary>
<pre>
Auth loaded: {String(authLoaded)}{'\n'}
User loaded: {String(userLoaded)}{'\n'}
User ID: {userId || 'null'}{'\n'}
Email: {user?.primaryEmailAddress?.emailAddress || 'N/A'}{'\n'}
Session ID: {session?.id || 'null'}{'\n'}
Session status: {session?.status || 'N/A'}{'\n'}
Last active: {session?.lastActiveAt ? new Date(session.lastActiveAt).toISOString() : 'N/A'}
</pre>
<button onClick={inspectToken}>Inspect JWT</button>
{tokenPreview && <pre>{tokenPreview}</pre>}
</details>
)
}
// middleware.ts — add debug logging (development only)
import { clerkMiddleware } from '@clerk/nextjs/server'
export default clerkMiddleware(async (auth, req) => {
if (process.env.CLERK_DEBUG === 'true') {
const { userId, sessionId } = await auth()
console.log(`[Clerk Debug] ${req.method} ${req.nextUrl.pathname}`, {
userId: userId || 'anonymous',
sessionId: sessionId?.slice(0, 8) || 'none',
cookies: req.cookies.getAll().map((c) => c.name).filter((n) => n.startsWith('__clerk')),
})
}
})
#!/bin/bash
# scripts/clerk-support-bundle.sh
set -euo pipefail
BUNDLE_DIR="clerk-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"
# Package versions
npm list --depth=0 2>/dev/null | grep clerk > "$BUNDLE_DIR/packages.txt" || true
# Environment check (redacted)
echo "NODE_ENV: ${NODE_ENV:-not set}" > "$BUNDLE_DIR/env.txt"
echo "Has PK: $([ -n "${NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY:-}" ] && echo yes || echo no)" >> "$BUNDLE_DIR/env.txt"
echo "Has SK: $([ -n "${CLERK_SECRET_KEY:-}" ] && echo yes || echo no)" >> "$BUNDLE_DIR/env.txt"
echo "PK prefix: ${NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY:0:8}..." >> "$BUNDLE_DIR/env.txt"
# Middleware check
[ -f middleware.ts ] && cp middleware.ts "$BUNDLE_DIR/" || echo "No middleware.ts found" > "$BUNDLE_DIR/middleware-missing.txt"
# Health check
curl -s http://localhost:3000/api/clerk-health > "$BUNDLE_DIR/health.json" 2>/dev/null || echo '{"error":"app not running"}' > "$BUNDLE_DIR/health.json"
# Bundle it
tar czf "${BUNDLE_DIR}.tar.gz" "$BUNDLE_DIR"
rm -rf "$BUNDLE_DIR"
echo "Support bundle: ${BUNDLE_DIR}.tar.gz"
/api/clerk-health endpoint for runtime health checks| Issue | Debug Action |
|---|---|
| Auth not working | Hit /api/clerk-health, check backendApi status |
| Token issues | Use debug panel "Inspect JWT" to view claims and expiry |
| Middleware not running | Enable CLERK_DEBUG=true, check console for request logs |
| Session not persisting | Check debug panel for __clerk cookies, verify domain |
# Verify Clerk API connectivity from CLI
curl -s -H "Authorization: Bearer $CLERK_SECRET_KEY" \
https://api.clerk.com/v1/users?limit=1 | jq '.total_count'
Proceed to clerk-rate-limits for understanding Clerk rate limits.