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

lex-setup

Configure and troubleshoot @atproto/lex code generation for TypeScript packages.

9.6k|915|Updated Dec 17, 2021
Search Tags:#codegen#lexicon#Monorepo#typeScript#ATProto#Code generation#lex build
One-click install
npx skills add https://github.com/bluesky-social/atproto --skill lex-setup
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: lex-setup
Source: https://github.com/bluesky-social/atproto/tree/main/.agents/skills/lex-setup
Command: npx skills add https://github.com/bluesky-social/atproto --skill lex-setup

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Setting up Lexicon-to-TypeScript code generation in the atproto monorepo involves subtle wiring: the right codegen:lex script, prebuild hooks, gitignore rules, --include filters, and a lex binary name collision between @atproto/lex and legacy @atproto/lex-cli. This Skill captures the canonical setup pattern and the fixes for the failures that follow stale or misconfigured codegen.

Core Features & Use Cases

  • Package wiring: Add the standard codegen:lex / prebuild / build script trio, gitignore src/lexicons, and compile with tsgo.
  • Codegen control: Use lex build flags like --include, --exclude, --lib, --indexFile, and --clear to scope and shape generated output.
  • Troubleshooting: Diagnose stale generated trees after lexicon edits, lex binary collisions with legacy lex-cli, and migration off gen-api/gen-server output.
  • Use Case: After editing a Lexicon JSON file, a build fails with "type X is not assignable to Y" — this Skill directs you to regenerate via pnpm codegen and explains why the stale tree caused it.

Quick Start

Ask the AI to wire up @atproto/lex code generation for a package in this repo, including the codegen script, prebuild hook, and gitignore entry.

Frequently Asked Questions about lex-setup

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

FAQPage Schema
How do I set up @atproto/lex code generation in a package?▼

Add @atproto/lex as a dependency and a codegen:lex script running lex build --clear --indexFile --lexicons ../../lexicons, plus a prebuild script that runs all codegen:* scripts. Gitignore the generated src/lexicons output directory since it is a build artifact.

Why does lex build fail with an unknown command error?▼

Both @atproto/lex and legacy @atproto/lex-cli claim the lex bin name, and resolution is per-package. In packages still depending on lex-cli, pnpm exec lex resolves to the legacy CLI; use ts-lex or migrate the dependency to fix it.

Why do I get type errors after editing lexicon JSON files?▼

Generated TypeScript is not rebuilt automatically, so a stale tree causes type X is not assignable to Y errors. Run pnpm codegen at the repo root or pnpm run prebuild inside the package to regenerate before building.

How do I generate only specific lexicons with lex build?▼

Pass --include with NSID patterns such as com.atproto.sync.subscribeRepos or app.bsky.* to filter which schemas compile. Referenced schemas are pulled in transitively, and --exclude is applied after --include.

Should I commit the generated src/lexicons directory?▼

No, generated files under src/lexicons are build artifacts deleted and rewritten on every --clear build, so they belong in .gitignore. The canonical lexicons/ directory at the repo root is committed source and must not be touched.

Related Skills

Explore More Software Engineering Skills→
ngerakinesngerakines
46

atproto-publish-lexicon

Publish and resolve AT Protocol lexicons as com.atproto.lexicon.schema records.

Community
Advanced
cchrisvcchrisv

generating-fragment

Generate reusable Salesforce UI fragments with UEM tree structures and TypeScript interfaces.

Community
Advanced
guardiatechnologyguardiatechnology

kata-frontend-review

Review frontend pull requests and output a Markdown report with Blocking, Recommendations, and Notes.

Official
Advanced
aryan-binaziraryan-binazir

skill-installer

Install agent skills from GitHub repositories or curated lists into Codex.

Community
Intermediate