@vruum/skills 0.4.3 → 0.4.5

package/README.md

@@ -6,11 +6,29 @@ Pairs with the Vruum MCP server at [https://api.vruum.ai/mcp](https://api.vruum.
 
 ## Install
 
+### Claude Code / Cursor / VS Code Copilot / Cline
+
+Add the Vruum MCP server as a connector. Slash commands appear automatically — you don't need this npm package.
+
+```bash
+claude mcp add --transport http --scope user vruum https://api.vruum.ai/mcp
+```
+
+### 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 → "+"**.
+
+### Codex CLI / ChatGPT / other harnesses
+
 ```bash
 npx @vruum/skills install
 ```
 
-Detects Claude Code (`~/.claude/skills/`) and Codex CLI (`~/.codex/skills/`). For other harnesses:
+Detects Codex CLI (`~/.codex/skills/`). For other harnesses:
 
 ```bash
 npx @vruum/skills install --target /path/to/skills/dir
@@ -23,6 +41,7 @@ npx @vruum/skills install --target /path/to/skills/dir
 - `/engagement-triage` — Review and approve your pending LinkedIn engagement drafts and demand-gen content posts. Use when: triage engagements, review engagement queue, review warming comments, review nurture reactions, review marketing comments, review content drafts, check engagement queue.
 - `/enrich-prospect` — Deep prospect diarization — synthesize everything known about a person into a structured intelligence profile. Use when: enrich prospect, deep research, profile this person, who is this person, research prospect, diarize prospect, prospect briefing.
 - `/outreach-triage` — Review and approve your pending outreach drafts across LinkedIn and email. Use when: triage, review queue, morning review, check messages, approve outreach, what needs review.
+- `/pipeline-fill` — Fill your outreach pipeline by importing new Sales Navigator prospects. Pre-filters results against ICP before import to save research credits. Use when: fill pipeline, import prospects, daily imports, need more prospects.
 - `/vruum-skills-upgrade` — Upgrade @vruum/skills to the latest npm version and re-sync ~/.vruum/. Use when: upgrade vruum skills, update vruum, pull latest vruum skills, or when the preamble reports UPGRADE_AVAILABLE.
 <!-- generated:skills-end -->
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vruum/skills",
-  "version": "0.4.3",
-  "description": "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.",
+  "version": "0.4.5",
+  "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": {
     "type": "git",
@@ -36,5 +36,5 @@
     "outreach",
     "gtm"
   ],
-  "contentHash": "5cd9f12d62a025c0c17b3d68702df7e9f9a823e3217785ea070d6f5f6f6afa78"
+  "contentHash": "b0e043a4560fc5d2eda1f7238a08f58d8d1865c97b28442574d6c509eb74e53a"
 }

package/skills/pipeline-fill/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: pipeline-fill
+description: >-
+  Fill your outreach pipeline by importing new Sales Navigator prospects.
+  Pre-filters results against ICP before import to save research credits. Use
+  when: fill pipeline, import prospects, daily imports, need more prospects.
+---
+
+## Auto-update check
+
+Before starting, run `~/.vruum/bin/vruum-skills-update-check` (path relative to this repo). Interpret output:
+- `UPGRADE_AVAILABLE <old> <new>` → mention the available upgrade in one line and offer `/vruum-upgrade`. Then continue.
+- `JUST_UPGRADED <old> <new>` → acknowledge in one line, then continue.
+- Empty → proceed silently.
+
+Never block skill execution on this check.
+
+# Pipeline Fill
+
+You are a pipeline filling orchestrator. Your job is to efficiently import the right number of prospects from configured Sales Nav saved searches, with smart pre-filtering to avoid wasting research credits on poor fits.
+
+## Why this skill exists
+
+Filling your pipeline manually (preview search → evaluate each profile → dismiss mismatches → import fits → assign to segment → start outreach) takes an hour or more per day. This skill automates it with smart pre-filtering so research credits go only to prospects that actually fit your ICP.
+
+## Subagent architecture
+
+This skill uses the custom agent `vruum-pipeline-filter` defined at `~/.claude/agents/vruum-pipeline-filter.md`. That agent has:
+- Full Vruum MCP access via `mcpServers` (can call preview_sales_nav_search, mcp_dismiss_sales_nav_profiles, import_from_sales_nav)
+- Complete filtering instructions baked into its system prompt
+
+### MCP access requirements
+
+Subagents can only access Vruum MCP if `vruum-local` is configured as a user-scoped HTTP MCP server in `~/.claude.json`. Cloud MCP servers (`claude.ai Vruum`) are NOT inherited by subagents.
+
+To set up: `claude mcp add --transport http --scope user vruum-local https://api.vruum.ai/mcp` (one-time, requires OAuth).
+
+### Dispatch methods (in order of preference)
+
+1. **Agent tool** (primary): Spawn subagents via the Agent tool. Subagents inherit local MCP servers from `~/.claude.json` and can call Vruum tools directly. Use `run_in_background=true` for parallelism.
+
+2. **CLI dispatch**: `claude --agent vruum-pipeline-filter --allowedTools "mcp__vruum-local__*,mcp__claude_ai_Vruum__*" -p "<prompt>" --output-format text --max-turns 20`. Use if Agent tool subagents can't reach MCP.
+
+3. **Inline**: For well-targeted searches where pre-filtering adds little value, skip the subagent and import directly.
+
+## Pre-fill checks
+
+Before importing for any segment, check T1 send capacity:
+1. How many people are already in "new" stage (queued but not yet contacted)?
+2. What is the daily connection limit for the segment?
+3. If the backlog already exceeds 3+ days of sends, skip importing — they have enough inventory.
+
+This prevents piling up prospects that won't get touched for days.
+
+## Workflow
+
+### Step 1: Check what needs filling
+
+Call `manage_sales_nav_searches` with `action="list"` to see configured Sales Nav saved searches + segment mappings, and `get_outreach_stats` to see queue depth per segment. Present a numbered table:
+
+```
+Pipeline status:
+
+  1. DFW CFOs        — 12/30 (18 needed, search healthy)
+  2. Austin VPs      — 28/30 (2 needed)
+  3. Houston CTOs    — 0/20  (20 needed, search drying up ⚠️)
+  4. NYC Partners    — 0/40  (40 needed)
+
+Which segments to fill? (all / 1,3,4 / skip 2)
+```
+
+**Table rules:**
+- One row per segment, numbered sequentially
+- Show current/target counts and how many are needed
+- Flag searches that are drying up (⚠️) or accounts near capacity
+- Mark segments already at target with ✓ and don't number them
+
+**Wait for the user's response.** They can reply with:
+- "all" — fill every segment that needs it
+- Segment numbers: "1, 3, 4" or "1 and 4"
+- Exclusions: "skip 2"
+- Natural language: "just the CFO ones", "skip anything under 10 needed"
+
+Parse their response and only fill the selected segments.
+
+### Step 2: Fill selected segments
+
+For each selected segment, for each active pipeline source mapping:
+
+#### 2a. Preview and filter via subagent
+
+Dispatch a subagent via the Agent tool to handle the full preview → filter → import flow. The subagent prompt should include:
+- Search name or ID
+- Segment ID or name
+- Number of profiles to import
+- Instructions to call `preview_sales_nav_search`, evaluate profiles against ICP, dismiss poor fits, and import the good ones with `auto_enroll=true`
+
+**Parallelism:** Each search/segment mapping is independent. Spawn multiple subagents in parallel using `run_in_background=true`.
+
+#### 2b. Fallback for simple cases
+
+If the search is well-targeted (title + location filters match the segment ICP closely), skip the subagent and import directly:
+
+```
+import_from_sales_nav(search="DFW CFOs", count=50, segment="dfw-cfos", auto_enroll=true)
+```
+
+Use the subagent only when the search is broad enough that pre-filtering saves meaningful cost.
+
+### Step 3: Report results
+
+After the fill completes, present a summary:
+
+"Pipeline fill complete:
+- DFW CFOs: Previewed 45 profiles, approved 32, dismissed 13. Imported 18 new.
+- Austin VPs: 2 more imported.
+- Houston CTOs: Search drying up — returned only 7 profiles. Consider broadening the search or creating a new one.
+Total: 27 imported, 13 dismissed, ~$3.40 saved by pre-filtering."
+
+## Shared search deduplication
+
+Multiple segments may use the same Sales Nav saved search (e.g. "Real Estate Team Owners" and "Real Estate Team Owners (No Warming)" both pull from the same search). **Never import from the same saved search in parallel across different segments.** Run them sequentially so the first import's profiles are already in the system (and deduped) before the second import starts. Otherwise the same person can get imported into two segments concurrently, which corrupts warming state.
+
+Before dispatching subagents, group segment fills by their saved search ID. Within each group, dispatch sequentially. Different saved searches can still run in parallel.
+
+## Notes
+
+- Each mapping is independent. If one fails (expired LinkedIn session, rate limit), others still run.
+- The 5-minute cooldown on automated pipeline fills prevents duplicate imports if the skill runs twice in quick succession.
+- Pre-filtering saves ~$0.10-0.20 per dismissed profile (LinkedIn research + company research + match analysis costs).
+- If a search returns fewer profiles than needed, flag it as "drying up" so the user knows to create a new search or broaden targeting.
+- If subagent MCP connections fail, fall back to inline: preview in the main session, filter manually, import directly. This typically means `vruum-local` isn't in `~/.claude.json`.