Clerk

Purpose

Manage users in the user's Clerk application through the Clerk Backend API: list users, look up one user, create users, update names, and delete users. Use when the user mentions their Clerk users.

Tooling

All commands go through bin/clerk.py:

bin/clerk.py auth                                                    # verify the secret key
bin/clerk.py users --limit 25                                        # list users
bin/clerk.py user --id <user-id>                                     # look up one user
bin/clerk.py create --email "them@example.com" --first-name Ana      # create a user
bin/clerk.py update --id <user-id> --last-name Reyes                 # update a user
bin/clerk.py delete --id <user-id>                                    # delete a user

Auth

• Provider id: clerk (credential is collected as custom.clerk)
• Collection: secret key (sk_...) via the secure credential flow (credentials.request_api_access); found in the Clerk dashboard under API Keys
• Allowed hosts: api.clerk.com
• Status check: bin/clerk.py auth (must return "ok": true)

Operating Rules

1. Request bodies use snake_case field names (for example public_metadata). The Clerk SDKs use camelCase; keep the two conventions separate and never send SDK-style field names to this API.
2. Create, update, and delete are confirmation-gated: confirm the details with the user first, unless standing permission exists.
3. Delete is irreversible; confirm explicitly even when other writes have standing permission.
4. Reads (users, user) need no confirmation.
5. Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/clerk.py). Do not print, log, or transmit the key value.

Files

• SKILL.md
• bin/clerk.py

Maturity

🧪 Draft: written from Clerk's public API docs; not yet live-tested end-to-end.