@vruum/skills 0.6.2 → 0.6.4

package/README.md

@@ -2,7 +2,7 @@
 
 Vruum AI skills for Claude Code, Codex CLI, and any AI assistant with a skill directory.
 
-Pairs with the Vruum MCP server at [https://api.vruum.ai/mcp](https://api.vruum.ai/mcp). For MCP-native clients (Claude Code, Claude Desktop, Cursor, VS Code Copilot, Cline), connecting to the MCP URL surfaces these skills as native slash commands. This npm package is for assistants that don't yet support MCP prompts (Codex CLI, ChatGPT, Windsurf).
+Pairs with the Vruum MCP server at [https://api.vruum.ai/mcp](https://api.vruum.ai/mcp). The MCP server exposes the `invoke_skill` tool (alongside `list_skills` / `get_skill` / `publish_skill`) so any connected client can run these skills. Skills themselves are distributed via the Claude Code plugin / marketplace; this npm package installs them into the agent-standard skills directory for harnesses without plugin support (Codex CLI, ChatGPT, Windsurf).
 
 ## Install
 
@@ -18,7 +18,7 @@ Add to `~/.claude.json`:
 }
 ```
 
-Slash commands appear automatically once registered. You don't need this npm package for Claude Code.
+Install the skills via the Claude Code plugin / marketplace (below); the MCP server provides the `invoke_skill` tool. You don't need this npm package for Claude Code.
 
 ### Codex CLI
 
@@ -45,17 +45,17 @@ npx @vruum/skills install --target /path/to/skills/dir   # any other harness
 
 ### 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.
+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). The `invoke_skill` tool becomes available — to also install the skill files locally, use this npm package's `install --target` below.
 
 ### Claude Desktop / Claude.ai (Cowork)
 
-Install the Vruum plugin via the official plugin directory — bundles the connector and slash commands in one step:
+Install the Vruum plugin via the official plugin directory — bundles the connector and the skills 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
+### ChatGPT / Windsurf / other harnesses without plugin support
 
 ```bash
 npx @vruum/skills install --target /path/to/skills/dir

package/install.js

@@ -2,12 +2,12 @@
 /**
  * @vruum/skills installer.
  *
- * For AI assistants that don't natively support MCP prompts (Codex CLI,
+ * For AI assistants without Claude Code plugin support (Codex CLI,
  * ChatGPT, Windsurf) — installs SKILL.md files into the target harness's
- * skill directory so slash commands still work. For clients that DO
- * support MCP prompts (Claude Code, Claude Desktop, Cursor, VS Code,
- * Cline), you don't need this — just connect to https://api.vruum.ai/mcp
- * and slash commands appear automatically.
+ * skill directory so the skills are available locally. For Claude Code,
+ * install the skills via the plugin / marketplace instead; in every case
+ * the Vruum MCP server at https://api.vruum.ai/mcp provides the
+ * `invoke_skill` tool to run a skill on demand.
  *
  * Zero runtime dependencies — stdlib Node only.
  *
@@ -123,9 +123,9 @@ Usage:
   npx @vruum/skills uninstall                Remove previously-installed symlinks
   npx @vruum/skills list                     Show detected targets + what's installed
 
-Pairs with the Vruum MCP server at https://api.vruum.ai/mcp. Connect your AI
-assistant to that URL first, then these skills turn common workflows into
-slash commands.
+Pairs with the Vruum MCP server at https://api.vruum.ai/mcp, which provides
+the invoke_skill tool. This installer puts the SKILL.md files into a harness's
+local skill directory so the skills are available there too.
 
 Supported auto-detection:
   - Claude Code  ~/.claude/skills/
@@ -133,11 +133,10 @@ Supported auto-detection:
 
 Any other harness: pass --target <its skills directory>.
 
-Note: Claude Code, Claude Desktop, Cursor, VS Code Copilot, and Cline all
-support MCP prompts natively. If you use one of those, you don't need this
-installer — connecting to https://api.vruum.ai/mcp surfaces slash commands
-automatically. This installer is for Codex CLI, ChatGPT, Windsurf, and
-other assistants that don't yet support MCP prompts.`);
+Note: for Claude Code, install the skills via the Vruum plugin / marketplace
+instead of this installer. This installer is for Codex CLI, ChatGPT, Windsurf,
+and other assistants without plugin support. In every case the MCP server's
+invoke_skill tool can run a skill on demand.`);
 }
 
 function listAvailableSkills() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "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": {
@@ -39,5 +39,5 @@
     "outreach",
     "gtm"
   ],
-  "contentHash": "753b0d94ad80acaf1986cadaa6502df2a6b6f32a913ec9b39349922331378345"
+  "contentHash": "d630c9b27e3423b309b80927c4a24d30372ac614826a3539d8e0a089723d5ca2"
 }

package/skills/campaign-doctor/SKILL.md

@@ -5,24 +5,24 @@ description: >-
   diagnose campaign, why is my campaign not working, campaign health, low reply
   rate, check campaigns, which campaigns need help.
 ---
-# Segment Doctor
+# Campaign Doctor
 
-You are a segment diagnostics and optimization agent. Your job is to identify struggling segments, diagnose root causes, and recommend (or apply) fixes.
+You are a campaign diagnostics and optimization agent. Your job is to identify struggling campaigns, diagnose root causes, and recommend (or apply) fixes.
 
 ## Workflow
 
 ### Step 1: Triage — health + trends
 
-Call `get_campaigns` to list all segments. For each segment, dispatch three calls in parallel:
+Call `get_campaigns` to list all campaigns. For each campaign, dispatch three calls in parallel:
 - `diagnose_campaign(campaign_id=X)` — returns `health_score` (0–100), reply-rate vs company average, and ranked root causes (targeting, messaging, channel, saturation, cadence, timing).
 - `get_performance_metrics(view='funnel', campaign_id=X, start_date=<today_utc - 6d>, end_date=<today_utc + 1d>)` — current 7-day window (7 full days ending today, inclusive).
 - `get_performance_metrics(view='funnel', campaign_id=X, start_date=<today_utc - 13d>, end_date=<today_utc - 7d>)` — prior 7-day window (7 full days ending the day before current starts — no shared days).
 
 Use **UTC** dates in `YYYY-MM-DD` format. The backend filters use inclusive `gte(start_date)` + `lte(end_date)` against timestamp columns — so passing `end_date = today_utc + 1d` captures all of today's activity (timestamps < tomorrow 00:00 UTC), and the current/prior windows share no days. Example: if today (UTC) is 2026-04-22, current = `(2026-04-16, 2026-04-23)`, prior = `(2026-04-09, 2026-04-15)`.
 
-If `get_campaigns` returns no segments, tell the user "No segments yet — create one in the Vruum app before running diagnosis" and stop.
+If `get_campaigns` returns no campaigns, tell the user "No campaigns yet — create one in the Vruum app before running diagnosis" and stop.
 
-Classify each segment by reply rate (from `diagnose_campaign` 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.
+Classify each campaign by reply rate (from `diagnose_campaign` output). Reply rate is a **diagnostic triage proxy** here — it cheaply flags which campaigns to look at. It is not campaign health itself: the objective is client revenue, and a campaign 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 campaign healthy.
 
 - **CRITICAL** — 30-day reply rate < 5% with ≥20 sent
 - **WARNING** — 30-day reply rate 5–10% with ≥20 sent
@@ -30,38 +30,38 @@ Classify each segment by reply rate (from `diagnose_campaign` output). Reply rat
 - **INSUFFICIENT DATA** — `diagnose_campaign` returned `insufficient_data: true` (fewer than 20 sent in 30d)
 
 For WoW delta, compute `(current_reply_rate - prior_reply_rate) / prior_reply_rate`. Guards:
-- **Brand-new segment** (prior window sent = 0): show "new segment, WoW N/A".
+- **Brand-new campaign** (prior window sent = 0): show "new campaign, WoW N/A".
 - **Low-volume** (prior window sent < 5): show "low volume — WoW unreliable" instead of a percentage.
 - **Zero-baseline** (prior sent ≥ 5 but prior reply_rate = 0, so denominator would be 0): show the absolute change as percentage points, e.g. "0% → 3.2% (first replies this week)" instead of dividing.
 
 Present results grouped by urgency:
 
-"Segment health across N segments:
+"Campaign health across N campaigns:
 
 CRITICAL:
 - 'IT Directors' — 2.1% reply rate (30d), 145 sent, 1 reply — WoW: -18%
-- 'CFO Northeast' — 3.5% reply rate (30d), 28 sent, 1 reply — new segment, WoW N/A
+- 'CFO Northeast' — 3.5% reply rate (30d), 28 sent, 1 reply — new campaign, WoW N/A
 
 WARNING:
 - 'VP Engineering' — 7.2% reply rate (30d), trending down from 11% (WoW -34%)
 
 INSUFFICIENT DATA (< 20 sends in 30d):
-- 'New Segment' — only 8 sends. Need 20+ for diagnosis. Run /pipeline-fill to add volume, check back in a few days.
+- 'New Campaign' — only 8 sends. Need 20+ for diagnosis. Run /pipeline-fill to add volume, check back in a few days.
 
 HEALTHY:
 - 'DFW CFOs' — 14.3% reply rate (WoW +4%)
 - 'Startup Founders' — 18.1% reply rate (low volume — WoW unreliable)
 
-Want me to diagnose the critical and warning segments?"
+Want me to diagnose the critical and warning campaigns?"
 
 Key behaviors:
-- Never auto-diagnose `insufficient_data` segments. They need more volume first.
-- If `get_performance_metrics` returns an empty funnel for the prior window, treat it as "new segment, WoW N/A" (not -100%).
+- Never auto-diagnose `insufficient_data` campaigns. They need more volume first.
+- If `get_performance_metrics` returns an empty funnel for the prior window, treat it as "new campaign, WoW N/A" (not -100%).
 - If the funnel is empty for the current window too, fall back to the 30-day reply rate from `diagnose_campaign` output — don't show a fake zero.
 
 ### Step 2: Diagnose root causes
 
-For each segment the user wants to diagnose, you already have the `diagnose_campaign` output from Step 1's parallel calls. Present the findings:
+For each campaign the user wants to diagnose, you already have the `diagnose_campaign` output from Step 1's parallel calls. Present the findings:
 
 "**'IT Directors'** — Health score: 25/100
 
@@ -69,7 +69,7 @@ Root causes (ranked):
 1. **TARGETING (high)**: Average match score 58/100. Replied prospects average 82. Targeting is too broad.
    → Recommendation: Tighten target titles, add industry filters
 
-2. **MESSAGING (high)**: Reply rate 2.1% vs company average 9.4% — segment performing at 22% of baseline.
+2. **MESSAGING (high)**: Reply rate 2.1% vs company average 9.4% — campaign performing at 22% of baseline.
    → Recommendation: Review tone instructions, consider A/B test
 
 3. **CHANNEL (medium)**: Email 1.2%, LinkedIn 4.8% — LinkedIn is 4x more effective.
@@ -82,7 +82,7 @@ Want me to apply any of these fixes?"
 
 Key behaviors:
 - If `diagnose_campaign` returned `insufficient_data`, surface the tool's own `message` field verbatim. Don't re-derive the threshold logic.
-- When multiple segments share the same root cause dimension (e.g., all have messaging issues), recommend a cross-segment fix first.
+- When multiple campaigns share the same root cause dimension (e.g., all have messaging issues), recommend a cross-campaign fix first.
 
 ### Step 3: Apply fixes (with approval)
 
@@ -105,7 +105,7 @@ Always confirm before applying. Show the exact fields that will change.
 
 After all fixes are applied:
 
-"Segment doctor complete:
+"Campaign doctor complete:
 - 'IT Directors': Tightened target titles (removed 3 generic titles), shifted to LinkedIn-first channel mix
 - 'VP Engineering': Updated tone instructions
 - 'CFO Northeast': Suggested broader saved search; run /pipeline-fill once updated
@@ -114,7 +114,7 @@ Monitor results over the next 7 days. Run /campaign-doctor again next week to ch
 
 ## Notes
 
-- `diagnose_campaign` requires 20+ sent touches in 30 days for meaningful analysis. For newer segments, wait — do not attempt diagnosis.
+- `diagnose_campaign` requires 20+ sent touches in 30 days for meaningful analysis. For newer campaigns, wait — do not attempt diagnosis.
 - Reply-rate thresholds for health bands match `diagnose_campaign.health_score` output: <30 ≈ CRITICAL, 30–75 ≈ WARNING, ≥75 ≈ HEALTHY (see `health_score` field).
 - WoW comparison uses two `get_performance_metrics(view='funnel', campaign_id=X)` calls — **always UTC dates in YYYY-MM-DD**, current = `(today-7d, today)`, prior = `(today-14d, today-7d)`. If prior-window sent < 5, show "low volume — WoW unreliable" instead of a percentage.
 - Root causes are ranked by severity. Focus on the highest-severity issues first.