Agent skill · software engineering · jeremylongshore
flyio-sdk-patterns
Build a typed local adapter for the Fly.io Machines REST API with scoped auth, state waits, limits, reconciliation, and contract tests. Use when code must manage Machines or volumes. Trigger with: "wrap Machines API", "build Fly API client", "type Fly Machine states".
Why this skill is useful
Provides specific TypeScript patterns and client implementations for interacting with the Fly.io Machines API that the AI wouldn't reliably generate on its own.
What it needs
Requires fly.io account access. About 3k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Typed Fly.io Machines API Adapter Overview Fly.io publishes a REST API and OpenAPI reference; this workflow does not claim a provider-maintained JavaScript SDK. Generate or handwrite only a thin local adapter, keep provider fields visible, and centralize authentication, timeouts, limits, state waits, and redaction. Prerequisites Chosen operations and current OpenAPI or endpoint documentation Runtime and HTTP client policy, schema generator decision, and error model Synthetic fixtures plus an authorized non-production app for contract verification Instructions Step 1: Freeze the contract Record base URL, operation paths, request and response schemas, state enums, response codes, and retrieval fingerprint. Preserve unknown fields for forward compatibility. Step 2: Define a thin transport Centralize bearer auth, content type, request ID, timeout, retry eligibility, response parsing, and error redaction. Do not hide target app or Machine identifiers. Step 3: Model desired and observed state Represent Machine ID, instance version, configuration, lifecycle state, and target state separately. Require callers to reconcile before replay. Step 4: Use the provider wait operation After a mutation, wait for started, stopped, suspended, or destroyed with a bounded timeout and the required instance version where applicable. Step 5: Apply rate and conflict policy Serialize conflicting actions per identifier, use documented per-action limits, retry only eligible failures, and refresh after 409, 408, or ambiguous transport results. Step 6: Test the adapter Use fixture tests for every response and error class, then run an authorized read and one reversible non-production lifecycle operation with cleanup. Authentication Inject FLYAPITOKEN from a secret manager and send it only as the bearer header to the documented Machines API host. Keep token scope outside the client configuration file and scrub headers and Machine config secrets from exceptions. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/flyio-sdk-patterns