Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# The skills ship in the package as they are written: the same bytes from every checkout.
skills/** text eol=lf
75 changes: 38 additions & 37 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,16 +57,19 @@ with `REPLY_NO_UPDATE_CHECK=1` set.

## Where this fits

Reply's agentic toolkit is three pieces. They are complementary, not alternatives:
Reply's agentic toolkit is two pieces, with the skills that teach an agent to use them
carried in this package. They are complementary, not alternatives:

| | What it is | When you want it |
|---|---|---|
| **reply CLI** (this repo) | `npm i -g reply-cli` — authenticated access to *every* v3 endpoint via `reply api` | Your agent has a shell. This is the complete surface. |
| **reply CLI** (this repo) | `npm i -g reply-cli` — authenticated access to *every* v3 endpoint via `reply api`, and the Reply skills (`reply skills install`) | Your agent has a shell. This is the complete surface. |
| **[Reply MCP](https://github.com/reply-team/reply-mcp)** | A curated tool catalog over `mcp.reply.io` | Your client speaks MCP and has no shell — desktop apps, hosted assistants. |
| **[reply-skills](https://github.com/reply-team/reply-skills)** | Outbound expertise as markdown skills: what to do, in what order, with what guardrails | Your agent knows *how* to call things but not *what* to run. |

MCP gives your agent tools. Skills give it judgement. Most setups want both; a shell-capable
agent can do everything through the CLI alone.
The skills teach an agent how to perform an SDR operation against Reply: which endpoint, which
scope, in what order, and what Reply's errors mean. The vendor-neutral SDR expertise — the
operation catalogue, playbooks and guardrails those skills map onto — and the runtime skills ship
with [Jason](https://github.com/reply-team/jason-ai), the catalogue under its `skills/business`.
A shell-capable agent can do everything through the CLI alone.

The shortest path that works: install the CLI, `reply auth login`, `reply skills install`, then
talk to your agent in plain words. MCP is optional — add it when your client has no shell.
Expand Down Expand Up @@ -525,55 +528,53 @@ exist. PowerShell, cmd, macOS and Linux are unaffected.

## 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:
The Reply skills ship inside this package as one pack, `reply-adapter` (alias
`adapter`), at the CLI's own version: `reply-api`, `reply-auth`, `reply-cli`,
`reply-mcp` and `reply-operations-mapping`. One command copies them into every
AI assistant on your machine, from the installed package, with no download:

```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
✓ Claude Code · reply-adapter installed
✓ Codex · reply-adapter 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
reply skills list # what's installed where, and at which version
reply skills update # bring the installed skills to the version of this CLI
reply skills remove # remove everything this CLI installed
```

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
The skills move with the CLI: after `reply install` brings a newer CLI,
`reply skills update` copies its skills over the old ones. Every assistant
receives 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 | Skills path | Paths verified | To take effect |
An earlier version of this CLI installed three packs, and installed them on
Claude Code and Codex through the assistant's own plugin CLI. `install` and
`update` now replace the old `reply-adapter` plugin with the copied
files, removing that plugin through the assistant's own CLI, and say so; the
two other plugins, and copies of the two other packs, stay installed, and the
report names them. `list` and
`remove` still find what an earlier version installed, under the old pack
names too.

| Assistant | How it receives the skills | Skills path | Paths verified | To take effect |
|---|---|---|---|---|
| Claude Code | its own plugin CLI | managed by the plugin CLI | yes | start a new session |
| Codex | its own plugin CLI (`--project` copies files instead) | managed by the plugin CLI | yes | start a new session |
| Claude Code | copied files | `~/.claude/skills`, or `.claude/skills` with `--project` | yes | start a new session |
| Codex | copied files | `~/.agents/skills`, or `.agents/skills` with `--project` | yes | start a new session |
| Cursor | copied files | `~/.cursor/skills`, or `.agents/skills` with `--project` | Cursor 3.14.27, cursor-agent 2026.08.04-aaa8809 | a new session (a new chat) |
| Windsurf (ships as Devin) | copied files | `~/.codeium/windsurf/skills`, or `.windsurf/skills` with `--project` | Devin 3.6.27, devin CLI 3000.3.27 | a new session (the next `devin` run) |
| Antigravity | copied files | `~/.gemini/config/skills`, or `.agents/skills` with `--project` | Antigravity 2.0.1 | nothing — it re-reads its skills every turn, including in a conversation already open |
Expand All @@ -585,10 +586,9 @@ Codex, Antigravity and GitHub Copilot. A project-scope install aimed at one of
them therefore makes those skills visible in the others, and removing them for
one changes what the others see. Use user scope when you want a host's skills to
itself. GitHub Copilot reads two further repository directories, `.claude/skills`
and `.github/skills`. This command never writes to either — Claude Code installs
through its own plugin CLI in both scopes — so that crossover appears only when
something else fills them: a skill copied there by hand, or the `npx skills`
channel, which writes `.claude/skills` for a project-scoped Claude Code install.
and `.github/skills`; `--project` for Claude Code writes `.claude/skills`, so a
project-scope install for Claude Code is visible to GitHub Copilot in that
repository too.

Every assistant in the table has been verified against the version named. A host
added later may arrive with its skills directory taken from the vendor's
Expand All @@ -600,8 +600,9 @@ Antigravity and GitHub Copilot with the release that adds them.
GitHub Copilot is two products over one directory: the `copilot` CLI and the
VS Code agent host, which ships `~/.copilot/skills` among the defaults of its
`chat.agentSkillsLocations` setting — alongside `~/.claude/skills` and
`~/.agents/skills`, user directories the CLI itself does not read. The CLI is
what the row above was verified against. VS Code scans those directories once per window and does not watch them,
`~/.agents/skills`, user directories the CLI itself does not read and where this
command puts the skills for Claude Code and Codex, so VS Code sees those too.
The CLI is what the row above was verified against. VS Code scans those directories once per window and does not watch them,
so an install made while it is open needs `Developer: Reload Window` rather than
just a new chat.

Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
},
"files": [
"dist",
"skills",
"README.md"
],
"devDependencies": {
Expand Down
82 changes: 44 additions & 38 deletions scripts/smoke-hosts.mjs
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
// Verifies `reply skills install` end to end, against real and simulated assistants.
//
// Not part of `npm test`: it clones from GitHub, and exercising a native host for
// real needs that assistant installed on the machine. It is safe to run on a
// working machine because:
// - Native hosts (Claude Code, Codex) are pointed at throwaway config directories
// via CLAUDE_CONFIG_DIR and CODEX_HOME. They are only *genuinely* exercised
// (real binary resolved from the real PATH) when really installed — otherwise
// they still appear in the report with status 'skipped'.
// - Flat-directory hosts (Cursor, Gemini CLI, GitHub Copilot) are always
// Not part of `npm test`: reaching the plugin CLI of Claude Code or Codex for
// real needs that assistant installed on the machine. Every host receives the
// skills as files copied from this package. It is safe to run on a working
// machine because:
// - Claude Code and Codex are pointed at throwaway config directories via
// CLAUDE_CONFIG_DIR and CODEX_HOME. Their plugin CLI, asked only about the
// plugins an earlier version installed, is reached only when the real binary
// resolves from the real PATH; without it they are reported 'skipped'.
// - The other hosts (Cursor, Antigravity, GitHub Copilot, Windsurf) are always
// *simulated* inside the sandbox below, regardless of what is really on this
// machine. That is deliberate: it is the only way the flat-directory install
// path gets exercised at all, on any machine. Do not read a flat host's 'ok'
// status here as evidence that assistant is really installed.
// machine. Do not read their 'ok' status here as evidence that assistant is
// really installed.
// - Both rely on HOME/USERPROFILE being redirected to the sandbox. That is not
// assumed: before anything mutating runs, a child process given the exact same
// env is asked what os.homedir() resolves to, and the run aborts without
Expand Down Expand Up @@ -98,6 +98,7 @@ const real_reply_config_dir = ()=>{
const snapshot_state = ()=>{
const real_home = os.homedir();
const paths_to_check = [
path.join(real_home, '.claude', 'skills'),
path.join(real_home, '.copilot'),
path.join(real_home, '.copilot', 'skills'),
path.join(real_home, '.cursor'),
Expand Down Expand Up @@ -241,19 +242,17 @@ try {
const installed = JSON.parse(cli('skills', 'install', '--json'));
console.log(`hosts: ${installed.hosts.map(h=>`${h.host}=${h.status}`).join(' ') || '(none detected)'}`);

// Flat hosts are always simulated (see header), so `installed.hosts`
// is never actually empty on any machine with git on PATH — the
// brief's original "no assistant at all" exit is dead code below.
// What is real and worth reporting is whether a *native* host (the
// only kind that is only exercised when genuinely installed) was
// actually present: status 'skipped' means its config directory
// marker existed but the real binary could not be resolved from
// the real PATH, i.e. it is not really installed here.
const native_ids = new Set(['claude-code', 'codex']);
const native_present = installed.hosts.some(h=>native_ids.has(h.host) && h.status !== 'skipped');
console.log(native_present
? '✓ at least one native assistant (Claude Code/Codex) is really installed and was exercised for real'
: 'ℹ no native assistant (Claude Code, Codex) is really installed on this machine — only the always-simulated flat hosts were exercised');
// The simulated hosts (see header) mean `installed.hosts` is never
// empty in practice. What is real and worth reporting is whether
// Claude Code or Codex, detected only when the real binary resolves,
// was actually present: status 'skipped' means its config directory
// marker existed but the binary could not be resolved from the real
// PATH, i.e. it is not really installed here.
const cli_hosts = new Set(['claude-code', 'codex']);
const cli_present = installed.hosts.some(h=>cli_hosts.has(h.host) && h.status !== 'skipped');
console.log(cli_present
? '✓ Claude Code or Codex is really installed and was exercised for real'
: 'ℹ neither Claude Code nor Codex is really installed on this machine — only the simulated hosts were exercised');

if (!installed.hosts.length)
{
Expand All @@ -267,9 +266,9 @@ try {
{
fail('no host reported ok');
}
if (installed.resolved.join(',') !== 'ai-sdr-core,reply-adapter,agentic-runtime')
if (installed.resolved.join(',') !== 'reply-adapter')
{
fail(`unexpected resolve order: ${installed.resolved.join(',')}`);
fail(`unexpected packs: ${installed.resolved.join(',')}`);
}

// Idempotency: the second run must change nothing.
Expand All @@ -280,20 +279,27 @@ try {
fail(`re-install was not idempotent: ${actions.join(',')}`);
}

// Selective install pulls the core.
cli('skills', 'remove', '--json');
const selective = JSON.parse(cli('skills', 'install', 'adapter', '--json'));
if (selective.resolved.join(',') !== 'ai-sdr-core,reply-adapter')
{
fail(`selective install did not pull the core: ${selective.resolved.join(',')}`);
// A pack this CLI no longer ships is refused as a usage error.
try {
cli('skills', 'install', 'core', '--json');
fail('installing a pack this CLI no longer ships was allowed');
} catch (e) {
if (e.status === 2)
{
console.log('✓ a pack this CLI no longer ships is refused with exit 2');
}
else
{
fail(`installing a pack this CLI no longer ships exited ${e.status}, not 2`);
}
}

// Removing the core alone must be refused.
try {
cli('skills', 'remove', 'core', '--json');
fail('removing the core while the adapter is installed was allowed');
} catch {
console.log('✓ removing a needed dependency is refused');
// Remove with no pack takes everything away again.
const removed = JSON.parse(cli('skills', 'remove', '--json'));
const left = removed.hosts.flatMap(h=>(h.packs ?? []).filter(p=>p.action !== 'removed'));
if (left.length)
{
fail(`remove left packs behind: ${left.map(p=>`${p.name}=${p.action}`).join(',')}`);
}
}
}
Expand Down
Loading
Loading