feat(plugin): add Cursor agent + commands (align with plugin model)

jesseoue · jesseoue · commit 4a787f959201 · 2026-04-04T00:56:36.000-04:00
- agents/leadmagic-enrichment.md; commands check-credits, research-company, validate-email
- plugin.json: agents, commands paths; keywords; v0.1.6
- validate frontmatter for agents/commands; README vs Encore + Cursor docs
- SUBMISSION + PR template + CI paths + CHANGELOG

Made-with: Cursor
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
@@ -1,8 +1,8 @@
 {
 	"name": "leadmagic",
 	"displayName": "LeadMagic",
-	"version": "0.1.5",
-	"description": "Official LeadMagic plugin for Cursor with hosted MCP (OAuth by default): emails, mobile, LinkedIn-to-email, job changes, company research, competitors, technographics, and credits.",
+	"version": "0.1.6",
+	"description": "Official LeadMagic plugin for Cursor with hosted MCP (OAuth by default), skills, rules, agent, and commands: emails, mobile, LinkedIn-to-email, job changes, company research, competitors, technographics, and credits.",
 	"author": {
 		"name": "LeadMagic",
 		"email": "plugins@leadmagic.io"
@@ -21,11 +21,15 @@
 		"email-finder",
 		"company-intelligence",
 		"prospecting",
-		"gtm"
+		"gtm",
+		"agent",
+		"commands"
 	],
 	"category": "developer-tools",
 	"tags": ["sales", "prospecting", "enrichment", "mcp", "api"],
 	"rules": "./rules/",
 	"skills": "./skills/",
+	"agents": "./agents/",
+	"commands": "./commands/",
 	"mcpServers": "./mcp.json"
 }
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -22,6 +22,7 @@
 
 - [ ] `mcp.json` still points to `https://mcp.leadmagic.io/mcp`
 - [ ] Default `mcp.json` stays OAuth-only (no headers); API-key fallback documented in README if needed
+- [ ] New or edited `agents/*.md` and `commands/*.md` include YAML frontmatter (`name`, `description`)
 - [ ] Repo copy does not imply MCP support for tools outside the current MCP surface
 - [ ] README and submission copy stay consistent
 
diff --git a/.github/workflows/validate-plugin.yml b/.github/workflows/validate-plugin.yml
@@ -15,6 +15,8 @@ on:
       - "README.md"
       - "SUBMISSION.md"
       - "rules/**"
+      - "agents/**"
+      - "commands/**"
       - "schemas/**"
       - "scripts/**"
       - "CHANGELOG.md"
@@ -44,4 +46,4 @@ jobs:
 
       - name: Check README references
         run: |
-          node -e "const fs=require('node:fs');const text=fs.readFileSync('README.md','utf8');for(const value of ['https://mcp.leadmagic.io/mcp','https://github.com/LeadMagic/leadmagic-openapi','leadmagic://docs','LeadMagic MCP Tools','OAuth']){if(!text.includes(value)){throw new Error('README.md is missing required reference: '+value)}}"
+          node -e "const fs=require('node:fs');const text=fs.readFileSync('README.md','utf8');for(const value of ['https://mcp.leadmagic.io/mcp','https://github.com/LeadMagic/leadmagic-openapi','https://cursor.com/docs/plugins','leadmagic://docs','LeadMagic MCP Tools','OAuth']){if(!text.includes(value)){throw new Error('README.md is missing required reference: '+value)}}"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 All notable changes to the LeadMagic Cursor plugin package are documented here.
 
+## 0.1.6
+
+- **Cursor plugin model:** Add `agents/leadmagic-enrichment.md` and `commands/` (`check-credits`, `research-company`, `validate-email`); wire `agents` and `commands` in `plugin.json` to match patterns used by plugins such as [encoredev/cursor-plugin](https://github.com/encoredev/cursor-plugin).
+- **Validation:** Assert agent/command markdown frontmatter; README links to [Cursor Plugins docs](https://cursor.com/docs/plugins).
+
 ## 0.1.5
 
 - **Docs:** README clarifies MCP (Cursor) vs REST (OpenAPI), links [leadmagic-openapi](https://github.com/LeadMagic/leadmagic-openapi) and product docs; validator and CI require the OpenAPI repo URL in README.
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@ This repository packages LeadMagic's hosted MCP integration in a Cursor-native f
 | Cursor agents, chat, or IDE automation over LeadMagic | This plugin + hosted MCP at `https://mcp.leadmagic.io/mcp` (default **OAuth** in Cursor) |
 | Your own services, scripts, or non-MCP clients calling `https://api.leadmagic.io` | [LeadMagic OpenAPI](https://github.com/LeadMagic/leadmagic-openapi) (YAML/JSON snapshot, `llms.txt`, and `test-api` smoke tests) + [product API docs](https://leadmagic.io/docs) |
 
-The OpenAPI repository is the best place for **schema-level** detail and **direct HTTP** examples. This plugin repo is the source for **Cursor packaging** (skills, rules, `mcp.json`, validation). Keep terminology aligned: MCP tools wrap a **subset** of the broader REST surface (for example jobs and ads APIs are not exposed as MCP tools today).
+The OpenAPI repository is the best place for **schema-level** detail and **direct HTTP** examples. This plugin repo is the source for **Cursor packaging** (skills, rules, agents, commands, `mcp.json`, validation). Keep terminology aligned: MCP tools wrap a **subset** of the broader REST surface (for example jobs and ads APIs are not exposed as MCP tools today).
 
 The package includes:
 
@@ -30,6 +30,12 @@ The package includes:
   - prospect list QA
   - signal research
 - One default rule that nudges Cursor toward efficient, low-duplication LeadMagic usage
+- One **agent** (`leadmagic-enrichment`): a dedicated enrichment/research persona wired to MCP best practices
+- **Commands** (playbooks): check credits, research a company, validate an email—usable from the Cursor commands palette like other marketplace plugins
+
+### How this compares to other Cursor plugins
+
+Well-structured plugins (for example [Encore’s Cursor plugin](https://github.com/encoredev/cursor-plugin), which bundles rules, skills, MCP, an agent, and commands) follow the same **Cursor plugin model** described in the official docs: [Plugins](https://cursor.com/docs/plugins) and the [plugin-template](https://github.com/cursor/plugin-template) monorepo. LeadMagic matches that shape where it makes sense for **hosted SaaS enrichment**: we ship **HTTP/streamable MCP** to `https://mcp.leadmagic.io/mcp` (OAuth by default) instead of launching a **local stdio** MCP process—appropriate because LeadMagic runs as a hosted API. Optional **hooks** or local scripts are not included until there is a clear, supportable automation story for all users.
 
 ## Why Use It
 
@@ -198,6 +204,8 @@ Use the shared docs resource `leadmagic://docs` or review:
 .cursor-plugin/plugin.json
 .github/pull_request_template.md
 .github/workflows/validate-plugin.yml
+agents/*.md
+commands/*.md
 assets/logo.svg
 mcp.json
 package-lock.json
diff --git a/SUBMISSION.md b/SUBMISSION.md
@@ -20,7 +20,7 @@ plugins@leadmagic.io
 https://raw.githubusercontent.com/LeadMagic/leadmagic-cursor-plugin/main/assets/logo.svg
 
 **Description**
-Official LeadMagic plugin for Cursor. Gives agents direct access to LeadMagic's hosted MCP surface for work email validation and discovery, mobile lookup, LinkedIn profile to work email, job-change detection, account research, competitor and technographics lists, people-by-role search, and credit balance—authenticated by default with OAuth in Cursor, with an optional API-key path for advanced setups.
+Official LeadMagic plugin for Cursor. Gives agents direct access to LeadMagic's hosted MCP surface for work email validation and discovery, mobile lookup, LinkedIn profile to work email, job-change detection, account research, competitor and technographics lists, people-by-role search, and credit balance—authenticated by default with OAuth in Cursor, with an optional API-key path for advanced setups. Includes skills, rules, a dedicated enrichment agent, and command playbooks aligned with Cursor's plugin model.
 
 **GitHub repository**
 https://github.com/LeadMagic/leadmagic-cursor-plugin
@@ -42,7 +42,7 @@ Before submitting:
 
 ## Suggested reviewer note
 
-LeadMagic is an API-first B2B enrichment platform for AI agents and GTM engineers. This plugin packages our hosted MCP integration (10 tools, `leadmagic://docs`, two prompts) into a Cursor-native repo with focused skills, safe default guidance, and OAuth-first MCP auth (optional `LEADMAGIC_API_KEY` header for environments that need it). Tool calls are processed per LeadMagic privacy and terms at leadmagic.io.
+LeadMagic is an API-first B2B enrichment platform for AI agents and GTM engineers. This plugin packages our hosted MCP integration (10 tools, `leadmagic://docs`, two prompts) into a Cursor-native repo with focused skills, a dedicated enrichment agent, command playbooks, safe default guidance, and OAuth-first MCP auth (optional `LEADMAGIC_API_KEY` header for environments that need it). Tool calls are processed per LeadMagic privacy and terms at leadmagic.io.
 
 ## Short marketplace blurb alternatives
 
diff --git a/agents/leadmagic-enrichment.md b/agents/leadmagic-enrichment.md
@@ -0,0 +1,29 @@
+---
+name: leadmagic-enrichment
+description: GTM enrichment assistant for Cursor. Uses the hosted LeadMagic MCP server for credit-aware email validation, discovery, mobile, job-change signals, account research, competitors, technographics, and role-based people search.
+---
+
+# LeadMagic enrichment assistant
+
+You help users run **credit-aware B2B enrichment and research** inside Cursor using the **LeadMagic MCP** tools (not generic web scraping).
+
+## MCP access
+
+Assume the LeadMagic MCP server is available when this plugin is installed and the user has completed **OAuth** (or API-key auth per the plugin README). Prefer **MCP tools** over guessing APIs or inventing parameters.
+
+Before ambiguous work, skim **`leadmagic://docs`** for parameter names and constraints.
+
+## How you work
+
+1. **Credits:** For bulk or expensive flows, start with `check_credit_balance` when the user cares about spend.
+2. **Emails:** If the user already has a work email, use `validate_work_email` before `find_work_email`. Use `linkedin_profile_to_work_email` when the best input is a B2B profile URL.
+3. **Account context:** Use `research_account` once per company and reuse the summary instead of repeating similar calls.
+4. **Depth:** Use `list_company_competitors`, `get_company_technographics`, or `find_people_by_role` only when the user explicitly needs competitors, tech stack, or role-based lists.
+5. **Signals:** Use `detect_job_change` when the user asks about recent role changes.
+6. **Output:** State which tools ran, key results, nulls or not-found cases, and a sensible next step.
+
+## What you avoid
+
+- Repeating the same enrichment for identical inputs unless the user asks for a refresh.
+- Claiming deliverability or data the tool output does not include.
+- Treating the REST API or OpenAPI repo as executable from here unless the user is writing integration code—default to **MCP tools** for in-editor tasks.
diff --git a/commands/check-credits.md b/commands/check-credits.md
@@ -0,0 +1,10 @@
+---
+name: check-credits
+description: Verify LeadMagic MCP is connected and show remaining credits using the hosted MCP tool.
+---
+
+# Check LeadMagic credits
+
+1. Confirm the LeadMagic MCP server is enabled in Cursor and you are signed in (OAuth) or using API-key mode per the plugin README.
+2. Ask the agent to run the MCP tool `check_credit_balance` and report the balance and any message returned.
+3. If the tool errors, check MCP settings, `https://mcp.leadmagic.io/health`, and the troubleshooting section in the plugin README.
diff --git a/commands/research-company.md b/commands/research-company.md
@@ -0,0 +1,11 @@
+---
+name: research-company
+description: Run a single account research pass on a company (name or domain) and summarize GTM-relevant signals via LeadMagic MCP.
+---
+
+# Research a company
+
+1. Collect **company domain** or **company name** from the user (prefer domain when available).
+2. Use the MCP tool `research_account` once with the best available identifiers.
+3. Summarize industry, size signals, funding snapshot if present, and obvious angles for outreach—only from tool output.
+4. If the user wants more depth, add **only** what they ask for: `list_company_competitors`, `get_company_technographics`, or `find_people_by_role` (with role and company context).
diff --git a/commands/validate-email.md b/commands/validate-email.md
@@ -0,0 +1,11 @@
+---
+name: validate-email
+description: Validate a work email with LeadMagic MCP before sending or storing it as verified.
+---
+
+# Validate a work email
+
+1. Obtain the **work email** the user wants checked.
+2. Run `validate_work_email` via MCP with that email.
+3. Report the tool’s stated result and any fields returned (do not infer beyond the response).
+4. If validation is inconclusive or the user still needs an address, consider `find_work_email` only when they provide person + company context.
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
 	"name": "leadmagic-cursor-plugin",
 	"private": true,
-	"version": "0.1.5",
+	"version": "0.1.6",
 	"description": "Submission package for the LeadMagic Cursor plugin",
 	"license": "MIT",
 	"scripts": {
diff --git a/scripts/validate-plugin.mjs b/scripts/validate-plugin.mjs
@@ -89,6 +89,14 @@ try {
 		plugin.rules === "./rules/",
 		"Plugin must expose the rules directory with an explicit relative path",
 	);
+	assert(
+		plugin.agents === "./agents/",
+		"Plugin must expose the agents directory with an explicit relative path",
+	);
+	assert(
+		plugin.commands === "./commands/",
+		"Plugin must expose the commands directory with an explicit relative path",
+	);
 	assert(
 		exists("schemas/plugin.schema.json"),
 		"Missing vendored Cursor plugin schema at schemas/plugin.schema.json",
@@ -163,12 +171,38 @@ try {
 		);
 	}
 
+	function assertMarkdownBundle(dirName, label) {
+		const dir = path.join(root, dirName);
+		assert(fs.existsSync(dir), `Missing ${dirName} directory`);
+		const mdFiles = fs
+			.readdirSync(dir)
+			.filter((n) => n.endsWith(".md"))
+			.map((n) => path.join(dir, n));
+		assert(mdFiles.length > 0, `${dirName} must include at least one .md file`);
+		for (const file of mdFiles) {
+			const fm = frontmatter(fs.readFileSync(file, "utf8"));
+			assert(fm, `Missing frontmatter in ${path.relative(root, file)}`);
+			assert(
+				/\bname:\s*.+/m.test(fm),
+				`Missing ${label} name in ${path.relative(root, file)}`,
+			);
+			assert(
+				/\bdescription:\s*.+/m.test(fm),
+				`Missing ${label} description in ${path.relative(root, file)}`,
+			);
+		}
+	}
+
+	assertMarkdownBundle("agents", "agent");
+	assertMarkdownBundle("commands", "command");
+
 	const readmePath = path.join(root, "README.md");
 	assert(fs.existsSync(readmePath), "Missing README.md");
 	const readme = fs.readFileSync(readmePath, "utf8");
 	for (const expectedText of [
 		"https://mcp.leadmagic.io/mcp",
 		"https://github.com/LeadMagic/leadmagic-openapi",
+		"https://cursor.com/docs/plugins",
 		"leadmagic://docs",
 		"LeadMagic MCP Tools",
 		"OAuth",
