@maximusgtm/lead-management 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "@maximusgtm/lead-management",
+  "version": "1.0.0",
+  "description": "Lead management skill for Maximus GTM - search, filter, enrich, and analyze leads",
+  "author": "Maximus GTM",
+  "homepage": "https://maximusgtm.com",
+  "mcp": {
+    "servers": {
+      "maximus": {
+        "type": "url",
+        "url": "${MAXIMUS_MCP_URL}",
+        "headers": {
+          "Authorization": "Bearer ${MAXIMUS_API_KEY}"
+        }
+      }
+    }
+  },
+  "skills": [
+    "SKILL.md",
+    "lead-sourcing/SKILL.md"
+  ]
+}

package/README.md

@@ -0,0 +1,54 @@
+# @maximusgtm/lead-management
+
+Claude Code skill for lead management on the Maximus GTM platform. Search, filter, enrich, and analyze leads using natural language.
+
+## Installation
+
+```bash
+/plugin install @maximusgtm/lead-management
+```
+
+## Configuration
+
+Set the following environment variables before using the skill:
+
+| Variable | Description |
+|----------|-------------|
+| `MAXIMUS_MCP_URL` | URL of your Maximus MCP server (e.g., `https://mcp.maximusgtm.com/mcp`) |
+| `MAXIMUS_API_KEY` | Your MCP agent API key |
+
+### Getting an API Key
+
+1. Log in to the Maximus GTM portal
+2. Navigate to **Settings > MCP Agents**
+3. Create a new agent with the `leads` and `accounts` scopes
+4. Copy the generated API key
+
+## Available Tools
+
+### Account Context
+- `maximus_list_accounts` - List available accounts
+- `maximus_get_account` - Get account details
+
+### Lead Data
+- `maximus_list_leads` - Search and filter leads with pagination
+- `maximus_get_lead` - Get complete lead details
+- `maximus_get_lead_stats` - Aggregate lead statistics
+
+### Lead Search (External)
+- `maximus_search_leads` - Search for new leads by criteria (Apollo, Builtin DB)
+- `maximus_search_leads_from_icp` - Search using ICP-derived criteria
+- `maximus_enrich_lead` - Enrich a person by email address
+- `maximus_list_lead_search_providers` - List available search providers
+
+## Usage Examples
+
+```
+> Show me all qualified leads from Apollo
+
+> Search for VP-level SaaS leaders in the US
+
+> Enrich sarah@techcorp.com
+
+> What's my lead pipeline health?
+```

package/SKILL.md

@@ -0,0 +1,93 @@
+# Lead Management Skill
+
+Specialized skill for working with leads in the Maximus GTM platform. Use this for lead-focused operations including search, filtering, quality analysis, and bulk operations.
+
+## Prerequisites
+
+- Use `maximus_list_accounts` to find the `accountId` before calling lead tools
+- Use `maximus_get_account` for account context (plan limits, integrations status)
+
+## When to Use
+
+Use this skill when the user wants to:
+- Search or filter leads
+- Understand lead quality scores
+- Analyze lead sources
+- Get lead statistics and trends
+- Work with specific leads
+
+## Available MCP Tools
+
+### Lead Data
+- `maximus_list_leads` - Search and filter leads with pagination
+- `maximus_get_lead` - Get complete lead details
+- `maximus_get_lead_stats` - Aggregate statistics
+
+### Lead Search (External)
+- `maximus_search_leads` - Search for new leads by criteria (Apollo, Builtin DB)
+- `maximus_search_leads_from_icp` - Search using ICP-derived criteria
+- `maximus_enrich_lead` - Enrich a person by email address
+- `maximus_list_lead_search_providers` - List available search providers
+
+## Lead Filtering
+
+The `maximus_list_leads` tool supports these filters:
+- `search` - Search by name, email, company
+- `status` - Filter by lead status (new, contacted, qualified, converted)
+- `source` - Filter by source (apollo, linkedin, manual, etc.)
+- `sortBy` / `sortOrder` - Sort results
+
+## Lead Quality Interpretation
+
+When presenting lead data, interpret quality indicators:
+
+### High Quality Lead Signals
+- Complete contact information (email, phone, LinkedIn)
+- Job title matches ICP buyer persona
+- Company fits target firmographics
+- Recent engagement activity
+
+### Data Quality Issues to Flag
+- Missing email or phone
+- Generic email domains (gmail, yahoo)
+- Incomplete company information
+- Stale leads (no recent updates)
+
+## Common Queries
+
+**"Show me qualified leads"**
+```
+Use maximus_list_leads with status="qualified"
+```
+
+**"Find leads from Apollo in the last week"**
+```
+Use maximus_list_leads with source="apollo", sortBy="createdAt"
+```
+
+**"What's my lead pipeline health?"**
+```
+Use maximus_get_lead_stats for aggregate view
+```
+
+## Response Format
+
+When presenting leads:
+1. Show total count and pagination info
+2. Present key fields: Name, Company, Title, Email
+3. Include status and source
+4. Highlight quality indicators
+5. Offer drill-down options
+
+Example:
+```
+Found 47 qualified leads from Apollo:
+
+1. **Sarah Chen** - VP Engineering at TechCorp
+   sarah@techcorp.com | Added 2 days ago | Score: 85
+
+2. **Mike Johnson** - CTO at StartupXYZ
+   mike@startupxyz.io | Added 5 days ago | Score: 78
+
+...showing 1-10 of 47. Say "show more" to continue.
+```

package/lead-sourcing/SKILL.md

@@ -0,0 +1,139 @@
+# Lead Sourcing Skill
+
+Specialized skill for finding and importing leads from multiple sources. Supports Apollo API search, database search, and ICP-driven lead discovery.
+
+## When to Use
+
+Use this skill when the user wants to:
+- Find leads matching specific criteria
+- Search for leads from an ICP profile
+- Enrich existing leads with additional data
+- Understand which lead search providers are available
+- Build a lead list from search results
+- Compare lead sources
+
+## Available MCP Tools
+
+### Search
+- `maximus_search_leads` - Search by criteria (job titles, industries, company size, location, etc.)
+- `maximus_search_leads_from_icp` - Search using an ICP's criteria (auto-converts ICP fields)
+
+### Enrichment
+- `maximus_enrich_lead` - Enrich a person by email (title, company, seniority, LinkedIn)
+
+### Providers
+- `maximus_list_lead_search_providers` - List available providers for the account
+
+## Provider Selection Guide
+
+| Provider | Best For | Requires |
+|----------|----------|----------|
+| **APOLLO** | External lead discovery, fresh data | Apollo API key (in Integrations) |
+| **BUILTIN** | Searching existing leads in database | Nothing (always available) |
+
+**Auto-detection:** If no provider is specified, the system checks for Apollo first, then falls back to Builtin.
+
+## Search Criteria Reference
+
+| Field | Type | Description | Example |
+|-------|------|-------------|---------|
+| `jobTitles` | string[] | Job titles to match | ["VP Engineering", "CTO", "Head of Product"] |
+| `seniorities` | string[] | Seniority levels | ["c_suite", "vp", "director", "manager"] |
+| `industries` | string[] | Target industries | ["SaaS", "FinTech", "E-commerce"] |
+| `employeeRange` | {min, max} | Company size | {min: 50, max: 500} |
+| `locations.countries` | string[] | Countries | ["United States", "Canada"] |
+| `locations.cities` | string[] | Cities | ["San Francisco", "New York"] |
+| `technologies` | string[] | Tech stack | ["React", "AWS", "Salesforce"] |
+| `keywords` | string[] | General keywords | ["AI", "machine learning"] |
+| `companyDomains` | string[] | Specific domains | ["stripe.com", "shopify.com"] |
+| `excludeTitles` | string[] | Titles to exclude | ["Intern", "Assistant"] |
+| `limit` | number | Results per page | 25 |
+| `page` | number | Page number | 1 |
+
+## ICP-to-Search Mapping
+
+When using `maximus_search_leads_from_icp`, ICP fields map to search criteria:
+
+| ICP Field | Search Criteria |
+|-----------|----------------|
+| `targetCompany.verticals` | `industries` |
+| `targetCompany.employeeRange` | `employeeRange` |
+| `targetCompany.technologies` | `technologies` |
+| `buyerPersonas[].roles` | `jobTitles` |
+| `buyerPersonas[].seniority` | `seniorities` |
+| `geography.countries` | `locations.countries` |
+| `geography.cities` | `locations.cities` |
+| `exclusions.titles` | `excludeTitles` |
+| `exclusions.industries` | `excludeIndustries` |
+
+## Workflows
+
+### "Find leads matching my ICP"
+
+```
+1. maximus_list_lead_search_providers (check what's available)
+2. maximus_search_leads_from_icp (auto-converts ICP and searches)
+3. Review results with user
+4. If satisfactory, proceed to campaign assignment
+```
+
+### "Search for VP-level SaaS leaders in the US"
+
+```
+1. maximus_search_leads with criteria:
+   - jobTitles: ["VP", "Vice President"]
+   - industries: ["SaaS", "Software"]
+   - locations: { countries: ["United States"] }
+   - seniorities: ["vp"]
+2. Present results with name, title, company, email
+3. Offer to refine or expand search
+```
+
+### "Enrich this email address"
+
+```
+1. maximus_enrich_lead with the email
+2. Present enriched data (title, company, seniority, LinkedIn)
+3. Offer to add to a lead list or campaign
+```
+
+### "What data sources do I have?"
+
+```
+1. maximus_list_lead_search_providers
+2. Present available vs. all providers
+3. If Apollo not available, suggest adding API key
+```
+
+## Response Format
+
+When presenting search results:
+```
+Found 234 leads matching your criteria via Apollo
+
+Criteria used:
+- Titles: VP Engineering, CTO, Head of Engineering
+- Industries: SaaS, FinTech
+- Company size: 50-500 employees
+- Location: United States
+
+Top results:
+1. Sarah Chen — VP Engineering at CloudTech (SaaS, 200 employees)
+   sarah@cloudtech.io | San Francisco, CA
+
+2. James Park — CTO at PayFlow (FinTech, 150 employees)
+   james@payflow.com | New York, NY
+
+3. Maria Garcia — Head of Engineering at DataSync (SaaS, 320 employees)
+   maria@datasync.io | Austin, TX
+
+Showing 1-10 of 234. Say "show more" or "refine search" to continue.
+```
+
+## Quality Assessment
+
+When reviewing search results, flag:
+- **Missing emails** — leads without email addresses cannot be contacted
+- **Generic domains** — gmail.com, yahoo.com may indicate personal accounts
+- **Title mismatches** — results that don't match the intended seniority
+- **Company size outliers** — companies outside the target range

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@maximusgtm/lead-management",
+  "version": "1.0.0",
+  "description": "Lead management skill for Maximus GTM platform",
+  "author": "Maximus GTM",
+  "license": "UNLICENSED",
+  "files": [
+    ".claude-plugin/",
+    "SKILL.md",
+    "lead-sourcing/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}