# Bridge skill propagation: how a bridge's docs reach the AI

A bridge is code that runs on your Windows desktop, right next to Adom Bridge. It drives
KiCad, a browser, Blender, whatever app it was written for. It has to run there, because
that is where the app is.

The AI that calls the bridge does not run there. It runs in a cloud container, and that
is where it looks for its local skills (its documentation), in `~/.claude/skills/` or
`~/.codex/skills/`.

So installing a bridge onto your desktop hands the AI a set of new abilities it has no
documentation for. The runtime and the docs are two separate things, they end up in two
separate places, and they get there by two different routes. This page explains how they
find each other.

## The two artifacts

Every bridge publishes two things to its own wiki page:

| | The release zip | The skills package |
|---|---|---|
| What it contains | Server code plus `bridge.json` | Text documentation only, a few KB |
| Where it goes | The desktop | The cloud container |
| How it gets there | `bridge_install {manifestUrl}` streams it, unzips it, and spawns it | `adom-wiki pkg install adom/<slug>` |
| Where it lands | Adom Bridge's bridge cache | `~/.claude/skills/` and `~/.codex/skills/` |

Same bridge, two destinations, two mechanisms. Neither one substitutes for the other.
Installing the runtime does not give the AI docs, and installing the skills does not give
your desktop anything to run.

## How a container finds out which skill it needs

This is the piece that connects the two halves.

1. A bridge declares `docs` in its `bridge.json`, pointing at its own wiki page.
2. Adom Bridge derives the skill package name, `adom/<slug>`, from that `docs` URL. It
   takes the last path segment. (It deliberately does not derive the name from the
   manifest URL, which is owner-qualified and would give the wrong answer.)
3. `bridge_list` returns, for each bridge, a `skillPkg` field (the package name) and an
   `installSkill` field (the exact, ready-to-run install line), plus a top-level
   `_skillsHint`.

So an AI in any container can ask your desktop what it has, and get back the literal
command that fixes its own missing documentation. It never has to guess a package name.

A `skillPkg` of null means there is nothing separate to install: the skill is already part
of the Adom Bridge core package, or the bridge does not ship one.

## The one command, and the self-healing

```bash
adom-bridge-cli sync_skills
```

That collects every non-null `skillPkg` from every connected desktop and installs each
one. It is idempotent, so running it again costs nothing. It fans out across multiple
desktops and takes the union, so a container talking to two machines gets the skills for
both.

You do not normally have to run it. The CLI runs it opportunistically in the background,
at most once a day. That runs in containers only (the desktop host itself is skipped), and
`ADOM_SKILL_SYNC=0` opts out.

The daily run is what makes the awkward case work. A container that connects a week after
you installed a bridge, and that never asked your desktop to install anything, still ends
up with the right documentation, hands-off.

## Why bridge skills are not in Adom Bridge's own package

The cloud-owned bridges (KiCad, Fusion, Blender, Puppeteer, the browser extension) each
own their wiki page and their own skill package. Their docs are not bundled into the
adom-bridge core package, and that is deliberate.

Bundling would mean the docs go stale the moment a bridge ships an update, and it would
mean cutting an Adom Bridge release every time someone else's project changed a
paragraph. Each bridge ships its own skills on its own cadence, which is the only
arrangement that keeps a fast-moving bridge's documentation accurate.

## What does not belong in the skills tarball

The skills package is text and nothing else. Specifically, it should not contain:

- **Hero images or screenshots.** A container never renders them. One real bridge shipped
  a 1 MB hero in its tarball, which was pure download bloat on every single install.
- **The release zip.** That is the other artifact, and it goes to the desktop.
- **The source tree or any binaries.** A consumer container does not build the bridge.
- **Dev skills and publish skills.** Dev skills are for whoever edits the bridge, publish
  skills are for whoever releases it. Both stay in the source repo, where a developer who
  checks out the code gets them automatically. A consumer container has no use for either.

Only user skills ship. If you are looking at a bridge's tarball and it is measured in
megabytes, something is in there that should not be.

## What this looks like when it works

You install a bridge on your desktop, from the Bridges sidebar or with `bridge_install`.
The card appears, and the bridge is ready to run.

The AI in your container asks the desktop what is available. It gets back the bridge, and
alongside it, the install line for that bridge's skills. It runs that line. The skills
land in its own skills folder.

From that point on it drives the bridge's verbs with real documentation in front of it,
instead of guessing at argument names and reading error messages to find out what it got
wrong.

One thing to expect: the runtime on your desktop and the docs in your container can
legitimately sit at different versions, because they update on independent schedules. The
desktop's copy refreshes from the bridge's wiki page on a periodic sweep; the container's
copy refreshes when skills are synced. That is normal, and usually invisible.

## For bridge authors

If you are publishing a bridge rather than using one, the Bridge SDK on the
`adom-bridge` wiki page has the publishing detail: what belongs in each artifact,
how to declare `docs` so the skill package name resolves, and how to ship both halves
together.