# Add Adapter > Add a vendor-official or community adapter to the Chat SDK catalog and docs — adapters.json registry, chat/adapters catalog entry, the docs MDX page, meta.json, integration-test lists, and a changeset. Use when a developer wants to add, list, register, or submit a third-party (vendor-official or community) adapter to this repo, add an adapter to the catalog, or create or edit an adapter docs page under apps/docs/content/adapters/vendor-official or apps/docs/content/adapters/community. - Skill: `vercel-chat/add-adapter` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds add vercel-chat/add-adapter` - Raw SKILL.md: https://api.skillmd.com/api/skills/vercel-chat/add-adapter/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: vercel (https://skillmd.com/u/vercel-chat) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/vercel-chat/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. ## 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 only. No `chat/adapters` catalog entry, no changeset. - **vendor-official** — a maintained/blessed adapter. Everything community has, plus a `chat/adapters` catalog entry, a matching `create-chat-sdk` scaffold-spec entry, and a changeset. Frontmatter adds `vendorOfficial: true` and `author`. ## Files to change `` is `vendor-official` or `community`. 1. **`apps/docs/content/adapters//.mdx`** — the docs page. Start from [assets/adapter.mdx](assets/adapter.mdx). The filename basename must equal the `slug` frontmatter field, and the page must render ``. 2. **`apps/docs/content/adapters//meta.json`** — add `""` to the `pages` array. 3. **`apps/docs/adapters.json`** — add a registry entry: `name`, `slug`, `type`, `community: true`, `description`, `packageName`, `author`, `readme` (the GitHub URL). Add `vendorOfficial: true` for vendor-official. 4. **`packages/integration-tests/src/docs-adapters.test.ts`** — add `""` to the hardcoded expected list for its tier. 5. **`packages/integration-tests/src/documentation-test-utils.ts`** — add the `packageName` to `VALID_DOC_PACKAGES`, plus every import specifier used in the MDX code blocks (subpaths count separately). **Vendor-official also:** 6. **`packages/chat/src/adapters/index.ts`** — add an `ADAPTERS` entry with `group: "vendor-official"`. Reuse the `env`/`secretEnv`/`urlEnv` helpers; use `env: { notes: "…" }` when there are no env vars. See `packages/chat/src/adapters/AGENTS.md`. 7. **`packages/create-chat-sdk/src/catalog/scaffold-spec.ts`** — add a matching `"": { invocation: … }` entry, modeled on a similar adapter. This is a required registration step, not a behavior change: the object is `satisfies Record`, so every catalog slug must have one or `create-chat-sdk` fails to type-check. 8. **`.changeset/-adapter.md`** — `"chat": patch` + `"create-chat-sdk": patch`, one line describing the addition. ## Invariants the tests enforce - **Registry ↔ catalog parity.** `Object.keys(ADAPTERS)` must equal the adapters.json slugs where `!community || vendorOfficial`. So vendor-official **must** be in `chat/adapters`; community-only **must not** be. This is why community adapters skip steps 6–8. - **peerDeps ↔ PackageInstall.** The catalog entry's `peerDeps` (sorted) must exactly equal the extra packages in the MDX ``, after removing the adapter's own `packageName`, `chat`, and any `@chat-adapter/state-*`. Easiest: `peerDeps: []`, install only ` chat` (plus a state adapter) in `PackageInstall`, and keep any other imports in fenced code blocks. - **Fields match.** `packageName`, `type`, `community`, and `vendorOfficial` must match between the MDX frontmatter and the adapters.json entry. - **Required frontmatter:** `title`, `description`, `packageName`, `slug`, `tagline`, `type` (`platform` | `state`), `mdxBody: true`, `community: true` (plus `vendorOfficial: true` and `author` for vendor-official). - **Imports.** Every import in an MDX code block must be listed in `VALID_DOC_PACKAGES`. ## Validate ```bash pnpm --filter chat build # regenerate the catalog the tests import pnpm --filter @chat-adapter/integration-tests test pnpm --filter chat typecheck 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 template: [assets/adapter.mdx](assets/adapter.mdx) - Catalog conventions: `packages/chat/src/adapters/AGENTS.md` - Examples to copy: `apps/docs/content/adapters/vendor-official/` and `apps/docs/content/adapters/community/`