reply-team · ArtemKosolap · Jul 31, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/.gitignore b/.gitignore
@@ -2,3 +2,4 @@ node_modules/
 dist/
 *.tgz
 coverage/
+.superpowers/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -24,6 +24,19 @@ server. `fetch` is stubbed, and the OAuth loopback flow is exercised against a
 local `127.0.0.1` listener with an injected browser stub. CI runs the build and
 tests on Linux and Windows.
 
+`npm run smoke:hosts` is a separate check that runs `reply skills install`
+entirely inside a throwaway `HOME`/`USERPROFILE` sandbox, and proves your real
+home is untouched with a before/after filesystem snapshot. Native hosts
+(Claude Code, Codex) are only genuinely exercised when actually installed —
+each is additionally pointed at a throwaway config directory
+(`CLAUDE_CONFIG_DIR`, `CODEX_HOME`) so its real plugin state is untouched
+either way. Flat-directory hosts (Cursor, Gemini CLI, GitHub Copilot) are
+always *simulated* inside the sandbox, regardless of what is really on your
+machine — that's deliberate, since it's the only way the flat-directory
+install path gets exercised at all. It is not part of `npm test` because it
+clones from GitHub and, for native hosts, needs a real assistant installed to
+exercise for real.
+
 ## Conventions
 
 - Data is written to stdout; status and error messages go to stderr.

diff --git a/README.md b/README.md
@@ -129,6 +129,68 @@ It prints `{ "code": <status>, "data": <body> }` and exits non-zero on HTTP
 stderr. Add `--verbose` for a full request/response trace on stderr with
 credentials redacted; stdout stays the plain JSON, so pipes keep working.
 
+## Skills
+
+Reply's outbound expertise ships as three markdown skill packs in
+[reply-skills](https://github.com/reply-team/reply-skills). One command installs
+them into every AI assistant on your machine, dependencies resolved:
+
+```sh
+reply skills install
+```
+
+```
+✓ detected Claude Code, Codex
+✓ Claude Code · ai-sdr-core, reply-adapter, agentic-runtime installed
+✓ Codex       · ai-sdr-core, reply-adapter, agentic-runtime installed
+Start a new session in each assistant so the skills load.
+```
+
+| Pack | Alias | What it gives your agent |
+|---|---|---|
+| `ai-sdr-core` | `core` | Vendor-neutral SDR operations, playbooks and guardrails |
+| `reply-adapter` | `adapter` | Executing those operations against Reply.io |
+| `agentic-runtime` | `runtime` | Durable multi-session work: plans, checkpoints, reports |
+
+Install a subset — dependencies come along automatically, so `adapter` pulls
+`core`:
+
+```sh
+reply skills install core
+reply skills install adapter runtime
+reply skills install --agent codex        # only this assistant
+reply skills install --project            # into this repository, not your home
+```
+
+Then manage them:
+
+```sh
+reply skills list             # what's installed where (notes packs with an update available)
+reply skills update           # bring installed packs to the latest version
+reply skills remove runtime   # remove one pack
+reply skills remove           # remove all of them
+```
+
+On Claude Code and Codex the packs are installed through the assistant's own
+plugin mechanism, so they keep updating through it. Other `SKILL.md` hosts
+receive the skills as files. Add `--json` for a machine-readable report, and
+`--dry-run` to see the plan without changing anything.
+
+| Assistant | How it receives the packs | Paths verified |
+|---|---|---|
+| Claude Code | its own plugin CLI | yes |
+| Codex | its own plugin CLI (`--project` copies files instead) | yes |
+| Cursor · Gemini CLI · GitHub Copilot · Windsurf | copied files | not yet |
+
+"Not yet" means the skills directory for that assistant comes from its
+documentation and has not been confirmed by a verification run of our own
+(REPLY-51268): the install works, but we cannot promise the assistant reads
+from where we put the files. Those hosts are marked `(paths not yet verified)`
+in the report and carry `"verified": false` in `--json`.
+
+Installing skills is not the same as connecting Reply: `reply-adapter` needs a
+Reply.io login (`reply auth login`) to actually do anything.
+
 ## Environment variables
 
 | Variable | Description |

diff --git a/package.json b/package.json
@@ -13,6 +13,7 @@
         "clean": "rm -rf dist",
         "test": "vitest run",
         "test:watch": "vitest",
+        "smoke:hosts": "node scripts/smoke-hosts.mjs",
         "prepare": "husky"
     },
     "author": "Reply.io",
-Original file line number
+Diff line change
@@ Expand Up / @@ -2,3 +2,4 @@ node_modules/ @@
     dist/
     *.tgz
     coverage/
+    .superpowers/