@vruum/skills 0.4.11 → 0.4.13

package/README.md

@@ -6,29 +6,54 @@ Pairs with the Vruum MCP server at [https://api.vruum.ai/mcp](https://api.vruum.
 
 ## Install
 
-### Claude Code / Cursor / VS Code Copilot / Cline
+### Claude Code
 
-Add the Vruum MCP server as a connector. Slash commands appear automatically — you don't need this npm package.
+Add to `~/.claude.json`:
 
-```bash
-claude mcp add --transport http --scope user vruum https://api.vruum.ai/mcp
+```json
+{
+  "mcpServers": {
+    "vruum-local": { "type": "http", "url": "https://api.vruum.ai/mcp" }
+  }
+}
 ```
 
-### Claude Desktop / Claude.ai (Cowork)
+Slash commands appear automatically once registered. You don't need this npm package for Claude Code.
 
-Install the Vruum plugin via the official plugin directory — bundles the connector and slash commands in one step:
+### Codex CLI
 
-[github.com/vruum-gtm/skills/releases/latest/download/vruum-plugin.zip](https://github.com/vruum-gtm/skills/releases/latest/download/vruum-plugin.zip)
+Add to `~/.codex/config.toml`:
 
-Download and upload via **Settings → Customize → Plugins → "+"**.
+```toml
+[mcp_servers.vruum-local]
+url = "https://api.vruum.ai/mcp"
+```
 
-### Codex CLI / ChatGPT / other harnesses
+Then run this installer to bring the skill bundle into your Codex skills directory:
 
 ```bash
 npx @vruum/skills install
 ```
 
-Detects Codex CLI (`~/.codex/skills/`). For other harnesses:
+Detects `~/.codex/skills/` automatically. For other harnesses without a known path:
+
+```bash
+npx @vruum/skills install --target /path/to/skills/dir
+```
+
+### Cursor / VS Code Copilot / Cline
+
+Register the MCP server via your editor's MCP setup (each one has its own UI / config path). Connect to `https://api.vruum.ai/mcp` (HTTP, OAuth via standard MCP flow). Skills surface as slash commands automatically — you don't need this npm package.
+
+### Claude Desktop / Claude.ai (Cowork)
+
+Install the Vruum plugin via the official plugin directory — bundles the connector and slash commands in one step:
+
+[github.com/vruum-gtm/skills/releases/latest/download/vruum-plugin.zip](https://github.com/vruum-gtm/skills/releases/latest/download/vruum-plugin.zip)
+
+Download and upload via **Settings → Customize → Plugins → "+"**.
+
+### ChatGPT / Windsurf / other harnesses without MCP prompts
 
 ```bash
 npx @vruum/skills install --target /path/to/skills/dir

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Vruum AI skills for Claude Code, Claude Desktop, Codex CLI, and any AI assistant with a skill directory. Slash commands for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis. Pairs with the Vruum MCP server at https://api.vruum.ai/mcp.",
   "license": "MIT",
   "repository": {
@@ -36,5 +36,5 @@
     "outreach",
     "gtm"
   ],
-  "contentHash": "e97fce36e8e7631ac79518a817736db2ecca21a991ac08fd9a03264e7c494a9e"
+  "contentHash": "a3981e97abb16b2688efd1fc76f8565288dd9006aea5d1a200a6bb8f9561f874"
 }

package/skills/engagement-triage/SKILL.md

@@ -38,7 +38,7 @@ Reviewing inline burns tokens fast. Subagents with their own context windows do
 
 This skill dispatches the `vruum-engagement-reviewer` subagent (bundled at `agents/vruum-engagement-reviewer.md`). That agent reviews both engagement items AND content posts.
 
-**Dispatch via the Agent tool** with `subagent_type: "vruum-engagement-reviewer"`. Supports `run_in_background=true` for parallelism.
+**Dispatch a subagent of role `vruum-engagement-reviewer`** via your runtime's native subagent mechanism (Claude Code's `Agent` tool with `subagent_type`; Codex's equivalent). Supports `run_in_background=true` for parallelism.
 
 Falls back to general-purpose subagent with MCP tool names in the prompt if the subagent type isn't recognized.
 

package/skills/outreach-triage/SKILL.md

@@ -30,7 +30,7 @@ This skill uses the custom agent `vruum-outreach-reviewer` (bundled at `agents/v
 - Web search for prospect research
 - Complete review instructions baked into its system prompt
 
-**Dispatch via the Agent tool** with `subagent_type: "vruum-outreach-reviewer"`. Supports `run_in_background=true` for parallelism. Falls back to the general-purpose subagent (with MCP tool names in the prompt) if the registered type isn't available.
+**Dispatch a subagent of role `vruum-outreach-reviewer`** via your runtime's native subagent mechanism (Claude Code's `Agent` tool with `subagent_type`; Codex's equivalent). Supports `run_in_background=true` for parallelism. Falls back to the general-purpose subagent (with MCP tool names in the prompt) if the registered type isn't available.
 
 For small queues (5 or fewer) or when subagents can't access MCP, review directly in the main session.
 

package/skills/pipeline-fill/RESEARCH-ENGINE.md

@@ -41,7 +41,7 @@ Before any other Step 3 work, call `get_research_playbook(segment_id=<id>)`. If
 
 > Vruum MCP not configured as a user-scoped server. Run:
 >
-> `claude mcp add --transport http --scope user vruum https://api.vruum.ai/mcp`
+> Register the Vruum MCP server in your assistant once: Claude Code → `~/.claude.json` `mcpServers.vruum-local = {"type":"http","url":"https://api.vruum.ai/mcp"}`; Codex CLI → `~/.codex/config.toml` `[mcp_servers.vruum-local]` with `url = "https://api.vruum.ai/mcp"`; other assistants → connect to `https://api.vruum.ai/mcp` (HTTP, OAuth via standard MCP flow).
 >
 > and retry. (The cloud `claude.ai Vruum` connector doesn't propagate to subagents — they need `vruum` configured at the user scope in `~/.claude.json`.)
 

package/skills/pipeline-fill/SKILL.md

@@ -43,19 +43,19 @@ This skill uses two subagents (defined in `.claude/agents/`):
 
 ### MCP access requirements (load-bearing)
 
-Subagents can only access Vruum MCP if `vruum` is configured as a **user-scoped HTTP MCP server** in `~/.claude.json`. Cloud MCP servers (`claude.ai Vruum`) are NOT inherited by subagents.
+Subagents need access to the Vruum MCP server. Register it once in your AI assistant:
 
-To set up: `claude mcp add --transport http --scope user vruum https://api.vruum.ai/mcp` (one-time, requires OAuth).
+- **Claude Code**: `~/.claude.json` → `mcpServers.vruum-local` = `{"type": "http", "url": "https://api.vruum.ai/mcp"}`
+- **Codex CLI**: `~/.codex/config.toml` → `[mcp_servers.vruum-local]` with `url = "https://api.vruum.ai/mcp"`
+- **Other**: connect to `https://api.vruum.ai/mcp` (HTTP, OAuth via standard MCP flow)
 
-The orchestrator's MCP precheck at the top of Step 3 (`get_research_playbook` call) catches this misconfiguration upfront with a clear error message. Don't skip it.
+The orchestrator's MCP precheck at the top of Step 3 (`get_research_playbook` call) catches misconfiguration upfront. Don't skip it.
 
 ### Dispatch methods (in order of preference)
 
-1. **Agent tool** (primary): Spawn subagents via the Agent tool with `subagent_type: vruum-company-deep-researcher` or `vruum-prospect-deep-researcher`. Subagents inherit local MCP servers from `~/.claude.json` and call Vruum tools directly. Use `run_in_background=true` for waves; wait for the wave to complete before dispatching the next.
+1. **Subagent dispatch** (primary): Use your runtime's native subagent mechanism (Claude Code's `Agent` tool with `subagent_type: vruum-company-deep-researcher` / `vruum-prospect-deep-researcher`; Codex's equivalent). Subagents should inherit MCP access from the runtime config. Run waves of up to 10 company-research subagents and up to 5 prospect-research subagents in parallel.
 
-2. **CLI dispatch**: `claude --agent vruum-{company,prospect}-deep-researcher --allowedTools "mcp__vruum-local__*" -p "<prompt>" --output-format text --max-turns 20`. Use only if Agent tool subagents can't reach MCP.
-
-3. **Inline**: For very small fills (1–3 prospects) where dispatching subagents is overhead, run the research inline in the main session.
+2. **Inline**: If subagents can't reach Vruum MCP in your runtime, run the research inline in the main session instead. Do NOT bounce through another CLI as a workaround — that is a runtime-configuration problem to surface to the user.
 
 ## Inputs
 

package/skills/segment-doctor/SKILL.md

@@ -32,10 +32,11 @@ Use **UTC** dates in `YYYY-MM-DD` format. The backend filters use inclusive `gte
 
 If `get_segments` returns no segments, tell the user "No segments yet — create one in the Vruum app before running diagnosis" and stop.
 
-Classify each segment by reply rate (from `diagnose_segment` output):
+Classify each segment by reply rate (from `diagnose_segment` output). Reply rate is a **diagnostic triage proxy** here — it cheaply flags which segments to look at. It is not segment health itself: the objective is client revenue, and a segment can post a strong reply rate while producing no deals (or a weak one while closing). Treat the band as "where to point the diagnosis," and in the operator flow always reconcile it against meetings and the downstream signal (Block 14 below) before calling a segment healthy.
+
 - **CRITICAL** — 30-day reply rate < 5% with ≥20 sent
 - **WARNING** — 30-day reply rate 5–10% with ≥20 sent
-- **HEALTHY** — 30-day reply rate ≥ 10%
+- **HEALTHY** — 30-day reply rate ≥ 10% (reply-rate-healthy — confirm it also produces meetings/deals before treating it as truly healthy)
 - **INSUFFICIENT DATA** — `diagnose_segment` returned `insufficient_data: true` (fewer than 20 sent in 30d)
 
 For WoW delta, compute `(current_reply_rate - prior_reply_rate) / prior_reply_rate`. Guards: