Skip to content
Skills Library
Programming · Tool integration

create-adapter

/create-adapter

Author a new Routecraft adapter (source, destination, enricher, transformer, or multi-role). Use when the user asks to add a new integration, connector, endpoint type, or producer or consumer of exchanges.

Repository
routecraft ↗
Licence
Apache-2.0
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
6
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Author a new Routecraft adapter (source, destination, enricher, transformer, or multi-role). Use when the user asks to add a new integration, connector, endpoint type, or producer or consumer of exchanges.

Original author description

Author a new Routecraft adapter (source, destination, enricher, transformer, or multi-role). Use when the user asks to add a new integration, connector, endpoint type, or producer or consumer of exchanges.

How it works

  1. When to use this skill
  2. Step 1: clarify
  3. Step 2: pick the closest example
  4. Step 3: write the adapter
  5. Step 4: write tests
  6. Step 5: verify
  7. Useful URLs
Original SKILL.md headings · 88 lines, 889 words
SKILL.md preview
---
name: create-adapter
description: Author a new Routecraft adapter (source, destination, enricher, transformer, or multi-role). Use when the user asks to add a new integration, connector, endpoint type, or producer or consumer of exchanges.
allowed-tools: Read Glob Grep WebFetch Bash(bun run lint:*) Bash(bun run typecheck:*) Bash(bun run test:*)
---

# Create a Routecraft adapter

Adapters are how Routecraft talks to the outside world. A source produces exchanges, a destination pushes them out (void send; receipts ride headers), an enricher pulls a value in per exchange, and a transformer changes the body in flight. Many adapters fill more than one role.

You are writing this adapter for the user. Treat the linter (`bun run lint`) as authoritative once you have written the code: if it disagrees, the linter wins.

## When to use this skill

Use this skill when the user asks to:

- Add a new integration (Stripe, Slack, S3, a database, a queue)
- Wrap a third-party SDK so it can be used inside a capability
- Replace bespoke `process()` calls with a reusable adapter
- Add a transformer that turns one body shape into another

If the user only needs a one-shot data transformation inside a single capability, use `.transform()` with a named function instead (not `.process()`; the create-capability skill records why `.process()` is a last resort). If the work is reusable across capabilities, it belongs in an adapter.

## Step 1: clarify

Before writing, confirm answers to these questions. Ask the user only the ones that are not already obvious from context.

1. **Which roles does the adapter play?** Source (`.from(...)`), Destination (`.to(...)` / `.tap(...)`, push-out), Enricher (`.enrich(...)`, pull-in), Transformer (`.transform(...)`), or several of these?
2. **How is data produced or consumed?** Request/response (HTTP-style)? Polling on an interval? Long-running stream or subscription? Filesystem? Two-sided protocol (server + client like mail)?
3. **Where do options come from?** Per-call options on the factory, or context-wide defaults a plugin provides through a port (`port<T>("owner.capability@1")`, read by the adapter with `context.lookup(PORT)`)?
4. **What is the exchange shape?** What does `body` look like for sources you produce, and what does `body` need to look like for destinations you consume?

## Step 2: pick the closest example

First read [`reference/adapter-structure.md`](reference/adapter-structure.md). It is the file layout, single-factory, class-naming, and options-naming convention every adapter follows; the rest of this skill assumes it.

Then read [`reference/examples-index.md`](reference/examples-index.md) and pick the row that best matches the answers above. The index maps intent to the relevant public doc page and the closest existing adapter on GitHub.

Then, in this order:

1. `WebFetch` the linked doc page (raw markdown variant on `routecraft.dev/raw/docs/...`)
2. `WebFetch` the linked example adapter source on GitHub (use the `raw.githubusercontent.com` URL)
3. If the user is in this monorepo, `Read` `packages/routecraft/src/adapters/<closest>/` end to end. Pay attention to file layout, the factory, the `tagAdapter` call, and the types module
4. Only after that, write the new adapter

Do not write the adapter from memory. The patterns are precise and the examples are short. Read first.

## Step 3: write the adapter

Create the adapter under `packages/routecraft/src/adapters/<concept>/` if you are inside this monorepo, or under your project's `adapters/<concept>/` folder otherwise. Follow [`reference/adapter-structure.md`](reference/adapter-structure.md) for the file layout, the single per-concept factory and how it dispatches by payload, class naming, and the options-naming convention, and mirror the example you read.

The remaining authoring rules to keep in mind while writing:

- **Tagging**: every factory return value goes through `tagAdapter(instance, factory, factoryArgs(...))`, at every return path. The eslint plugin and tests rely on this
- **Store keys**: the adapter's own per-context state goes in the context store under an exported module-level `const` key built with `Symbol.for("routecraft.adapter.<concept>.<key>")` and declared in `StoreRegistry` through a `declare module "@routecraft/routecraft"` augmentation (`getStore` / `setStore` accept only registry keys, so an inline `Symbol.for(...)` does not typecheck). `Symbol.for` keeps the key shared across duplicate package copies in the same process. Anything a plugin hands the adapter (defaults, a client manager) is a port, never a store key another package writes
- **No mutation**: transformers and processors return new objects via spread (`{ ...exchange, body: newBody }`). Do not mutate the incoming exchange
- **Errors**: throw at adapter boundaries with a stable `rc` error code from `@routecraft/routecraft`. Capabilities catch and surface these via the capability-level error handler

## Step 4: write tests

Tests live in the package's `test/` directory: `packages/<pkg>/test/<name>.test.ts`. Do not colocate tests next to source. Every test must have a JSDoc with `@case`, `@preconditions`, `@expectedResult`. Prefer the helpers from `@routecraft/testing`:

- `testContext()` to build an isolated context
- `spy()` for destinations whose payload you want to assert on
- `pseudo("name", options)` for a stand-in source or destination
- `mockAdapter(factory, {...})` to assert how a factory was called

For the full pattern, fetch:

```
https://routecraft.dev/raw/docs/introduction/testing.md
```

## Step 5: verify

Run, in this order, until each is clean:

```bash
bun run typecheck
bun run lint
bun run test
```

Use `bun run <script>` (not `bun <script>`) so Bun invokes the package.json script rather than its built-in test runner. If `bun run lint` complains, fix the code rather than silencing the rule. The linter encodes Routecraft's authoring rules; it is allowed to be stricter than this skill. If the linter does not catch something the user expected it to catch, that is a follow-up for the lint package, not a workaround here.

## Useful URLs

- Adapters reference (every connector, one line each; read it first, the one you need may already ship): https://routecraft.dev/raw/docs/reference/adapters.md
- Operations reference (every verb; behaviour that is an operation does not belong in an adapter): https://routecraft.dev/raw/docs/reference/operations.md
- Creating adapters guide: https://routecraft.dev/raw/docs/advanced/custom-adapters.md
- Adapters introduction: https://routecraft.dev/raw/docs/introduction/adapters.md
- All Routecraft AI-friendly docs index: https://routecraft.dev/llms.txt
Files in this package (3)
  • SKILL.md 7 KB
  • reference/adapter-structure.md 6 KB
  • reference/examples-index.md 4 KB

Versions

RepositoryScoreLicence
This page · routecraftjs/routecraft100Apache-2.0
refractionPOINT/usp-adapters100Apache-2.0
marcus/sidecar100MIT
gtme-run/gtme100Apache-2.0

Database snapshot: 13.11.2026 · package version 4cc7473539ba (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95create-evlog-enricher
    Create a new built-in evlog enricher to add derived context to wide events. Use when adding a new enricher (e.g., for deployment metadata, tenant context, feature flags, etc.) to the evlog package. Covers source code, tests, and all documentation.
  • 100create-capability
    Author a new Routecraft capability (workflow, automation, MCP tool, webhook handler, or scheduled job). Use when the user asks to compose adapters into a pipeline.
  • 100ship-adapter
    Port schemas, interfaces, and API contracts into adapters. Use when writing a DB adapter, API client wrapper, interface adapter, or data transformer.
  • 100response-transformer
    Transform response transformer operations. Auto-activating skill for API Integration. Triggers on: response transformer, response transformer Part of the API Integration skill category. Use when working with response transformer functionality. Trigger with phrases like "response…
  • 95create-evlog-adapter
    Create a new built-in evlog adapter to send wide events to an external observability platform. Use when adding a new drain adapter (e.g., for Elasticsearch, Honeycomb, SigNoz, etc.) to the evlog package. Covers source code, build config, package exports, tests, e2e, and all documentation.
  • 100write-code
    Write or review code in this repo. Use when writing new code, reviewing existing code, or editing code.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.