skills.rest
bluesky-social
bluesky-socialOFFICIAL
Explore all skills by this author →
GitHub

lexification-client

Migrates AT Protocol client code from legacy @atproto/api and @atproto/xrpc to @atproto/lex.

9.6k|915|Updated Dec 17, 2021
Search Tags:#code modernization#typeScript#Bluesky#ATProto#XRPC#Migration#atproto-lex
One-click install
npx skills add https://github.com/bluesky-social/atproto --skill lexification-client
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: lexification-client
Source: https://github.com/bluesky-social/atproto/tree/main/.agents/skills/lexification-client
Command: npx skills add https://github.com/bluesky-social/atproto --skill lexification-client

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

AT Protocol codebases built on the legacy @atproto/api, @atproto/lexicon, and @atproto/xrpc stack need to be modernized onto @atproto/lex, but the migration touches many API surfaces — agents, error handling, headers, CIDs, BlobRefs, datetimes, and type guards — making manual conversion error-prone and inconsistent.

Core Features & Use Cases

  • Agent-to-Client Migration: Replaces AtpAgent with Client, converting agent.api.<ns>.<method>() calls into client.call(), client.xrpc(), or xrpcSafe() depending on whether the call site needs the body, headers, or typed error handling.
  • Data Type Modernization: Converts jsonStringToLex/stringifyLex to lexParse/lexStringify, CID from multiformats to Cid/parseCid, BlobRef instanceof checks to isBlobRef/getBlobCidString, and ISO date strings to branded DatetimeString helpers.
  • Error Handling Upgrades: Replaces try/catch with instanceof XRPCError by xrpcSafe() discriminated results, including toDownstreamError() remapping and schema-declared error narrowing.
  • Use Case: While modernizing a Bluesky service package, you reach an agent.api.app.bsky.feed.getFeedSkeleton() call — this Skill rewrites it to a typed client.xrpc() call with standard Headers access and branded DidString types at the boundaries.

Quick Start

Migrate this file's outgoing XRPC calls from AtpAgent and @atproto/api to the @atproto/lex Client API.

Frequently Asked Questions about lexification-client

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate from AtpAgent to the @atproto/lex Client?▼

Replace `new AtpAgent({ service })` with `new Client(agentConfig, clientOptions)` from @atproto/lex, moving static headers into the agent config instead of calling setHeader. Then convert `agent.api.<ns>.<method>()` calls to `client.call(schema, params, opts)` or `client.xrpc(schema, opts)`.

What replaces XRPCError try/catch in @atproto/lex?▼

Use `xrpcSafe()` or `client.xrpcSafe()`, which return a discriminated result instead of throwing. Narrow failures with `XrpcResponseError` and `XrpcInvalidResponseError` checks, or inspect `result.error` for schema-declared error codes.

How do I replace BlobRef instanceof checks after migrating?▼

BlobRef is now an interface in @atproto/lex-data, so instanceof no longer works. Use the `isBlobRef(value)` guard for checks and `getBlobCidString(json)` to extract CIDs, passing `{ strict: false }` for legacy data.

Does this migration cover server route definitions too?▼

No, this Skill covers only code that calls out to XRPC services. Route definitions using `server.add` and handler signatures are handled by the separate lexification-server skill, and service packages typically need both.

Should I migrate tests that still use AtpAgent?▼

By default, leave passing tests alone since they act as unchanged regression checks during source migration. Only update tests that import deleted legacy paths, or migrate a test file wholesale when deliberately converting it, avoiding half-migrated suites.

Related Skills

Explore More Software Engineering Skills→
luyi985luyi985

codegen-over-complex-types

Generate TypeScript types from OpenAPI, GraphQL, or database schemas.

Community
Advanced
Ledger-Wallet-LLCLedger-Wallet-LLC

create-changeset

Create changeset markdown files for Ledger Live package changes.

Official
Basic
aitchwhyaitchwhy

type-safety

Prevent mixing incompatible values with branded types and boundary parsing.

Community
Advanced
gonzoblascogonzoblasco

redux-migration-rtk-zustand

Migrate Redux stores incrementally to Redux Toolkit and Zustand.

Community
Advanced