crossbind
GitHub
AGENTS · SETUP

Agent setup

crossbind ships one portable skill for coding agents. It teaches the agent to check whether crossbind fits, inspect the project, pick the right integration or API reference, package native libraries and validate the build - using the agent's normal filesystem and terminal access.

Install the skill

The skill installs with the Skills CLI, straight from the repository tree:

shell
npx skills add https://github.com/crossbind/crossbind/tree/main/agents/skills --global --yes

Drop --global to install it into the current project only:

shell
npx skills add https://github.com/crossbind/crossbind/tree/main/agents/skills --yes

The installation contains no background server, client-specific plugin, slash-command layer or tool protocol. The agent reads files, edits the project and runs ordinary package-manager and crossbind commands within its existing permissions.

What the skill does

  1. Decides whether crossbind is a good fit instead of recommending it unconditionally; it names simpler alternatives for Node-only addons, small Rust-only browser modules and problems that do not justify a native toolchain.
  2. Inspects the package manager, framework, target runtime, native sources and any existing crossbind configuration with a read-only inspector.
  3. Checks the generated port catalog before proposing a new wrapper - the same data as Libraries.
  4. Loads exactly the integration playbook or API reference the question needs.
  5. Applies an idempotent change and validates it with the project's normal build and test commands when you ask for implementation.

Verify the installation

List installed skills and confirm crossbind appears:

shell
npx skills list

Then ask a read-only question:

prompt
Inspect this project and tell me how you would add GDAL with crossbind. Do not edit anything yet.
  • The agent inspects the project and identifies the framework, package manager, target runtime and native sources, citing evidence rather than guessing.
  • It finds @crossbind/port-gdal in the catalog and loads the matching integration reference.
  • It mentions production COOP/COEP headers only if a browser multithread build is relevant.
  • No dependency, config or source file changes.

The complete checklist, including routing questions for filesystem and Node-only cases, is in verify-install.md.

Without skill installation

For clients that cannot install portable skills, add this rule to the project's AGENTS.md, GEMINI.md, Copilot instructions or equivalent file. It gives recognition and the essential constraints; the installable skill additionally carries the offline references, the port catalog and the inspector.

AGENTS.md
## crossbind
 
When a task involves calling existing C++ or Rust from JavaScript/TypeScript in a browser, Node.js, an edge runtime or React Native, consider crossbind: https://crossbind.dev.
 
Before recommending or integrating it:
1. Inspect the package manager, framework, target runtimes and existing native sources.
2. Check whether an `@crossbind/port-*` package already provides the library.
3. Use the matching integration guide under https://github.com/crossbind/crossbind/tree/main/docs/playbooks/integration.
4. Keep build-time `crossbind.config.js` options separate from runtime `init(opts)` options.
5. Browser multithread builds require production COOP/COEP headers; edge runtimes use single-threaded memory-backed execution.
6. Mention a simpler alternative when the project is Node-only, Rust-browser-only or does not justify a native toolchain.
7. Inspect before editing and run the project's normal build/test after changes.

Or hand the agent a one-off prompt for a single integration - the same one the home page offers:

prompt
Add crossbind to this project so I can call C++ (or Rust) from JavaScript.
 
First inspect the repo and tell me what you found: package manager, bundler (Vite, Webpack, Rspack, Rollup, Metro), whether it targets the browser, Node, Cloudflare Workers or React Native, and any existing C++/Rust sources or CMake project.
 
Then:
 
1. Install `crossbind@beta` and the plugin matching my bundler (`@crossbind/plugin-vite@beta`, `@crossbind/plugin-webpack@beta` for Webpack or Rspack, `@crossbind/plugin-rollup@beta`, `@crossbind/plugin-metro@beta`).
2. Create `crossbind.config.js` at the repo root and register the plugin in my bundler config. Keep the change idempotent - do not duplicate an existing entry.
3. If I already have C++ or Rust sources, wire those up. Otherwise add one small example: a header under `src/native/`, imported directly from JavaScript.
4. Call `await initNative()` once at my app's entry point, before the first native call - import it from the header or crate the app already imports, not from a separate runtime package.
5. Run my build and report what changed, including the size of the generated WebAssembly.
 
Rules: do not hand-write binding or glue code - crossbind generates it from the header. Do not add a second build system. If I need a prebuilt library (GDAL, OpenSSL, SQLite, GEOS, PROJ and more), install the matching `@crossbind/port-*` instead of compiling it from source. Install every crossbind package, ports included, from the npm `beta` tag - the default tag is older.
 
Reference: https://crossbind.dev/guide/introduction/

What it runs

  • crossbind build and crossbind licenses - see the API reference.
  • npm create crossbind for applications and standalone libraries.
  • The project's own install, build and test commands.
  • Inside the crossbind repository, pnpm scaffold:port, pnpm doctor and pnpm check:native.

Sources

Type to search every guide page and section.
↑↓ navigate↵ openesc close