Communitygithub.com

deangilmoreremix/videoremix.vip2

Clerk 後端 REST API 的瀏覽器與執行器。可瀏覽標籤、檢查端點架構,並執行已驗證的請求。適用於列出使用者、管理組織或呼叫任何 Clerk API 端點。

videoremix.vip2 是什麼?

這是一個專為 AI 代理(如 Claude Code、Cursor 或 Codex)設計的 Clerk 後端 API 技能。它提供了一個快速路徑,來執行常見的 Clerk 後端 API 操作,例如列出使用者、建立組織、邀請成員、更新使用者元資料以及刪除使用者。該技能會強制執行重要的安全檢查:在進行任何寫入請求之前,它會驗證 `CLERK_SECRET_KEY` 是否存在,並檢查 `CLERK_BAPI_SCOPES` 以確保使用者擁有正確的權限。對於 DELETE 操作,它會強制要求明確的不可復原性警告。該技能支援兩種執行模式:`快速路徑` 用於常見操作(無需獲取規格,直接執行),以及 `完整規格模式`,用於透過 OpenAPI 規格來發現和執行任何端點。如果是透過 SDK 使用,它也會提供 TypeScript 等價範例,並包含關於速率限制和元資料覆寫陷阱的重要備註(元資料是取代而非合併)。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

選項上下文

使用者提示:$ARGUMENTS

關鍵:每次寫入請求前必須執行的檢查

在進行任何 POST / PATCH / PUT / DELETE 之前,您必須在您的回應中執行以下所有步驟:

  1. 檢查 CLERK_SECRET_KEY — 確認它已設定:

    echo $CLERK_SECRET_KEY | head -c 10
    

    如果為空,請停止並詢問使用者。沒有有效的金鑰就無法繼續。

  2. 檢查 CLERK_BAPI_SCOPES — 執行:

    echo $CLERK_BAPI_SCOPES
    

    檢查輸出。如果範圍缺失或未包含所需的寫入權限,請告知使用者:「這是一個寫入操作,您目前的範圍可能不允許。是否要使用 --admin 重新執行以略過?」 不要嘗試請求然後失敗 — 先詢問。

  3. 對於 DELETE 請求: 明確警告該操作是不可復原的,並準確列出哪些資料將被永久銷毀(使用者記錄、所有工作階段、所有成員資格、所有關聯資料)。在繼續之前需要明確確認。此警告是強制性的 — 絕對不能省略。

  4. 對於元資料操作: 總是解釋正在使用哪種元資料類型以及原因(請參閱下面的元資料類型章節)。


快速路徑:常見操作(直接使用,無需擷取規格)

對於以下操作,請直接執行,無需擷取規格。根據使用者上下文中的 $CLERK_SECRET_KEY、$USER_ID、$ORG_ID、$EMAIL 來替換。

建立組織 + 邀請成員(兩步驟)

# 步驟 1 — 建立組織
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))"

# 步驟 2 — 提取組織 ID
ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# 步驟 3 — 邀請成員並指定角色
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))"

角色: 使用 "org:admin" 或 "org:member"(總是加上 org: 前綴)。

SDK 等效範例(適用於使用 @clerk/nextjs 或 @clerk/backend 的 Next.js / TypeScript 專案)

import { clerkClient } from '@clerk/nextjs/server'
// OR if using @clerk/backend directly:
// import { createClerkClient } from '@clerk/backend'
// const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })

// Step 1: Create organization
const org = await clerkClient.organizations.createOrganization({
  name: 'Acme Corp',
  createdBy: userId,  // required — the ID of the user creating the org
})

// Step 2: Invite member to the org
const invitation = await clerkClient.organizations.createOrganizationInvitation({
  organizationId: org.id,
  emailAddress: '[email protected]',
  role: 'org:admin',  // or 'org:member'
})

更新使用者元資料

在詢問使用哪種元資料類型之前,總是先解釋這三種元資料類型:

類型欄位可讀取者可寫入者用途
公開public_metadata客戶端 + 伺服器僅限伺服器前端讀取的方案層級、角色、功能開關
私有private_metadata僅限伺服器僅限伺服器Stripe ID、合規標誌、內部識別碼
不安全unsafe_metadata客戶端 + 伺服器客戶端 + 伺服器暫時性 UI 狀態、入門步驟(客戶端可寫 — 避免敏感資料)

對於 plan: 'pro' 和 onboarded: true — 使用 public_metadata(前端可讀、伺服器可寫):

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'Updated user {d[\"id\"]}: public_metadata={d.get(\"public_metadata\")}')"

SDK 等效範例:

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

await clerkClient.users.updateUser(userId, {
  publicMetadata: { plan: 'pro', onboarded: true },   // readable by client, writable server-only
  // privateMetadata: { stripeId: 'cus_xxx' },         // server-only read AND write
  // unsafeMetadata: { step: 'welcome' },              // client-writable, avoid sensitive data
})

注意: REST API 使用 snake_case (public_metadata)。SDK 使用 camelCase (publicMetadata)。

列出使用者(過去 7 天)

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'Found {len(data)} users:')
    for u in data:
        print(f'  {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"no email\")}')
else:
    print(json.dumps(data, indent=2))
"

刪除使用者(需要確認)

# ONLY run after explicit user confirmation
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'Deleted: {d}')"

Clerk 後端 API — 完整端點參考

基礎 URL:https://api.clerk.com/v1 驗證:每個請求都需要 Authorization: Bearer $CLERK_SECRET_KEY。

使用者

列出使用者

GET /v1/users
查詢參數:limit (最大 500,預設 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 (ISO 8601 範圍:gt:TIMESTAMP 或 lt:TIMESTAMP,使用 Unix 毫秒)
回傳:User 物件陣列

取得使用者

GET /v1/users/{user_id}
回傳:User 物件

更新使用者

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

刪除使用者 — 不可復原

DELETE /v1/users/{user_id}
銷毀:使用者記錄、所有工作階段、所有成員資格、所有關聯資料
回傳:{ id, object, deleted: true }

總是警告使用者此操作是永久性的,並在繼續之前要求確認。

組織

建立組織

POST /v1/organizations
主體:{ name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? }
回傳:Organization 物件,包含 { id, name, slug, ... }

列出組織

GET /v1/organizations
查詢參數:limit、offset、query、order_by

邀請成員

POST /v1/organizations/{organization_id}/invitations
主體:{ email_address: string, role: string ("org:admin" 或 "org:member"), public_metadata?, private_metadata? }
回傳:OrganizationInvitation 物件

如何執行請求

總是使用直接的 curl 指令來執行請求。 使用規格提取腳本 (api-specs-context.sh、extract-tags.js、extract-endpoint-detail.sh) 來發現端點,但使用 curl 來進行實際的 API 呼叫。不要使用 scripts/execute-request.sh — 那是本機開發輔助工具,不適用於代理。

GET 請求的範本:

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

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}'

DELETE 請求的範本:

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

收到回應後: 解析並清晰地顯示出來。使用 python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))" 來美化列印 JSON。為使用者提取關鍵欄位 (id、email、name 等) 並進行總結。


API 規格上下文

在執行快速路徑之外的任何操作之前,請先執行以下指令來擷取可用的規格版本和標籤:

bash scripts/api-specs-context.sh

使用輸出結果來決定最新的版本和可用的標籤。

快取: 如果您在此對話中已經擷取過規格上下文,請不要再次擷取。直接重複使用上一次呼叫中的版本和標籤。


規則

  • 對於常見操作(列出使用者、建立組織、邀請、更新元資料、刪除使用者):使用上面的快速路徑 — 不要先擷取規格。
  • 總是忽略與 platform 相關的端點/架構。
  • 在執行寫入請求 (POST/PUT/PATCH/DELETE) 之前,總是先確認。
  • 對於 DELETE 操作,總是警告使用者該操作是不可復原的,並提及哪些資料將會遺失(使用者記錄、工作階段、成員資格)。此警告是強制性的 — 絕對不能省略。
  • 對於寫入操作 (POST/PUT/PATCH/DELETE),在嘗試請求之前檢查 CLERK_BAPI_SCOPES。如果遺失或不足,直接詢問使用者。不要嘗試然後失敗 — 在執行之前先詢問。此檢查是強制性的。
  • 對於元資料操作,總是解釋全部三種類型(公開、私有、不安全)並建議合適的類型。
  • 分頁:總是使用 limit + offset,並提及對於大型資料集,結果可能需要分頁。
  • 對所有 API 呼叫使用直接的 curl 指令 — 永遠不要使用 scripts/execute-request.sh。

速率限制與注意事項

速率限制

環境限制
正式環境1,000 個請求 / 10 秒
開發環境100 個請求 / 10 秒
單一邀請100 / 小時
大量邀請25 / 小時
組織邀請250 / 小時
前端 API 登入建立5 / 10 秒
前端 API 登入嘗試3 / 10 秒
列出使用者每頁上限500

currentUser() 會進行實際的 API 呼叫,這會計入速率限制。如果只需要工作階段的宣告,請使用 auth() — 它從權杖中讀取,不需要 API 呼叫。

元資料覆寫(非合併)

updateUser({ publicMetadata: { role: 'admin' } }) 會取代所有公開元資料,而不是合併。要在不丟失現有資料的情況下新增欄位:先讀取、展開、再寫入。

錯誤:

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

這會刪除所有其他的 publicMetadata 欄位。

正確:

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

模式

根據選項上下文中的使用者提示來決定作用中的模式:

模式觸發條件行為
help提示為空,或僅包含 help / -h / --help列印使用範例(步驟 0)
browse提示為 tags,或一個標籤名稱(例如 Users)列出所有標籤,或列出某個標籤的端點
execute特定端點(例如 GET /users)或自然語言動作(例如 "get user john_doe")查詢端點,執行請求
detail端點 + help / -h / --help(例如 GET /users help)顯示端點架構,不執行

您的任務

預設情況下,使用來自 API 規格上下文 的最新版本。如果使用者指定了不同的版本(例如 --version 2024-10-01),則使用該版本。

決定作用中的模式,然後遵循下面適用的步驟。


0. 列印使用說明

模式: 僅 help — 對於 browse、execute 和 detail 模式則跳過。

向使用者逐字列印以下範例:

瀏覽
  /clerk-backend-api tags                         — 列出所有標籤
  /clerk-backend-api Users                        — 瀏覽 Users 標籤的端點
  /clerk-backend-api Users version 2025-11-10.yml — 使用不同版本瀏覽

執行
  /clerk-backend-api GET /users             — 取得所有使用者
  /clerk-backend-api get user john_doe      — 自然語言也可以
  /clerk-backend-api POST /invitations      — 建立邀請

檢查
  /clerk-backend-api GET /users help        — 顯示端點架構但不執行
  /clerk-backend-api POST /invitations -h   — 檢視請求/回應詳情

選項
  --admin                            — 略過寫入/刪除的範圍限制
  --version [date], version [date]   — 使用特定的規格版本
  --help, -h, help                   — 檢查端點而不是執行

在此停止。


1. 擷取標籤

模式: browse(當提示為 tags 或未指定標籤時) — 對於 help、execute 和 detail 模式則跳過。

如果使用非最新版本,則為該版本擷取標籤:

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

否則,使用 API 規格上下文中已有的標籤。

以表格形式分享標籤,並提示使用者選擇一個查詢。


2. 擷取標籤端點

模式: browse(當提供了標籤名稱時) — 對於 help、execute 和 detail 模式則跳過。

為識別出的標籤擷取所有端點:

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

與使用者分享結果(端點、架構、參數)。


3. 擷取端點詳情

模式: execute、detail — 對於 help 和 browse 模式則跳過。

對於 execute 模式中的自然語言提示,先檢查是否與快速路徑中的任何操作相符。如果是,則直接使用快速路徑範本。如果不是,則使用來自 API 規格上下文 的版本名稱:

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

(如果使用者提供了版本,則替換 ${version_name})。

產生結構化摘要,如果模式為 execute,則繼續執行步驟 4。

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

相關技能