Add focused Context.dev workflow skills

Author: aadithyanr

.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "context-dev",
   "displayName": "Context.dev",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Search, scrape, crawl, extract, parse, monitor, and process the live web with Context.dev.",
   "author": {
     "name": "Context.dev",

README.md

@@ -35,10 +35,26 @@ Cursor automatically selects the appropriate Context.dev tool. Tool calls requir
 | Component | What it provides |
 | --- | --- |
 | MCP server | The production Context.dev MCP with 34 direct, typed tools and OAuth |
-| Skills | Context.dev API guidance, Cursor connection help, and Logo Link integration |
+| Skills | Focused MCP workflows, direct API guidance, Cursor connection help, and Logo Link integration |
 | Commands | `/brand-colors`, `/scrape-url`, `/search-web`, and `/extract-web-data` |
 | Rules | Routes live-web tasks to the right Context.dev tool and keeps credentials out of client code |
 
+### Skill catalog
+
+| Skill | When Cursor uses it |
+| --- | --- |
+| `context-search` | Live web research and source discovery |
+| `context-scrape` | Markdown, HTML, images, or screenshots from one known URL |
+| `context-crawl` | Sitemap discovery and focused multi-page crawling |
+| `context-extract` | Schema-shaped JSON from websites |
+| `context-parse` | PDFs, Office files, images, and other local document bytes |
+| `context-brand` | Brand profiles, design systems, fonts, and industry codes |
+| `context-monitor` | Recurring website-change detection and history |
+| `context-batches` | Large asynchronous scrape and crawl jobs |
+| `context-dev` | Building directly with the Context.dev REST API or SDKs |
+| `connect-context-dev` | OAuth setup and MCP troubleshooting |
+| `logolink` | Safe dynamic company logos in frontend applications |
+
 ### MCP tool catalog
 
 | Group | Tools |
@@ -56,7 +72,7 @@ For a known page, use `web-scrape-markdown`. Use `web-search` when the URL is un
 
 OAuth connects Cursor to the MCP server. If you are writing application code that calls the Context.dev REST API or SDK directly, create an API key in the [Context.dev dashboard](https://context.dev) and keep it in a server-side `CONTEXT_DEV_API_KEY` environment variable. Never put a private API key in browser code or commit it to source control.
 
-The bundled `context-dev` skill is synchronized from [docs.context.dev/skill.md](https://docs.context.dev/skill.md), while the plugin's MCP instructions deliberately describe only the public tools exposed by the production MCP server.
+The bundled `context-dev` API reference is synchronized from [docs.context.dev/skill.md](https://docs.context.dev/skill.md). Its Cursor activation description is narrowed to direct API and SDK development, while the focused OAuth skills route interactive work through the public production MCP tools.
 
 ## Local development
 
@@ -75,7 +91,7 @@ mkdir -p ~/.cursor/plugins/local
 rsync -a --delete --exclude '.git/' ./ ~/.cursor/plugins/local/context-dev/
 ```
 
-Then run **Developer: Reload Window** in Cursor and verify that the `context` MCP server, four commands, three skills, and two rules appear. A copied directory is used because current Cursor builds reject local-plugin symlinks whose targets are outside `~/.cursor/plugins/local`.
+Then run **Developer: Reload Window** in Cursor and verify that the `context` MCP server, four commands, eleven skills, and two rules appear. A copied directory is used because current Cursor builds reject local-plugin symlinks whose targets are outside `~/.cursor/plugins/local`.
 
 ## Links
 

scripts/sync-skill.mjs

@@ -8,6 +8,14 @@ const repoRoot = process.cwd();
 const skillUrl = "https://docs.context.dev/skill.md";
 const skillPath = path.join(repoRoot, "skills", "context-dev", "SKILL.md");
 const checkOnly = process.argv.includes("--check");
+const cursorDescription =
+  "Build application code directly against the Context.dev REST API or SDKs with server-side API-key authentication. Use when the user asks to integrate Context.dev into a codebase, choose an SDK method or REST endpoint, debug an API request, or implement a backend Context.dev workflow. For ordinary live-web work inside Cursor, use the focused Context.dev MCP skills instead.";
+
+function adaptForCursor(body) {
+  return body
+    .replace(/^description:.*$/m, `description: ${cursorDescription}`)
+    .replace(/^compatibility:.*\n/m, "");
+}
 
 async function fetchSkill() {
   let lastError;
@@ -36,14 +44,14 @@ async function main() {
     throw new Error(`${skillUrl} did not return a valid context-dev skill`);
   }
 
-  const expected = `${body}\n`;
+  const expected = `${adaptForCursor(body)}\n`;
 
   if (checkOnly) {
     const current = await fs.readFile(skillPath, "utf8");
     if (current !== expected) {
       throw new Error(`${path.relative(repoRoot, skillPath)} is stale. Run node scripts/sync-skill.mjs.`);
     }
-    console.log(`${path.relative(repoRoot, skillPath)} matches ${skillUrl}`);
+    console.log(`${path.relative(repoRoot, skillPath)} is synchronized with ${skillUrl}`);
     return;
   }
 

scripts/validate-plugin.mjs

@@ -225,8 +225,8 @@ async function validateComponents() {
   if (ruleFiles.length !== 2) {
     addError(`expected 2 rules but found ${ruleFiles.length}.`);
   }
-  if (skillFiles.length !== 3) {
-    addError(`expected 3 skills but found ${skillFiles.length}.`);
+  if (skillFiles.length !== 11) {
+    addError(`expected 11 skills but found ${skillFiles.length}.`);
   }
   if (commandFiles.length !== 4) {
     addError(`expected 4 commands but found ${commandFiles.length}.`);
@@ -273,6 +273,31 @@ async function validateInstructionsAreCurrent() {
       addError(`${relativeFile} must call the direct MCP tool ${toolName}.`);
     }
   }
+
+  const skillToolRequirements = new Map([
+    ["skills/context-search/SKILL.md", ["web-search"]],
+    ["skills/context-scrape/SKILL.md", ["web-scrape-markdown", "web-scrape-html", "web-scrape-images", "web-screenshot"]],
+    ["skills/context-crawl/SKILL.md", ["web-scrape-sitemap", "web-crawl"]],
+    ["skills/context-extract/SKILL.md", ["web-extract"]],
+    ["skills/context-parse/SKILL.md", ["parse-document"]],
+    ["skills/context-brand/SKILL.md", ["get-brand", "brand-retrieve-unified", "web-styleguide", "web-fonts", "web-naics", "web-sic"]],
+    ["skills/context-monitor/SKILL.md", ["create-monitor", "update-monitor", "delete-monitor", "run-monitor-now"]],
+    ["skills/context-batches/SKILL.md", ["submit-batch", "get-batch", "get-batch-results", "cancel-batch", "delete-batch"]],
+  ]);
+  for (const [relativeFile, toolNames] of skillToolRequirements) {
+    const content = await fs.readFile(path.join(repoRoot, relativeFile), "utf8");
+    for (const toolName of toolNames) {
+      if (!content.includes(`\`${toolName}\``)) {
+        addError(`${relativeFile} must reference the direct MCP tool ${toolName}.`);
+      }
+    }
+  }
+
+  const directApiSkill = await fs.readFile(path.join(repoRoot, "skills/context-dev/SKILL.md"), "utf8");
+  const directApiFields = parseFrontmatter(directApiSkill);
+  if (!directApiFields?.description?.includes("directly against the Context.dev REST API or SDKs")) {
+    addError("skills/context-dev/SKILL.md must activate only for direct API and SDK development.");
+  }
 }
 
 async function validateRequiredFiles() {

skills/context-batches/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: context-batches
+description: Run and manage large asynchronous Context.dev web jobs. Use when the user needs to scrape many URLs, crawl at scale, process up to 25,000 URLs in one job, avoid synchronous timeouts, inspect batch progress or results, or cancel or delete a previously submitted batch.
+---
+
+# Run asynchronous batches
+
+Use `submit-batch` for large URL collections or crawls that should continue asynchronously. Use direct scrape or crawl tools for small interactive requests.
+
+## Workflow
+
+1. Confirm whether the job is a URL scrape batch or a crawl batch.
+2. Validate the target list, requested output, limits, and optional webhook before submission.
+3. Supply an idempotency key when retrying a submission so a network retry cannot create a duplicate job.
+4. Record the returned batch ID.
+5. Check progress with `get-batch` and retrieve completed output with `get-batch-results`.
+6. Use `list-batches` when the user needs to locate an existing job.
+
+`submit-batch`, `cancel-batch`, and `delete-batch` change external state. Run them only when explicitly requested. Cancellation stops active work; deletion removes the stored batch record and must not be used as a substitute for cancellation.

skills/context-brand/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: context-brand
+description: Retrieve company brand intelligence and design data with Context.dev. Use when the user asks for a company's logo, colors, fonts, style guide, social profiles, description, industry, address, stock information, brand kit, or lookup by domain, name, email, ticker, ISIN, transaction descriptor, or direct URL.
+---
+
+# Retrieve brand intelligence
+
+Choose the Context.dev MCP tool by output and identifier:
+
+| Need | Tool |
+| --- | --- |
+| Visual brand profile for a domain | `get-brand` |
+| Raw structured brand data or a non-domain lookup | `brand-retrieve-unified` |
+| Website design system and component styling | `web-styleguide` |
+| Website font inventory | `web-fonts` |
+| NAICS classification | `web-naics` |
+| SIC classification | `web-sic` |
+
+## Workflow
+
+1. Prefer a bare domain such as `stripe.com` when available.
+2. Use `get-brand` when a visual card is useful; use `brand-retrieve-unified` when the result feeds code or a structured workflow.
+3. Set `maxSpeed` as a boolean only when the user prioritizes speed over slower enrichment steps.
+4. Select logo variants by type and light/dark mode rather than assuming the first logo is correct.
+5. Preserve nullable fields and provide sensible presentation fallbacks without inventing data.
+
+For dynamic frontend logo URLs, use the separate `logolink` skill. Do not expose a private Context API key in browser code.

skills/context-crawl/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: context-crawl
+description: Discover or read multiple pages from a website with Context.dev. Use when the user asks to map a site, find URLs in a sitemap, crawl documentation or a site section, gather several linked pages, or locate the most relevant pages within one domain.
+---
+
+# Map and crawl websites
+
+Choose between URL discovery and content collection:
+
+- Use `web-scrape-sitemap` to discover and rank URLs without reading every page.
+- Use `web-crawl` to retrieve content from a bounded set of linked pages.
+
+## Workflow
+
+1. Confirm the target domain or starting URL and the section the user cares about.
+2. Use sitemap search when the user wants particular pages rather than the whole site.
+3. Apply path, subdomain, and link limits that match the request.
+4. Keep synchronous crawls focused; do not expand scope beyond the requested site or section.
+5. Return page URLs alongside the relevant content so results remain traceable.
+
+Use `web-scrape-markdown` for one known page. For a large crawl or thousands of URLs, use `submit-batch` instead of forcing the work through a synchronous crawl.

skills/context-dev/SKILL.md

@@ -1,8 +1,7 @@
 ---
 name: context-dev
-description: Use this skill to call the Context.dev API for brand data and web extraction. Make sure to use this skill whenever the user wants to look up a company's logo, colors, socials, industry, address, employee count, or stock ticker by domain, name, work email, ticker, or ISIN; enrich a lead or CRM record; enrich a person or contact from an email, name, or social profile URL; pre-fill an onboarding form; build a customer logo wall or "trusted by" strip; categorize a card or bank transaction descriptor (e.g. "AMZN MKTP US"); scrape a webpage to clean markdown or HTML for an LLM or RAG pipeline; crawl a site or fetch its sitemap; run a web search; extract products or pricing from a storefront; take a screenshot of a webpage; pull a website's design system (colors, fonts, spacing, components) for theming; classify a company by NAICS or SIC; or extract structured data from a website with a JSON Schema, even if they don't explicitly mention "Context.dev" or "Brand API". Requires a CONTEXT_DEV_API_KEY environment variable.
+description: Build application code directly against the Context.dev REST API or SDKs with server-side API-key authentication. Use when the user asks to integrate Context.dev into a codebase, choose an SDK method or REST endpoint, debug an API request, or implement a backend Context.dev workflow. For ordinary live-web work inside Cursor, use the focused Context.dev MCP skills instead.
 license: MIT
-compatibility: Requires a Context.dev API key in the CONTEXT_DEV_API_KEY environment variable. SDKs for TypeScript, Python, Ruby, Go, and PHP; or call the REST API directly.
 metadata:
   author: context.dev
   version: "3.1"

skills/context-extract/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: context-extract
+description: Extract schema-shaped JSON from websites with Context.dev. Use when the user wants structured records such as products, pricing plans, rankings, jobs, events, tables, listings, or explicitly requests JSON that follows a schema.
+---
+
+# Extract structured web data
+
+Use the Context.dev `web-extract` MCP tool when the output must have a predictable JSON shape rather than free-form page text.
+
+## Workflow
+
+1. Define the smallest JSON Schema that contains only the fields the user needs.
+2. Give every field a clear description that distinguishes similar values.
+3. Make fields optional or nullable when the source may omit them.
+4. Pass the relevant URL or URLs and describe the records to extract.
+5. Validate that the response follows the requested schema before presenting it.
+
+Preserve source semantics. Tied ranks such as `=19`, ranges such as `101-150`, and unavailable scores are legitimate source values; do not silently convert or invent them.
+
+Extraction does not remove site pagination. Discover additional pages with `web-scrape-sitemap`, then use a batch when many page URLs must be processed. Use `web-scrape-markdown` when the user only needs readable text.

skills/context-monitor/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: context-monitor
+description: Create and manage recurring website-change monitors with Context.dev. Use when the user wants ongoing tracking, scheduled checks, alerts, change history, monitor runs, or asks to watch a page or site for future changes rather than inspect it once.
+---
+
+# Monitor website changes
+
+Use monitors only for recurring work. For a one-time check, scrape or crawl instead.
+
+## Workflow
+
+1. Confirm the target, monitoring goal, schedule, and desired notification behavior.
+2. Use `create-monitor` only after the user clearly asks to create ongoing monitoring. Creation immediately queues the initial baseline.
+3. Do not call `run-monitor-now` immediately after creation unless the user asks for an additional run.
+4. Inspect results with `list-monitor-runs`, `get-monitor-run`, `list-monitor-changes`, `list-changes`, or `get-change`.
+5. Use `list-monitor-credit-usage` when the user asks about monitor consumption.
+
+Use `list-monitors` and `get-monitor` for inspection. `update-monitor`, `delete-monitor`, and `run-monitor-now` modify external state; execute them only when the user explicitly requests that action. Prefer pausing through `update-monitor` over deletion when the user only wants checks temporarily stopped.