# Bridge skill templates

Fill-in-the-blanks starting points for the **three kinds of skill** every Adom Desktop
bridge ships (see [`../BRIDGE_SDK.md`](../BRIDGE_SDK.md) → "The SKILL SET you should ship").
Generalized from the Puppeteer (pup) bridge's battle-tested set.

| Template | For whom | Goes where |
|---|---|---|
| [`bridge-dev-template.md`](bridge-dev-template.md) | whoever **edits** the bridge | your wiki page, source-only as `dev-skills/*.md` |
| [`bridge-publish-template.md`](bridge-publish-template.md) | your **publish/release** thread | your wiki page, source-only as `dev-skills/*.md` |
| [`bridge-user-skill-template.md`](bridge-user-skill-template.md) | a **cloud container** driving your verbs | your `adom-wiki pkg` tarball as `SKILL.md` |

## How to use

1. Copy the template you need.
2. Replace `<bridge>` (your bridge's slug, e.g. `blender`) and `<prefix>` (your verb prefix,
   e.g. `blender_`) everywhere.
3. Delete sections that don't apply; fill in your verbs.

**Keep the caller-provenance sections.** The dev template's "Caller provenance" section (the
`X-Adom-Caller-*` headers you receive, and the ones you must forward on your own AD callbacks) and the
user template's "Identify yourself on every call" section are contract, not decoration: AD refuses an
unidentified relayed call with `errorCode: caller_identity_required`, and a bridge that drops the headers
breaks the user's attribution chain. Full detail lives in AD's `adom-desktop-caller-identity` skill.

## The two naming rules that bite

- **Only the USER skill may be named `SKILL.md`.** The wiki indexes EVERY `SKILL.md` in your
  pkg tarball as an installable, Skills-tab-listed user skill — so the DEV + PUBLISH skills must
  be named `dev-skills/*.md` (source-only on your page), or every user who installs your pkg also
  installs your dev/publish docs.
- **THE ONE PRINCIPLE:** the AI almost never reads your on-disk skill — it reads your verb
  **OUTPUT**. The templates exist for the human author and the publish flow; your real leverage is
  the `_hint`/`_next`/`related`/`pitfalls` you return on **every** verb response. The
  user-skill template's eight conventions all reinforce this.