add-adapter

Add a catalog adapter (vendor-official or community)

Use this to list a third-party adapter in the Chat SDK catalog and docs. It is not for building a first-party packages/adapter-* package.

Required: load the technical-writer skill (../technical-writer/SKILL.md) before writing any prose: the docs page, frontmatter tagline and description, the changeset, commit messages, and the PR description. Follow its editorial standards alongside the sourcing rules below.

Gather the source — never invent details

Ask the user for:

1. Their adapter's GitHub repository URL.
2. Their docs or README.

Read both. Everything you write into the catalog and docs must come directly from those sources or from the user. Do not assume or guess any information:

• packageName — read it from the repo's package.json, verbatim.
• Factory export (e.g. createFooAdapter) — read it from the package's exports/source. Do not guess it from the display name.
• type (platform or state), env vars, and the feature matrix — base these on what the code and README actually document.
• Install and usage snippets — take them from the README; do not write example code the adapter may not support.

If the repo or README does not make something clear, stop and ask the user rather than filling it in. When in doubt, ask.

Choose the slug (kebab-case) and confirm it is not already taken: ls apps/docs/content/adapters/*/.

Pick the tier

• community — listed in the docs. A CommunityAdapter entry in @chat-adapter/catalog (listing metadata and capabilities only), no scaffold spec.
• vendor-official — a maintained/blessed adapter. A full CatalogAdapter entry with setup metadata (factory export, peer deps, env vars), a matching create-chat-sdk scaffold-spec entry, and a changeset. Frontmatter adds vendorOfficial: true and author.

Files to change

<tier> is vendor-official or community.

1. apps/docs/content/adapters/<tier>/<slug>.mdx: the docs page. Start from assets/adapter.mdx for a platform adapter or assets/adapter-state.mdx for a state adapter, and follow the section order and names in references/page-layout.md. The filename basename must equal the slug frontmatter field, and the page must render <FeatureSupport />.
2. apps/docs/content/adapters/<tier>/meta.json — add "<slug>" to the pages array.
3. packages/catalog/src/adapters/<tier>/<slug>.ts — the catalog entry: name, slug, type, group, description, packageName, author, readme (the GitHub tree URL of the adapter's source folder, pinned to a commit or tag; the docs page fetches the README from it and links to it as "View source"), and features (the capability matrix the docs page renders). Copy a neighbor in the same folder. Then register it in packages/catalog/src/adapters/index.ts: COMMUNITY_ADAPTERS for community, ADAPTERS for vendor-official. See packages/catalog/AGENTS.md.

Vendor-official also:

4. Setup fields in the catalog entry — factoryExport, peerDeps, optional importPath, and env. Reuse the env/secretEnv/urlEnv helpers from packages/catalog/src/env.ts; use env: { notes: "…" } when there are no env vars.
5. packages/create-chat-sdk/src/catalog/scaffold-spec.ts — add a matching "<slug>": { invocation: … } entry, modeled on a similar adapter. This is a required registration step, not a behavior change: the object is satisfies Record<AdapterSlug, …>, so every catalog slug must have one or create-chat-sdk fails to type-check.
6. .changeset/<slug>-adapter.md — "@chat-adapter/catalog": patch + "create-chat-sdk": patch, one line describing the addition. Community listings ship in the published catalog too, so add a "@chat-adapter/catalog": patch changeset for them as well.

Invariants the tests enforce

• Docs ↔ catalog parity. Every adapter MDX page has a catalog entry in the matching group, and every catalog entry has a page. Vendor-official entries go in ADAPTERS; community entries go in COMMUNITY_ADAPTERS. This is why community adapters skip steps 4 and 5.
• peerDeps ↔ PackageInstall. The catalog entry's peerDeps (sorted) must exactly equal the extra packages in the MDX <PackageInstall package="…" />, after removing the adapter's own packageName, chat, and any @chat-adapter/state-*. Easiest: peerDeps: [], install only <packageName> chat (plus a state adapter) in PackageInstall, and keep any other imports in fenced code blocks.
• Fields match. packageName, type, and author (when set in frontmatter) must match between the MDX frontmatter and the catalog entry.
• Capabilities live in the catalog. Frontmatter must not declare features; <FeatureSupport /> reads them from the catalog entry. Only keys from PLATFORM_FEATURE_CATEGORIES or STATE_FEATURE_CATEGORIES (matching the adapter type) are allowed.
• Required frontmatter: title, description, packageName, slug, tagline, type (platform | state), mdxBody: true, community: true (plus vendorOfficial: true and author for vendor-official).

Validate

pnpm --filter @chat-adapter/catalog build   # regenerate the catalog the tests import
pnpm --filter @chat-adapter/catalog test
pnpm --filter @chat-adapter/integration-tests test
pnpm --filter create-chat-sdk typecheck   # vendor-official only
pnpm check && pnpm konsistent

Resources

• Human guide (vendor-official): apps/docs/content/docs/contributing/vendor-official.mdx
• Human guide (community listing): apps/docs/content/docs/contributing/publishing.mdx
• MDX templates: assets/adapter.mdx (platform) and assets/adapter-state.mdx (state)
• Page layout and section names: references/page-layout.md
• Writing standards (required): technical-writer skill
• Catalog conventions: packages/catalog/AGENTS.md
• Examples to copy: apps/docs/content/adapters/vendor-official/ and apps/docs/content/adapters/community/