Agent skill · software engineering · jeremylongshore
persona-sdk-patterns
Design a typed Persona REST adapter that preserves JSON:API envelopes, request evidence, and compatible additions. Use when building a reusable client. Trigger with: "wrap Persona API", "type Persona responses", "Persona SDK pattern".
Why this skill is useful
Adds a complete, typed API client wrapper for the Persona API with error handling and pagination that the AI cannot generate on its own.
What it needs
Requires axios installed locally. 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
Typed Persona REST Adapter and JSON:API Envelope Overview Keep transport, Persona resource envelopes, and domain decisions separate. The adapter should preserve raw identifiers and metadata, tolerate new resources and fields, and expose explicit mutation evidence rather than flattening every response into a brittle model. Prerequisites Endpoint inventory and approved API version Language runtime with HTTP, JSON, and constant-time comparison support Domain boundary defining what may contain PII Instructions Step 1: Define the transport core Centralize the API base, bearer header, dated version, timeouts, request IDs, and safe telemetry. Do not retry mutations blindly. Step 2: Model JSON:API generically Represent data, type, id, attributes, relationships, included, meta, links, and structured errors before adding endpoint-specific views. Step 3: Preserve compatible additions Treat unknown fields, resource types, event types, and array order changes as data to preserve or ignore safely, not parse failures. Step 4: Separate command from query Require an operation ID and Idempotency-Key for POST commands. Queries may use bounded retries; commands reconcile observed state after ambiguity. Step 5: Normalize evidence, not identity Return status, request ID, rate and quota headers, resource ID, and a redacted envelope hash. Keep customer attributes behind the domain privacy boundary. Step 6: Test with contract fixtures Cover errors, pagination, unknown fields, multiple verification types, session metadata, throttling, and ambiguous POST outcomes. Authentication Inject the environment-scoped bearer key at the transport boundary and pin Persona-Version per request. Callers must never pass raw credentials or select an arbitrary host. 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-sdk-patterns