> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfacets.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a Custom Adapter

> Write custom adapters for AI coding tools

An <Tooltip headline="Adapter" tip={<span>The bridge between facets and an AI coding tool. It tells <code>facet</code> where and how to write a facet's assets on disk so the tool can find them.</span>} cta="Adapter reference" href="/cli/adapters/install">adapter</Tooltip> teaches the `facet` CLI how to install assets into a specific AI coding tool. The first-party adapters cover Claude Code, OpenCode, and Codex; this guide shows how to build your own using the [`@agent-facets/adapter`](https://github.com/agent-facets/facets/tree/main/packages/adapter) SDK.

An adapter is a small TypeScript library. You write one file, build it, and install it locally  -- from a directory, from GitHub, or (once published) by name.

> **Building an adapter?** It's a TypeScript package that default-exports a
> `defineAdapter({...})` call. The contract lives in `@agent-facets/adapter`:
>
> * `name` (required) — unique adapter id.
> * `buildAssetMetadata(data)` (required) — validate/enrich per-asset
>   manifest metadata; return `Validated<AdapterMetadata>`.
> * `supportsInstall: true` + `installAsset` / `readAsset` / `deleteAsset` —
>   the filesystem I/O that materializes assets. Without these the adapter
>   is metadata-only and hidden from the install picker.
>
> Use the SDK's `installAssetFile` / `readAssetFile` / `deleteAssetFile`
> helpers for front-matter-aware file I/O. `Scope` is `'system' | 'user' |
> 'project'`; `AssetType` is `'skill' | 'agent' | 'command'`.
>
> Build with `tsdown`/`tsc`, then install:
>
> ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
> facet adapter install ./my-adapter                        # local directory
> facet adapter install git+https://github.com/you/repo.git # from GitHub
> facet adapter install my-adapter                           # by npm name, once published
> ```