Agent skill · software engineering · jeremylongshore
persona-common-errors
Triage Persona authentication, JSON:API, inquiry, session, webhook, and throttle failures with redacted evidence. Use when an integration is failing. Trigger with: "debug Persona error", "Persona 401", "Persona inquiry failed".
Why this skill is useful
Provides specific error handling procedures and fixes for the Persona API that the AI wouldn't reliably generate on its own.
What it needs
Requires persona account access. About 3k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Persona API and Inquiry Failure Triage Overview Diagnose from the outer boundary inward: environment and credentials, request contract, resource lifecycle, session state, webhook authenticity, then provider limits. Preserve the original status and request evidence while keeping identity data out of logs. Prerequisites Timestamp, environment, endpoint, status, and provider request identifier Redacted request fingerprint and relevant inquiry or event ID Access to current Dashboard configuration and application logs Instructions Step 1: Freeze the evidence Record UTC time, method, canonical host and path, API version, status, request ID, idempotency key hash, and response-body hash. Step 2: Check environment and auth Confirm api.withpersona.com, the target environment, key state, permissions, and explicit version. A 401 is not fixed by printing or widening the key. Step 3: Validate the request envelope Check JSON:API shape, template selector, content headers, account auto-create metadata, and replay parameters. Step 4: Reconcile lifecycle state Read the inquiry before retrying a create, resume, or transition. Distinguish pending, terminal, redacted, and unavailable resources. Step 5: Verify event intake Use raw bytes, timestamp-plus-dot-plus-body HMAC, all v1 candidates, constant-time compare, event-ID dedupe, and creation-time ordering. Step 6: Respect limit signals Read live RateLimit- and Quota- headers and Dashboard product quotas. On 429, reduce the responsible lane and use bounded backoff. Authentication Authenticate REST diagnostics with the correct environment bearer key and webhook diagnostics with the endpoint’s signing secret. Redact both before creating a ticket or debug bundle. Tool Discipline Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/persona-common-errors