From 2d6056160e88c397359335b724013427863ad8b6 Mon Sep 17 00:00:00 2001 From: George Pickett Date: Thu, 24 Sep 2026 18:02:42 -0700 Subject: [PATCH] fix: align Cursor plugin workflows with CLI 0.9.3 --- .cursor-plugin/plugin.json | 2 +- README.md | 99 +++++++++--------- commands/parallel-result.md | 16 ++- commands/parallel-setup.md | 70 ++++++------- commands/parallel-status.md | 8 +- rules/citation-standards.mdc | 4 +- skills/parallel-data-enrichment/SKILL.md | 56 +++++++---- skills/parallel-deep-research/SKILL.md | 88 ++++++++-------- skills/parallel-findall/SKILL.md | 123 +++++++++++++---------- skills/parallel-monitor/SKILL.md | 88 +++++++++------- skills/parallel-web-extract/SKILL.md | 38 ++++--- skills/parallel-web-search/SKILL.md | 32 ++++-- 12 files changed, 348 insertions(+), 276 deletions(-) diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 68f0674..b185dfc 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "parallel", "displayName": "Parallel", - "version": "0.2.0", + "version": "0.2.1", "description": "Web search, content extraction, deep research, data enrichment, entity discovery (FindAll), and web monitoring — powered by parallel-cli.", "author": { "name": "Parallel Web Systems", diff --git a/README.md b/README.md index b6d3115..9dfbb88 100644 --- a/README.md +++ b/README.md @@ -1,95 +1,86 @@ -# Parallel — Cursor Plugin +# Parallel Cursor Plugin -Web search, content extraction, deep research, and data enrichment powered by [parallel-cli](https://docs.parallel.ai/home). +Web search, content extraction, deep research, data enrichment, entity discovery and web monitoring powered by [parallel-cli](https://docs.parallel.ai/integrations/cli). ## Features +This source package contains six skills, nine commands and one citation rule. Cursor's official marketplace reviews updates separately from GitHub changes, so the installed listing may contain an earlier revision. Check the listing and installed version before assuming source features have shipped. + | Capability | Skill | Command | -|---|---|---| -| **Web Search** | `parallel-web-search` | `/parallel-search ` | -| **Content Extraction** | `parallel-web-extract` | `/parallel-extract ` | -| **Deep Research** | `parallel-deep-research` | `/parallel-research ` | -| **Data Enrichment** | `parallel-data-enrichment` | `/parallel-enrich ` | -| **Entity Discovery** | `parallel-findall` | `/parallel-findall ` | -| **Web Monitoring** | `parallel-monitor` | `/parallel-monitor ` | +| --- | --- | --- | +| Web Search | `parallel-web-search` | `/parallel-search ` | +| Content Extraction | `parallel-web-extract` | `/parallel-extract [url2]` | +| Deep Research | `parallel-deep-research` | `/parallel-research ` | +| Data Enrichment | `parallel-data-enrichment` | `/parallel-enrich ` | +| Entity Discovery | `parallel-findall` | `/parallel-findall ` | +| Web Monitoring | `parallel-monitor` | `/parallel-monitor ` | + +Additional commands: `/parallel-setup`, `/parallel-status ` and `/parallel-result `. Status and result are for research tasks only. -Additional commands: `/parallel-setup`, `/parallel-status `, `/parallel-result ` +The package uses the authenticated CLI and does not bundle an MCP server. Ordinary lookups use Search with its default `basic` mode. Deep research requires an explicit request. FindAll discovers entities; enrichment adds fields to an existing list. Monitors persist until cancelled and can incur charges on scheduled or triggered executions. ## Installation -1. Install the plugin in Cursor from the marketplace (or see [Local Development](#local-development) to test from source). -2. Run `/parallel-setup` to install `parallel-cli` and authenticate. +1. Install **Parallel** from Cursor's marketplace. +2. Run `/parallel-setup` in Cursor to check CLI installation, feature support and authentication. -### Manual CLI Setup +For manual setup, prefer pipx: ```bash -curl -fsSL https://parallel.ai/install.sh | bash +pipx install "parallel-web-tools[cli]" +pipx ensurepath parallel-cli login ``` -Or via pipx: +If pipx is unavailable, the standalone installer is another option: ```bash -pipx install "parallel-web-tools[cli]" +curl -fsSL https://parallel.ai/install.sh | bash parallel-cli login ``` -## Quick Start +This source package is checked against CLI 0.9.3. Monitor GA commands require ≥ 0.4.0, Entity Search ≥ 0.6.0, research text/context and enrichment suggestions ≥ 0.3.0, and optional Search `fast` ≥ 0.9.2. Upgrade through the original installation method using `/parallel-setup`, and verify the CLI in Cursor's terminal. Cursor and Parallel CLI versions are separate. -**Search the web:** -``` -/parallel-search latest developments in AI chip manufacturing -``` +`PARALLEL_API_KEY` overrides stored login credentials. `/parallel-setup` checks the active credential source without exposing secrets; stored organization metadata does not identify an overriding environment key's organization. -**Extract a webpage:** -``` -/parallel-extract https://example.com/article -``` +## Quick Start -**Deep research (slower, more thorough):** -``` +```text +/parallel-search latest developments in AI chip manufacturing +/parallel-extract https://docs.parallel.ai/integrations/cli https://docs.parallel.ai/integrations/cursor-marketplace /parallel-research comprehensive analysis of React vs Vue in 2026 -``` - -**Enrich data:** -``` /parallel-enrich companies.csv with CEO name, funding amount, and headquarters +/parallel-findall Find European climate-tech companies with headquarters and official homepage +/parallel-monitor Watch for official Parallel API changelog announcements daily ``` -## Local Development - -To test the plugin locally without installing from the marketplace: +Async research, enrichment and FindAll return IDs that should be saved before polling. Polling timeouts end the local wait; resume the saved job instead of submitting another. Research may produce JSON only or JSON plus Markdown. Async enrichment produces JSON; requested CSV is converted locally with failed rows retained. FindAll requested fields require verified enrichment output, and an Entity Search ID cannot be polled as a FindAll run. -1. Clone this repo: - ```bash - git clone https://github.com/parallel-web/parallel-cursor-plugin.git - ``` +Monitor setup must follow the user's requested schedule and notification destination. A CLI polling loop does not guarantee future notifications. Save its monitor ID, inspect events and completion history, and cancel it when monitoring is no longer wanted. -2. Open the repo in Cursor: - ```bash - cursor parallel-cursor-plugin - ``` +## Local Development -3. Skills and rules are auto-discovered from the standard directories. Type `/` in the chat to verify the `parallel-*` skills are listed. +Follow [Cursor's plugin documentation](https://cursor.com/docs/plugins) and [manifest reference](https://cursor.com/docs/reference/plugins). Test in a disposable Cursor environment so existing installs and work are preserved. -4. Commands are **not** auto-discovered when testing locally. Symlink them into Cursor's project commands directory: - ```bash - ln -s ../commands .cursor/commands - ``` +1. Clone this repository. +2. Confirm `~/.cursor/plugins/local/parallel` is absent before copying. If it exists, inspect its ownership and contents rather than overwriting it. +3. Copy the real package directory under that path, including `.cursor-plugin/plugin.json`, `skills`, `commands` and `rules`. Exclude `.git` and planning artifacts. Symlinks outside the local plugin directory are skipped. +4. Reload the disposable Cursor window. Inspect Customize for package origin, all six skills, nine commands and citation rule at the intended user or project scope. +5. Check that slash commands invoke their corresponding skills. Then use `/parallel-setup` to verify the terminal's CLI and credential source before an authorized capability test. -5. Type `/` again — the `parallel-*` commands should now appear alongside the skills. +A same-name marketplace plugin takes precedence over the local copy. Test with that conflict absent only in the disposable environment. Enterprise policy can block local imports; do not change policy to force a test. Opening this repository or adding project-command symlinks does not prove plugin loading. -6. Run `/parallel-setup` to confirm the CLI is installed and authenticated. +Verify each intended consumer independently, including the IDE, Agents Window and any Cursor CLI workflow. This source update does not establish propagation to cloud agents, Grok or Slack. Local loading and an upgrade rehearsal do not prove an official marketplace update or an existing marketplace install's upgrade. ## Plugin Structure -``` +```text .cursor-plugin/plugin.json Plugin manifest -skills/ 4 skills (auto-discovered) -commands/ 7 slash commands -rules/ Citation standards rule +skills/ 6 capability skills +commands/ 9 slash commands +rules/ 1 citation standards rule ``` ## License -MIT — see [LICENSE](LICENSE). +MIT. See [LICENSE](LICENSE). diff --git a/commands/parallel-result.md b/commands/parallel-result.md index 82bcca3..96857ef 100644 --- a/commands/parallel-result.md +++ b/commands/parallel-result.md @@ -1,16 +1,24 @@ --- name: parallel-result -description: "Get completed research task result. Usage: /parallel-result " +description: "Retrieve research task output only. Usage: /parallel-result " --- # Get Research Result ## Run ID: $ARGUMENTS +Use only a saved research `run_id`. Establish an unknown ID's origin first. For enrichment use `enrich poll`, for FindAll use `findall poll` or `findall result`, and for Monitor use `monitor events`. Never poll an Entity Search ID or Search/Extract session ID as research. + +Choose a concrete, run-specific output base in a persistent directory, such as `reports/research-`. Create the parent directory if needed and inspect existing `.json` and `.md` paths. Replace `$OUTPUT_BASE` below with that chosen base. + ```bash -parallel-cli research poll "$ARGUMENTS" --json +parallel-cli research poll "$ARGUMENTS" --timeout 60 -o "$OUTPUT_BASE" ``` -Present results in a clear, organized format. +Do not add `--json` or dump the full output into chat. On completion, JSON contains metadata and basis; Markdown exists only for text output. In that case, resolve `output.content_file` relative to the saved JSON. Read the actual saved paths and verify files exist before linking them. The CLI can fall back to temporary storage after a write error; inspect partial writes and copy the final files to the intended persistent location before claiming durable delivery. + +Existing files are refused unless `--force` is explicit. Prefer a fresh base, and use `--force` only when replacing those files is intended. Share an executive summary if printed; otherwise summarize only inspected relevant output. Report the actual paths and retain the returned `interaction_id` for Task follow-ups. + +Timeout exit 5 or interruption ends the local wait. Check the same saved task with `/parallel-status`, then resume this poll for a pending/running task. Retrieve completed output or report failed/cancelled/`action_required` states; never submit a replacement task because polling ended. -If CLI not found, tell user to run `/parallel-setup`. +If the binary is missing, use `/parallel-setup`. For a missing command or option, use its installation-specific upgrade guidance. For authentication errors, inspect `parallel-cli auth --json` and `authenticated`; a `403` alone does not prove insufficient balance. diff --git a/commands/parallel-setup.md b/commands/parallel-setup.md index 005bfc3..5960912 100644 --- a/commands/parallel-setup.md +++ b/commands/parallel-setup.md @@ -5,68 +5,64 @@ description: Set up the Parallel plugin (install CLI and authenticate) # Parallel Plugin Setup -## Step 1: Check if CLI is already installed +## Check the CLI in Cursor's terminal ```bash parallel-cli --version ``` -If this prints a version, skip to **Step 2: Authenticate**. - -## Step 1b: Attempt installation - -Try installing with the install script: +If the binary exists, check the help for the feature the user needs before skipping installation. This package is checked against CLI 0.9.3. Monitor's GA commands require ≥ 0.4.0, Entity Search ≥ 0.6.0, research text/context and enrichment suggestions ≥ 0.3.0, and optional native Search `fast` ≥ 0.9.2. Default Search remains `basic`. ```bash -curl -fsSL https://parallel.ai/install.sh | bash +parallel-cli monitor --help +parallel-cli findall entity-search --help +parallel-cli research run --help +parallel-cli search --help ``` -If that fails, try pipx: +`No such command`, `No such option` or `unrecognized arguments` indicates a stale or mismatched CLI interface. API, authentication and invalid-input errors do not indicate a version problem. Identify the install method before upgrading: + +| Install method | Upgrade | +| --- | --- | +| pipx | `pipx upgrade parallel-web-tools` | +| uv tool | `uv tool upgrade parallel-web-tools` | +| Homebrew | `brew upgrade parallel-web/tap/parallel-cli` | +| npm global | `npm update -g parallel-web-cli` | +| Standalone install script | `parallel-cli update` | + +Recheck version and feature help in the same Cursor terminal after upgrading. Do not use the standalone updater for a package-manager install. + +## Install when the binary is missing + +Prefer pipx for an isolated Python CLI installation: ```bash pipx install "parallel-web-tools[cli]" pipx ensurepath ``` -After either install method, verify it worked: +If pipx is unavailable, use the documented standalone installer in a terminal with the required network and filesystem access: ```bash -parallel-cli --version -``` - -### If installation fails - -Tell the user to re-run `/parallel-setup` with sandbox mode disabled. Installation requires network and filesystem access that Cursor's sandbox may block. - -Alternatively, they can install manually in their own terminal: - -``` curl -fsSL https://parallel.ai/install.sh | bash ``` -or: - -``` -pipx install "parallel-web-tools[cli]" -pipx ensurepath -``` - -They may need to add `~/.local/bin` to PATH in their shell config (e.g. `~/.zshrc`). Ask them to re-run `/parallel-setup` once installed. - -## Step 2: Authenticate +If an agent sandbox blocks installation, explain the specific error and give the user the appropriate terminal command. Do not tell them to disable sandboxing. Verify `parallel-cli --version` in Cursor's terminal; a successful install in another shell does not establish this terminal's PATH. If needed, add the actual installation bin directory (commonly `~/.local/bin`) to the shell PATH and open a new terminal. -Check if already authenticated: +## Check authentication and active credential source ```bash -parallel-cli auth +parallel-cli auth --json ``` -If not authenticated, tell the user to run `parallel-cli login` in their terminal, or set `PARALLEL_API_KEY` in their environment. +Inspect `authenticated`, `method`, `env_var_set` and `has_stored_credentials`. Exit zero alone is not success: this command also exits zero with `authenticated: false`. Authentication status reports available credentials; it does not validate API access, credit or account policy. -## Step 3: Verify +If `authenticated` is false, tell the user to run `parallel-cli login` in their terminal or set `PARALLEL_API_KEY` in the environment inherited by Cursor. Never request or print credentials in chat. -```bash -parallel-cli auth -``` +If `method` is `environment`, `PARALLEL_API_KEY` overrides stored login. Any `selected_org_id` or `selected_org_name` describes the inactive stored login, not the environment key's organization. Report that distinction. The environment key's billing organization must be verified independently before an account-specific or paid test; do not claim that it belongs to the stored organization. Do not switch accounts or remove overrides automatically. + +If `method` is `oauth`, selected organization metadata describes the active stored login. Report only nonsecret account metadata needed for the request. + +## Verify readiness -Confirm the CLI is installed, authenticated, and ready to use. +Repeat `parallel-cli auth --json` in the agent's terminal and confirm the binary, required feature help and `authenticated` boolean. State the active credential source and any unverified organization or API-access limitation. Do not start a paid job or add funds merely to prove setup. For a `403`, inspect the actual permissions, policy or billing error before suggesting a remedy. diff --git a/commands/parallel-status.md b/commands/parallel-status.md index 8d335e9..bfbde56 100644 --- a/commands/parallel-status.md +++ b/commands/parallel-status.md @@ -1,14 +1,18 @@ --- name: parallel-status -description: "Check running research task status. Usage: /parallel-status " +description: "Check research task status only. Usage: /parallel-status " --- # Check Research Status ## Run ID: $ARGUMENTS +Use only a saved research `run_id`. If the ID's origin is unknown, establish which operation returned it before calling the CLI. Enrichment task groups use `enrich status`, FindAll runs use `findall status`, and monitors use `monitor get`. Entity Search IDs and Search/Extract session IDs cannot be checked as research tasks. + ```bash parallel-cli research status "$ARGUMENTS" --json ``` -If CLI not found, tell user to run `/parallel-setup`. +Inspect the exit status and JSON. Report pending/running, completed, failed/cancelled or `action_required` accurately. On failure, preserve the run ID and report the returned error; do not create a new research task. An `action_required` state needs the indicated action, not indefinite polling. Use `/parallel-result` to retrieve completed output. + +If the binary is missing, use `/parallel-setup`. For a missing command or option, use its installation-specific upgrade guidance. For authentication errors, inspect `parallel-cli auth --json` and `authenticated`; a `403` alone does not prove insufficient balance. diff --git a/rules/citation-standards.mdc b/rules/citation-standards.mdc index 29ce9bb..82f10af 100644 --- a/rules/citation-standards.mdc +++ b/rules/citation-standards.mdc @@ -24,10 +24,12 @@ When presenting information from web search results: **End every search response with a Sources section** listing all referenced URLs: -``` +```text Sources: - [Source Title](https://example.com/article) (Feb 2026) - [Another Source](https://example.com/other) (Jan 2026) ``` This Sources section is mandatory. Do not omit it. + +Include source dates only when returned or verified in retrieved content. Omit unknown dates rather than guessing them. diff --git a/skills/parallel-data-enrichment/SKILL.md b/skills/parallel-data-enrichment/SKILL.md index aaec446..6b46c82 100644 --- a/skills/parallel-data-enrichment/SKILL.md +++ b/skills/parallel-data-enrichment/SKILL.md @@ -23,9 +23,9 @@ If the user gave a vague intent ("enrich these companies with useful info") and parallel-cli enrich suggest "Find CEO and recent funding info" --json ``` -The response is an envelope: `{title, processor, enriched_columns, warnings}`. Extract just the **`enriched_columns` array** (not the whole envelope) and pass it as the value of `--enriched-columns` on `enrich run`, **in place of `--intent`** — the two flags are alternative ways to specify what to enrich, not combined. If `suggest` returned a `processor`, pass it through explicitly via `--processor` on the `run` call (it's a tuned recommendation for the schema). Skip this whole section if the user already specified the fields they want. +The response is an envelope: `{title, processor, enriched_columns, warnings}`. Extract just the **`enriched_columns` array** (not the whole envelope) and pass it as the value of `--enriched-columns` on `enrich run`, **in place of `--intent`**. These flags are alternative ways to specify what to enrich. If `suggest` returned a `processor`, pass it explicitly via `--processor` on the `run` call. Skip this section if the user already specified the fields they want. -> `enrich suggest` requires `parallel-cli` ≥ 0.3.0. If it errors with anything resembling `no such command` / `No such command` / `unknown command`, **do not bail** — skip the suggestion step, fall through to step 1 with `--intent`, complete the run, and mention `parallel-cli update` (or `pipx upgrade parallel-web-tools`) in the final response so the user picks up the feature next time. +> `enrich suggest` requires `parallel-cli` ≥ 0.3.0. If only that command is missing, skip the optional suggestion step and use `--intent` in step 1. Suggest an installation-specific upgrade from Setup. Do not classify authentication, API or invalid-input failures as an older CLI. An intent-based run itself requests a suggestion; explicit columns default to `core-fast`, while intent can select another processor unless `--processor` overrides it. ## Step 1: Start the enrichment @@ -49,49 +49,65 @@ If this is a **follow-up** to a previous research task and you have its `interac parallel-cli enrich run --data '...' --intent "..." --target "output.csv" --no-wait --json --previous-interaction-id "$INTERACTION_ID" ``` -The enrichment will run with the full context of that prior research — so you can enrich entities discovered earlier without restating what was already found. Note: enrichment does **not** itself produce a new `interaction_id`, so you cannot chain a further follow-up off of an enrichment. +This reuses the prior Task's context. Context chaining is unavailable for Zero Data Retention (ZDR) accounts, so omit the flag there and include the needed context explicitly. Enrichment does **not** return a new `interaction_id`; retain the prior Task ID for later follow-ups. A `taskgroup_id` or Search/Extract `session_id` is not a Task interaction ID. **IMPORTANT:** Always include `--no-wait` so the command returns immediately instead of blocking. -Parse the `--json` output to extract `taskgroup_id` and `url`. The output is `{taskgroup_id, url, num_runs}` — there is no `interaction_id` field, do not look for one. Immediately tell the user: +Save the `--json` output's `taskgroup_id`, `url` and `num_runs` immediately. There is no `interaction_id` field. If creation is interrupted or its response is lost, inspect whether the group was created before submitting another run. Immediately tell the user: + - Enrichment has been kicked off - The monitoring URL where they can track progress -Tell them they can background the polling step to continue working while it runs. +The group runs server-side; polling can resume later using its saved ID. ## Step 2: Poll for results -Pick a concrete output path (e.g., `/tmp/enrichment-acme.json`). Note: the file is JSON regardless of the extension you choose — it's an array of `{input, output}` objects, not a CSV. Name it `.json` to avoid confusing yourself or the user. +Pick a persistent, run-specific output path (e.g., `enrichment-acme-tgrp-.json`). Polling overwrites its output file, so inspect any existing file and use a new path unless replacement is intended. The output is JSON regardless of extension: an array of rows with `input` and either `output` or `error`. Async polling does not include basis or per-row interaction IDs; do not invent citations or context IDs. ```bash -parallel-cli enrich poll "$TASKGROUP_ID" --timeout 540 --output "/tmp/enrichment-.json" +parallel-cli enrich poll "$TASKGROUP_ID" --timeout 60 --output "enrichment--.json" ``` Important: -- Use `--timeout 540` (9 minutes) to stay within tool execution limits -- The `--target` from step 1 is unused in `--no-wait` mode — only `--output` here determines where results are saved, and the file is always JSON -### If the poll times out +- Keep polls bounded; `--timeout 60` allows progress updates between waits. +- The `--target` from step 1 is unused in `--no-wait` mode. Only `--output` here determines where results are saved, and the file is always JSON. +- A completed group can include failed rows. Count rows containing `output` separately from rows containing `error` and compare their total with `num_runs`; an empty or incomplete file is not successful enrichment of the entire input. + +### If polling times out or is interrupted + +Timeout exit 5 or interruption ends the local wait. Check group state before saying it is still running: + +```bash +parallel-cli enrich status "$TASKGROUP_ID" --json +``` + +Inspect `is_active`, `status_counts` and `num_runs`. Resume the same poll for an active group, or retrieve results for an inactive group and report failures or unresolved rows. Do not recreate the group on a timeout or automatically rerun failed rows. A local file-write failure can be retried with the same group ID and a writable output path. + +### If the user requested CSV -Enrichment of large datasets can take longer than 9 minutes. If the poll exits without completing: -1. Tell the user the enrichment is still running server-side -2. Re-run the same `parallel-cli enrich poll` command to continue waiting +Convert the saved JSON locally into a separate CSV. Preserve every original input column and row, including duplicate and failed rows; keep enrichment fields separate from conflicting input names and include an error column for failures. Do not assume streamed rows match original input order or guess a join when row identity is ambiguous. Validate the row count and leave the input CSV untouched. This is local conversion, not a CSV produced by async polling; report both JSON and CSV paths. ## Response format **After step 1:** Share the monitoring URL (for tracking progress). **After step 2:** -1. Report number of rows enriched -2. Preview first few rows from the output file (it's a JSON array of `{input, output}` objects) + +1. Report successful, failed and total row counts, with any missing results called out. +2. Preview a few successful rows and a representative failure if present, without claiming all rows succeeded. 3. Tell the user the full path to the output file -Do NOT re-share the monitoring URL after completion — the results are in the output file. +After completion, link the saved output rather than repeating the monitoring URL. ## If the `parallel-cli` binary is not installed -If the shell reports `command not found: parallel-cli` (i.e. the binary itself is missing — distinct from a `No such command` error from a stale CLI, which the in-body guidance above covers), **stop immediately**. Do NOT search the web yourself, do NOT use any built-in search tools, and do NOT try to answer the query from your own knowledge. Instead, tell the user: +If the shell reports `command not found: parallel-cli`, stop and tell the user to run `/parallel-setup`, then retry their request. Do not substitute built-in search, another provider or an answer from memory. + +### Command and authentication failures + +`No such command`, `No such option` or `unrecognized arguments` from an installed CLI indicate a stale or mismatched interface. Check its version and upgrade through its installation method using `/parallel-setup`; `parallel-cli update` is for standalone installs only. Verify the required command in the same Cursor terminal before retrying. + +For authentication errors, run `parallel-cli auth --json` and inspect `authenticated`; exit zero alone does not prove authentication. Use `/parallel-setup` for terminal login or environment-key guidance, without requesting credentials in chat. A `403` can be an authorization or billing error: report the actual error and do not assume insufficient balance or add funds automatically. -1. `parallel-cli` is not installed -2. Run `/parallel-setup` to install it -3. Then retry their request +For other API/input errors, report the error without calling it a version problem. Reuse saved run IDs to resume asynchronous work. After an ambiguous creation failure, resolve whether a job exists before retrying creation. diff --git a/skills/parallel-deep-research/SKILL.md b/skills/parallel-deep-research/SKILL.md index 380eb86..5faf7ea 100644 --- a/skills/parallel-deep-research/SKILL.md +++ b/skills/parallel-deep-research/SKILL.md @@ -1,6 +1,6 @@ --- name: parallel-deep-research -description: "ONLY use when user explicitly says 'deep research', 'exhaustive', 'comprehensive report', or 'thorough investigation'. Slower and more expensive than parallel-web-search. For normal research/lookup requests, use parallel-web-search instead. Supports multi-turn: pass --previous-interaction-id from a prior research or enrichment to continue with context." +description: "ONLY use when user explicitly says 'deep research', 'exhaustive', 'comprehensive report', or 'thorough investigation'. Slower and more expensive than parallel-web-search. For normal research/lookup requests, use parallel-web-search instead. Supports follow-ups with a known prior Task interaction ID." compatibility: Requires parallel-cli >= 0.3.0 and internet access. allowed-tools: Bash(parallel-cli:*) metadata: @@ -11,15 +11,15 @@ metadata: Research topic: $ARGUMENTS -> Requires `parallel-cli` ≥ 0.3.0. If any command below errors with `no such option`, `no such command`, or `unrecognized arguments`, the user is on an older CLI. Tell them to run `parallel-cli update` (or `pipx upgrade parallel-web-tools` if installed via pipx), then retry. +> Requires `parallel-cli` ≥ 0.3.0 for text output and context chaining. If a documented command or option is missing, check `parallel-cli --version` and that command's `--help`, then follow the installation-specific upgrade guidance in Setup. API, authentication and input errors are not evidence of an older CLI. ## When to use (vs parallel-web-search) -ONLY use this skill when the user explicitly requests deep/exhaustive research. Deep research is 10-100x slower and more expensive than parallel-web-search. For normal "research X" requests, quick lookups, or fact-checking, use **parallel-web-search** instead. +ONLY use this skill when the user explicitly requests deep/exhaustive research. It can take several minutes and costs more than a quick search, depending on the processor and task. For normal "research X" requests, quick lookups, or fact-checking, use **parallel-web-search** instead. ## Step 1: Start the research -Choose a descriptive filename based on the topic (e.g., `ai-chip-market-2026`, `react-vs-vue-comparison`). Use lowercase with hyphens, no spaces. Reuse this base name in step 2 as `-o "$FILENAME"`. +Choose a descriptive output base in a persistent directory (e.g., `reports/ai-chip-market-2026`). Include the returned run ID to make it unique, then use this base in step 2 as `-o "$FILENAME"`. Check for existing `.json` and `.md` files before saving. ```bash parallel-cli research run "$ARGUMENTS" --processor pro-fast --text --no-wait --json @@ -29,80 +29,82 @@ The `--text` flag tells the API to return a markdown report (with inline citatio Optional with `--text`: pass `--text-description "Keep under 1500 words, focus on M&A activity"` to steer length, format, or focus. -If this is a **follow-up** to a previous research or enrichment task where you know the `interaction_id`, add context chaining: +If this is a **follow-up** and you have a prior Task's returned `interaction_id`, add context chaining. An enrichment `taskgroup_id` and a Search/Extract `session_id` are not Task interaction IDs. Async enrichment does not return a new interaction ID; retain the prior Task ID instead. Context chaining is unavailable for Zero Data Retention (ZDR) accounts, so omit it there and provide the needed context explicitly. ```bash parallel-cli research run "$ARGUMENTS" --processor lite-fast --text --no-wait --json --previous-interaction-id "$INTERACTION_ID" ``` -By chaining `interaction_id` values across requests, each follow-up question automatically has the full context of prior turns — so you can drill deeper without restating what was already researched. Use a lighter processor (`lite-fast` or `base-fast`) for follow-ups since the heavy lifting was done in the initial turn. +This reuses the prior Task's context. A lighter processor (`lite-fast` or `base-fast`) can suit a focused follow-up; choose based on the new question's depth rather than assuming all follow-ups are simple. -This returns instantly. Do NOT omit `--no-wait` — without it the command blocks for minutes and will time out. +Always use `--no-wait` to separate creation from bounded polling. Save the returned IDs immediately. If creation is interrupted or its response is lost, do not submit a replacement until you have checked whether the first task was created. -Processor options (choose based on user request): +Use `pro-fast` by default for exploratory research. Run `parallel-cli research processors` for the installed CLI's processor list and latency estimates; these are not deadlines. Choose `ultra` tiers only when explicitly requested and within the user's approved budget. Check [current pricing](https://parallel.ai/pricing) rather than quoting fixed cost multipliers. -| Processor | Expected latency | Use when | -|-----------|-----------------|----------| -| `lite-fast` | 10–60s | Quick lookups, follow-ups | -| `base-fast` | 15–100s | Simple questions | -| `core-fast` | 1–5 min | Moderate research | -| `pro-fast` | 2–10 min | **Default** — exploratory research, good depth/speed balance | -| `ultra-fast` | 5–25 min | Multi-source deep research (~2× cost) | -| `ultra2x-fast` / `ultra4x-fast` / `ultra8x-fast` | up to 2 hr | Hardest questions, only when explicitly requested | +Fast variants prioritize speed and may use less fresh indexed data. Standard variants may suit freshness-sensitive work, but neither choice guarantees that every source was fetched live. State the relevant date or freshness requirement in the research prompt and check the returned evidence. -Notes on the `-fast` suffix: `-fast` tiers use cached web data and are quicker. The non-fast variants (`pro`, `ultra`, etc.) re-fetch fresher data — slower but better for very recent events. Default to `-fast` unless the user specifically asks about news from the last day or two. +Parse the JSON output to save `run_id`, `interaction_id`, and `result_url`. Immediately tell the user: -Run `parallel-cli research processors` to see the full list with latencies. - -Parse the JSON output to extract the `run_id`, `interaction_id`, and monitoring URL. Immediately tell the user: - Deep research has been kicked off -- The expected latency for the processor tier chosen (from the table above) +- The estimated latency for the selected processor, if available - The monitoring URL where they can track progress -Tell them they can background the polling step to continue working while it runs. +The task runs server-side; polling can resume later using the saved `run_id`. ## Step 2: Poll for results ```bash -parallel-cli research poll "$RUN_ID" -o "$FILENAME" --timeout 540 +parallel-cli research poll "$RUN_ID" -o "$FILENAME" --timeout 60 ``` Important: -- Use `--timeout 540` (9 minutes) to stay within tool execution limits -- Do NOT pass `--json` — the full output is large and will flood context. The `-o` flag writes results to files instead. + +- Keep each poll bounded; `--timeout 60` allows progress updates between waits. +- Avoid `--json` when polling a large report. The `-o` flag saves the full result to files. - With `-o "$FILENAME"`: - `$FILENAME.json` is always written (metadata + basis) - - `$FILENAME.md` is written **only if step 1 used `--text`** (markdown report) -- The poll command prints an **executive summary** to stdout when the research completes. Share this executive summary with the user — it gives them a quick overview without having to open the files. -- Pass `--force` if re-polling and you want to overwrite existing files + - `$FILENAME.md` is written only for returned text output, normally requested with `--text`; auto-schema results can remain JSON-only. + - For text, JSON references `output.content_file` relative to the saved JSON file instead of duplicating the report body. +- Share the executive summary if one was printed. Some successful outputs have no summary; do not invent one or treat its absence as failure. +- Existing output files are refused unless `--force` is explicit. Prefer a new base; use `--force` only when overwriting those files is intended. +- Read the actual printed paths. On a write error, the CLI may fall back to the system temp directory, and writes may be partial. Inspect both locations before retrying. Copy a final report from temporary storage to the intended persistent location before presenting it as saved durably. + +### If polling times out or is interrupted -### If the poll times out +Timeout exit 5 or interruption ends the local wait, not necessarily the server task. Check the saved task: + +```bash +parallel-cli research status "$RUN_ID" --json +``` -Higher processor tiers can take longer than 9 minutes. If the poll exits without completing: -1. Tell the user the research is still running server-side -2. Re-run the same `parallel-cli research poll` command to continue waiting +Resume the same poll only for a pending/running task; retrieve completed output and report failed/cancelled or `action_required` states accurately. The CLI's polling loop may not recognize `action_required`, so do not poll that state indefinitely. Never recreate the task merely because a local wait ended. ## Response format -**After step 1:** Share the monitoring URL (for tracking progress only — it is not the final report). +**After step 1:** Share the monitoring URL for tracking progress. **After step 2:** -1. Share the **executive summary** that the poll command printed to stdout + +1. Share the executive summary if printed; otherwise say the result is saved and provide a brief summary only from inspected output when needed. 2. Tell the user the generated file paths: - - `$FILENAME.md` — formatted markdown report (if `--text` was used) - - `$FILENAME.json` — metadata and basis + - Actual `.md` path, if a text report exists + - Actual `.json` path with metadata and basis (and structured content for JSON output) 3. Share the `interaction_id` and tell the user they can ask follow-up questions that build on this research (e.g., "drill deeper into X" or "compare that to Y") -Do NOT re-share the monitoring URL after completion — the results are in the files, not at that link. +After completion, link the saved files rather than repeating the monitoring URL. -Ask the user if they would like to read through the files for more detail. Do NOT read the file contents into context unless the user asks. +Avoid loading the whole report into context. Read only the relevant sections when answering a requested summary or follow-up, and cite the returned sources. -**Remember the `interaction_id`** — if the user asks a follow-up question that relates to this research, use it as `--previous-interaction-id` in the next research or enrichment command. +**Remember the `interaction_id`:** use it for a related research or enrichment follow-up when context chaining is supported by the account. ## If the `parallel-cli` binary is not installed -If the shell reports `command not found: parallel-cli` (i.e. the binary itself is missing — distinct from a `No such command` error from a stale CLI, which the in-body guidance above covers), **stop immediately**. Do NOT search the web yourself, do NOT use any built-in search tools, and do NOT try to answer the query from your own knowledge. Instead, tell the user: +If the shell reports `command not found: parallel-cli`, stop and tell the user to run `/parallel-setup`, then retry their request. Do not substitute built-in search, another provider or an answer from memory. + +### Command and authentication failures + +`No such command`, `No such option` or `unrecognized arguments` from an installed CLI indicate a stale or mismatched interface. Check its version and upgrade through its installation method using `/parallel-setup`; `parallel-cli update` is for standalone installs only. Verify the required command in the same Cursor terminal before retrying. + +For authentication errors, run `parallel-cli auth --json` and inspect `authenticated`; exit zero alone does not prove authentication. Use `/parallel-setup` for terminal login or environment-key guidance, without requesting credentials in chat. A `403` can be an authorization or billing error: report the actual error and do not assume insufficient balance or add funds automatically. -1. `parallel-cli` is not installed -2. Run `/parallel-setup` to install it -3. Then retry their request +For other API/input errors, report the error without calling it a version problem. Reuse saved run IDs to resume asynchronous work. After an ambiguous creation failure, resolve whether a job exists before retrying creation. diff --git a/skills/parallel-findall/SKILL.md b/skills/parallel-findall/SKILL.md index a728449..ee43d82 100644 --- a/skills/parallel-findall/SKILL.md +++ b/skills/parallel-findall/SKILL.md @@ -1,7 +1,7 @@ --- name: parallel-findall description: "Discover entities (companies, people, products, etc.) matching a natural-language description. Use when the user asks to 'find all X' or 'list every Y that…' — e.g., 'Find AI startups that raised Series A in 2026', 'List roofing companies in Charlotte NC', 'Show me YC W24 dev tools companies'. Different from web-search (which returns webpages) and deep-research (which returns a narrative report). Use this when the user wants a structured list of entities." -compatibility: Requires parallel-cli >= 0.3.0 and internet access. +compatibility: Requires parallel-cli >= 0.6.0 and internet access. allowed-tools: Bash(parallel-cli:*) metadata: author: parallel @@ -11,92 +11,109 @@ metadata: Find: $ARGUMENTS -> Requires `parallel-cli` ≥ 0.3.0 (the `findall` command was added in 0.3.0). If `parallel-cli findall` errors with `no such command` or similar, tell the user to run `parallel-cli update` (or `pipx upgrade parallel-web-tools` if installed via pipx), then retry. +> Full FindAll requires `parallel-cli` ≥ 0.3.0; the optional `entity-search` path requires ≥ 0.6.0. If a documented command or option is missing, update through the installation method used for this CLI, then retry. See . ## When to use this skill -Use FindAll when the user wants a **structured list of entities** matching a description, not webpages or a narrative answer. +Use FindAll for a structured list of entities matching a description. Use parallel-web-search for webpages or quick answers, parallel-deep-research for narrative analysis, and parallel-data-enrichment to add fields to a list the user already has. -| User asks for… | Use | -|---|---| -| "Find all X that…" / "List every Y…" | **parallel-findall** (this skill) | -| Webpage results / quick answers / current info | parallel-web-search | -| Narrative report / analysis / "research X" | parallel-deep-research | -| Add fields to a list you already have | parallel-data-enrichment | +Default to the comprehensive, asynchronous `findall run`. It supports match conditions, exclusions, enrichment, evidence, and entity types beyond companies and people. “Find all” does not guarantee exhaustive internet coverage. -If the user already has a list and just wants to add fields, this is the wrong skill — use parallel-data-enrichment. +Use the synchronous `entity-search` path only when the user explicitly wants a quick or rough list of companies or people and accepts results without individual verification. Do not choose it just because the entity type is supported. It has no exclusions, generator selection, enrichment, or FindAll condition/enrichment citations. -## Step 1: Start the run +## Step 1: Start and retain the run + +Choose an unused, descriptive, run-specific `$FILENAME` for the saved JSON files. Pass the user's objective as one quoted argument, without shell evaluation. ```bash -parallel-cli findall run "$ARGUMENTS" --no-wait --json +parallel-cli findall run "$ARGUMENTS" --no-wait --json -o "/tmp/$FILENAME-create.json" ``` -Defaults: generator `core`, match limit `10`. Stick with `core` unless the user has a reason to escalate: -- `-g pro` — most thorough generator (slower, costlier). Use when the user asks for "comprehensive" coverage or matches are sparse on `core` -- `-g base` — fastest, but **markedly lower quality**. Often returns query-echo entities (e.g., directory pages, the literal query string), entries with no URL, or category placeholders. Only use if the user explicitly asks for a quick scan and accepts noise; otherwise prefer `core` -- `-n 50` — return up to 50 matched entities (5–1000 allowed) +Defaults are generator `core` and match limit `10`. Use `-n 50` for up to 50 matched entities; the allowed limit is 5–1000. Stay with `core` unless the user requests a different tradeoff. `pro` searches a larger pool and is slower/costlier; `base` is a faster, lower-quality option for an explicitly requested rough scan. Spot-check specific claims such as batch, year, and geography against available evidence, especially for `base`. -If the user wants to exclude known entities (e.g., "find competitors but not Google or OpenAI"): +For requested exclusions: ```bash parallel-cli findall run "$ARGUMENTS" --no-wait --json \ - --exclude '[{"name":"Google","url":"google.com"},{"name":"OpenAI","url":"openai.com"}]' + --exclude '[{"name":"Google","url":"google.com"},{"name":"OpenAI","url":"openai.com"}]' \ + -o "/tmp/$FILENAME-create.json" ``` -Tip — preview the schema first if the objective is ambiguous: `parallel-cli findall ingest "$ARGUMENTS" --json` shows the entity type and match conditions the API inferred, so you can refine wording before paying for a run. +If the objective needs clarification, `parallel-cli findall ingest "$ARGUMENTS" --json` previews the inferred entity type, conditions, and suggested enrichments. This calls the API; it is not an offline or free test. Refine the objective before creating the run if the inferred conditions differ from the user's intent. -Parse the JSON output to extract the `findall_id` and any monitoring URL. Tell the user: -- A FindAll run has been started -- Approximate cadence (minutes for `core`, longer for `pro`) -- They can keep working while it runs +Capture the returned `findall_id` immediately, along with the objective, generator, match limit and exclusions. Report that the run started and give a monitoring URL only if one was actually returned. Do not infer a URL or a guaranteed completion time. If the creation response is lost, resolve the existing job before submitting again. -## Step 2: Poll for results +## Step 2: Add requested fields explicitly -Choose a descriptive filename (e.g., `series-a-ai-2026`, `charlotte-roofers`). Use lowercase with hyphens, no spaces. +`--no-wait` ingests and creates the run but does **not** apply suggested enrichments. Requested output fields such as CEO name or employee count need a separate enrichment request; mentioning them in the objective is insufficient. ```bash -parallel-cli findall poll "$FINDALL_ID" -o "/tmp/$FILENAME.json" --timeout 540 +parallel-cli findall enrich "$FINDALL_ID" \ + '{"type":"object","properties":{"ceo":{"type":"string","description":"CEO name"},"employee_count":{"type":"number","description":"Number of employees"}}}' \ + -p core --json ``` -Important: -- Use `--timeout 540` (9 minutes) to stay within tool execution limits -- Do NOT pass `--json` for large result sets — it will flood context. `-o` saves the full results to disk +Use a JSON Schema object describing the user's fields, not the complete ingest envelope. Retain the exact submitted schema and processor locally with the run ID, including multiple requests if used. Do not rely on schema summaries to reconstruct them later. Enrichment adds non-boolean output data; it does not change match conditions. + +Enrichment can be added while the run is active or after completion. A terminal run can requeue to process the fields. Creation, enrichment acceptance, and populated results are separate outcomes. Do not claim the fields are ready from the enrichment response or a completed poll alone. + +## Step 3: Check status and retrieve results + +```bash +parallel-cli findall status "$FINDALL_ID" --json +parallel-cli findall poll "$FINDALL_ID" -o "/tmp/$FILENAME.json" --timeout 60 +parallel-cli findall result "$FINDALL_ID" -o "/tmp/$FILENAME-snapshot.json" +``` -### If the poll times out +Use bounded waits. A timeout (exit 5) or interrupt is local wait exhaustion, not cancellation. Check status and resume the same ID while it is active, within the user's waiting window; do not submit another run. The shared poller does not recognize the compatibility status `action_required`. If that status, `failed`, `cancelled`, or an inactive unfinished state appears, stop automatic waiting and report the state and saved ID as needing attention. -Re-run the same `parallel-cli findall poll` command to continue waiting. Server-side the run continues regardless. +`result` returns a snapshot and does not prove completion. Read `status` and `is_active` together. After enrichment, inspect each matched candidate's `output` for every requested field. If fields are missing, take further result snapshots within a bounded waiting window, even if the first poll said completed. Report missing, null, or failed values rather than inventing them; if the window expires, return partial results and the ID for resumption. An empty matched set is not proof of successful enrichment. -## Response format +Avoid `--json` for large result sets; `-o` retains the complete JSON. These commands can overwrite their selected files, so use paths belonging to this run. Preserve the raw candidate list and status. `/tmp` is temporary; copy requested deliverables to a persistent user location when needed. -Before presenting matches, **filter the results** for obvious noise: -- Drop entries with empty/missing `url` -- Drop entries whose `name` echoes the user's query (e.g., literal "YC W25 batch companies in developer tools") — those are search-result placeholders, not real entities -- Drop entries whose `url` is a third-party directory or profile page rather than the entity's own domain. Concretely: drop URLs on `linkedin.com`, `ycombinator.com/companies/...`, `crunchbase.com`, `pitchbook.com`, generic news/blog posts about the entity, etc. The URL should be something the entity itself owns (its product site, docs, or marketing site) +## Present matches and evidence -If filtering removes a meaningful share of matches, mention this to the user and suggest re-running with `-g pro` or a higher `-n`. +Present only candidates with `match_status: "matched"` as matches. Preserve generated, unmatched, and discarded candidates in the raw file. Review obvious query-echo placeholders and unsupported entries rather than treating every candidate as an entity. -**Sanity-check `-g base` results.** The base generator can hallucinate categorical attributes (e.g., return a YC S22 company as a YC W25 match). The filter rules above only catch URL/name shape, not factual correctness. If the user's query has a falsifiable attribute (a specific batch, year, geography, etc.), spot-check the kept entries against the source URL and flag any that don't fit. Recommend re-running with `-g core` (or higher) if **either** multiple kept entries fail the spot-check **or** noise filtering dropped a meaningful share of the matched set (say, ≥40%) — both indicate `base` isn't producing reliable results for this query. +Review URLs in the context of the entity. LinkedIn profiles can legitimately identify people, and YC or Crunchbase profiles can identify companies. Do not discard these solely because the entity does not own the domain. Flag missing or unverifiable URLs and use available evidence to resolve uncertainty. -Present the remaining (real) entities as a markdown table or list. Lead with the count, then list each entity with its name, URL, and a one-line description if available. Cite each entity with its source URL. +Use condition and enrichment basis for factual claims, with its source URLs. The entity's primary URL and a supporting citation may differ. Do not label a primary/profile URL as evidence for an attribute unless it supports the claim. -Tell the user: -- How many entities were matched (and how many were filtered as noise, if any) -- The full results path (`/tmp/$FILENAME.json`) -- That they can: - - Add fields to these results, e.g.: +Lead with the number of matched entities presented, note exclusions or unresolved entries, and use a table or list with names, URLs, and requested fields. Include the saved raw-results path, run ID, current state, and any incomplete fields. Sparse or noisy results can warrant suggesting a revised objective or generator; do not automatically create a replacement paid run. + +## Get more matches + +Extend only when the user requests additional matches: + +```bash +parallel-cli findall schema "$FINDALL_ID" --json +parallel-cli findall extend "$FINDALL_ID" 50 --json +``` - ```bash - parallel-cli findall enrich $FINDALL_ID '{"properties":{"ceo":{"type":"string"},"employee_count":{"type":"number"}}}' - ``` +`50` is an increment, not the new total. Check the known creation limit or current schema, including prior extensions, so the resulting total stays at or below 1000. Preview runs cannot be extended. A completed run is eligible only if its termination reason was `match_limit_met`; status/result in the CLI omit that reason and cannot prove eligibility. For an explicitly requested extension within the limit, let the API validate eligibility and surface any rejection without creating a new run automatically. - The schema is a JSON Schema-style object with `properties` mapping field names → `{type, description?}`. - - Get more matches: `parallel-cli findall extend $FINDALL_ID 50` +Retain the updated limit and poll the same ID for new results. Recheck requested enrichment fields; if the existing enrichment must be reapplied, use the original retained request payload and processor within the user's authorized scope. + +## Fast entity search + +Use only for explicit speed/rough-list intent and entity type `companies` or `people`. It is synchronous and returns `entity_set_id` plus ranked `entities`, not `findall_id` or verified candidates. + +```bash +parallel-cli findall entity-search "$ARGUMENTS" -t companies -n 10 -o "/tmp/$FILENAME.json" +``` + +The `-n` limit is 5–1000, default 10. Choose a limit proportional to the user's request. Avoid highly restrictive criteria on this path: relevance can decline toward the tail. Use full FindAll when individual condition checks or enrichment are required. + +Keep legitimate directory/profile links and review empty URLs or query-echo names. Present these as unverified leads, cite their links as links to the entities, and avoid attributing absent FindAll basis or verification to them. Report the saved path and returned count. Never pass an `entity_set_id` to FindAll poll/status/result/enrich/extend. If the user later requests those capabilities, explain that a separate full run is needed and retain the original quick results. ## If the `parallel-cli` binary is not installed -If the shell reports `command not found: parallel-cli` (i.e. the binary itself is missing — distinct from a `No such command` error from a stale CLI, which the in-body guidance above covers), **stop immediately**. Do NOT search the web yourself, do NOT use any built-in search tools, and do NOT try to answer the query from your own knowledge. Instead, tell the user: +If the shell reports `command not found: parallel-cli`, stop and tell the user to run `/parallel-setup`, then retry their request. Do not substitute built-in search, another provider or an answer from memory. + +### Command and authentication failures + +`No such command`, `No such option` or `unrecognized arguments` from an installed CLI indicate a stale or mismatched interface. Check its version and upgrade through its installation method using `/parallel-setup`; `parallel-cli update` is for standalone installs only. Verify the required command in the same Cursor terminal before retrying. + +For authentication errors, run `parallel-cli auth --json` and inspect `authenticated`; exit zero alone does not prove authentication. Use `/parallel-setup` for terminal login or environment-key guidance, without requesting credentials in chat. A `403` can be an authorization or billing error: report the actual error and do not assume insufficient balance or add funds automatically. -1. `parallel-cli` is not installed -2. Run `/parallel-setup` to install it -3. Then retry their request +For other API/input errors, report the error without calling it a version problem. Reuse saved run IDs to resume asynchronous work. After an ambiguous creation failure, resolve whether a job exists before retrying creation. diff --git a/skills/parallel-monitor/SKILL.md b/skills/parallel-monitor/SKILL.md index 9f838d7..6b78ef2 100644 --- a/skills/parallel-monitor/SKILL.md +++ b/skills/parallel-monitor/SKILL.md @@ -1,7 +1,7 @@ --- name: parallel-monitor -description: "Continuously track the web for changes on a recurring cadence. Use when the user asks to 'monitor', 'track changes to', 'watch', or 'alert me when' something on the web changes — e.g., 'Track price changes for iPhone 16', 'Alert me when Tesla files a new 8-K', 'Monitor competitor pricing pages weekly'. Also use to list, inspect, update, or delete existing monitors." -compatibility: Requires parallel-cli >= 0.3.0 and internet access. +description: "Continuously track the web for changes on a recurring cadence. Use when the user asks to 'monitor', 'track changes to', 'watch', or 'alert me when' something on the web changes — e.g., 'Track price changes for iPhone 16', 'Alert me when Tesla files a new 8-K', 'Monitor competitor pricing pages weekly'. Also use to list, inspect, update, or stop existing monitors, including requests to delete them." +compatibility: Requires parallel-cli >= 0.4.0 and internet access. allowed-tools: Bash(parallel-cli:*) metadata: author: parallel @@ -11,11 +11,13 @@ metadata: Action: $ARGUMENTS -> Requires `parallel-cli` ≥ 0.3.0 (the `monitor` command was added in 0.3.0). If `parallel-cli monitor` errors with `no such command` or similar, tell the user to run `parallel-cli update` (or `pipx upgrade parallel-web-tools` if installed via pipx), then retry. +> Requires `parallel-cli` ≥ 0.4.0 for the GA Monitor commands. If a Monitor command or option is missing, tell the user to update through their installation method (see ), then retry. ## What this skill does -Monitors are long-running, server-side jobs that re-check the web on a cadence and emit events when something changes. Unlike search/research/findall (one-shot lookups), monitors persist until deleted and can optionally fire a webhook on each event. +Monitors are long-running, server-side jobs that re-check the web on a cadence and emit events when something changes. Unlike search/research/findall (one-shot lookups), monitors persist until cancelled and can optionally deliver detected events through a webhook. Creation does not establish an ongoing agent notification service: explain how to read server-side events or use the configured webhook, without promising chat or email alerts. + +The default type is `event_stream`, with frequency `1d` and server processor `lite`. A `snapshot` monitor requires an existing Task run ID. Create or modify only the resource requested by the user; do not create a monitor just to demonstrate the skill. ## Decide the action @@ -27,36 +29,32 @@ Parse the user's request and pick one: | "What am I monitoring?" / "List monitors" | **list** | | "What changed?" / "Show me events for monitor X" | **events** | | "Show monitor X" / "Get details for X" | **get** | -| "Change cadence / query / webhook for X" | **update** | -| "Test the webhook" / "Fire a test event" | **simulate** (requires a webhook on the monitor) | -| "Show me the full payload for event group X" | **event-group** | -| "Stop / delete monitor X" | **delete** (always confirm before deleting) | +| "Change cadence / webhook for X" | **update** | +| "Check monitor X now" / "Run it now" | **trigger** | +| "Show me the full payload for event group X" | **events** with `--event-group-id` | +| "Stop / delete monitor X" | **cancel** (permanent; verify authority and exact ID) | ## Create a monitor ```bash -parallel-cli monitor create "" --cadence daily --json +parallel-cli monitor create "" --frequency 1d --json ``` -Cadence options: `hourly`, `daily` (default), `weekly`, `every_two_weeks`. Match cadence to how often the source actually changes — hourly for prices/news, weekly for filings/staffing. +Frequency accepts `` with `h`, `d`, or `w` (for example `1h`, `1d`, or `1w`), within the supported range of 1 hour to 30 days. The aliases `hourly`, `daily`, `weekly`, and `every_two_weeks` are also accepted. Match cadence to the user's request and how often the source actually changes. Optional flags: -- `--webhook https://example.com/hook` — POST events to a URL as they happen + +- `--webhook https://example.com/hook` — deliver detected events to a URL - `--metadata '{"team":"competitive-intel"}'` — attach JSON metadata for your own bookkeeping - `--output-schema ''` — structure the event payload (advanced) -Parse the JSON to extract the `monitor_id`. Tell the user: -- The monitor has been created with its ID -- The cadence (so they know when to expect first event) -- That events accumulate server-side — they can run `parallel-cli monitor events $MONITOR_ID` later to see what changed +Capture the returned `monitor_id` immediately with the query, frequency and requested settings. Verify creation with `get` using that ID. Tell the user: -If they configured a webhook, suggest testing it: - -```bash -parallel-cli monitor simulate "$MONITOR_ID" -``` +- The monitor has been created with its ID +- The frequency (so they know how often the monitor checks) +- That recent events are available server-side — they can run `parallel-cli monitor events $MONITOR_ID` later to see what changed -`simulate` requires a webhook to be configured on the monitor. Without one it errors with `Webhook not configured for this monitor` — do not run it on monitors created without `--webhook`. +If creation or another mutation times out or the response is lost, resolve the existing monitor/action before retrying. Resume with the saved ID, `get` and `events`; do not automatically recreate it. Recreating can duplicate persistent monitoring and billing. ## List monitors @@ -64,40 +62,60 @@ parallel-cli monitor simulate "$MONITOR_ID" parallel-cli monitor list -n 10 --json ``` -Default to `-n 10` — accounts with many historical monitors can return megabytes of JSON otherwise. Raise the limit only if the user explicitly asks for "all" or a larger set. Present as a table: ID, query (truncated), cadence, created. +Default to `-n 10` for concise output. `list` returns active monitors only by default; add `--status active --status cancelled` when the user asks to include cancelled monitors. Raise the limit only for a larger set. Present as a table: ID, query or Task Run (truncated), frequency, created. -> Note: `monitor list` is not guaranteed to be sorted newest-first, so a monitor you just created may not appear in the first page of results. If a user is verifying creation, prefer `monitor get $MONITOR_ID` (using the ID returned by create) over scanning the list. +> Note: `monitor list` is sorted newest-first. If a user is verifying creation, prefer `monitor get $MONITOR_ID` (using the ID returned by create) over scanning the list. ## View events for a monitor ```bash -parallel-cli monitor events "$MONITOR_ID" --lookback 10d --json +parallel-cli monitor events "$MONITOR_ID" --json +``` + +Events are returned newest-first. If the response contains `next_cursor`, pass it with `--cursor` to retrieve another page. + +An empty event list does not prove that a check completed without changes. To inspect completion history as well as detected events: + +```bash +parallel-cli monitor events "$MONITOR_ID" --include-completions --limit 10 --json ``` -Lookback format: `Nd` (days) or `Nw` (weeks). Default `10d`. +Distinguish typed detected events, no-change `completion` events and `error` events. Use their actual timestamps and report failures. An empty completion history is not execution proof. Retain `event_id` and `event_group_id` when present; these identify events and executions, not monitor IDs. For deeper detail on a specific event group: ```bash -parallel-cli monitor event-group "$MONITOR_ID" "$EVENT_GROUP_ID" --json +parallel-cli monitor events "$MONITOR_ID" --event-group-id "$EVENT_GROUP_ID" --json ``` -Summarize for the user: count of events in the period, then a bulleted list of what changed with timestamps. Cite source URLs from the event payload. +Event-group detail ignores pagination arguments. Summarize detected changes separately from completions/errors, with dates or timestamps. Read typed `output` or `changed_output` and available `basis`; cite its source URLs for factual claims. Do not invent provenance when the payload lacks basis. Surface response warnings and continue pagination only as needed for the requested period. -## Get / update / delete +## Get / update / trigger / cancel ```bash parallel-cli monitor get "$MONITOR_ID" --json -parallel-cli monitor update "$MONITOR_ID" --cadence weekly --json -parallel-cli monitor delete "$MONITOR_ID" --json +parallel-cli monitor update "$MONITOR_ID" --frequency 1w --json +parallel-cli monitor update "$MONITOR_ID" --webhook https://example.com/hook --json +parallel-cli monitor trigger "$MONITOR_ID" --json +parallel-cli monitor cancel "$MONITOR_ID" --json ``` -**Always confirm before deleting** — deletion is permanent. +Only supply fields the user requested to update. A webhook-only update leaves frequency unchanged; update has no default frequency. Metadata and advanced event-stream settings can also be updated through the CLI, but query and Task run identity are immutable. A different query needs a new monitor with separate authority and a deliberate decision about the old monitor; do not silently recreate or cancel it. + +`trigger` enqueues a real billed off-schedule execution without changing the regular schedule. It is not a synthetic webhook test and must not substitute for a request to test notification delivery. A successful trigger response confirms enqueueing, not completion. It emits a detected event only if material change is found; inspect completion history for no-change execution. Cancelled monitors cannot be triggered. + +Cancellation is irreversible, not deletion or a temporary pause. Explain this and obtain confirmation for the exact monitor ID unless the user has already authorized that permanent cancellation or cleanup of the specific disposable monitor. After cancelling, verify its state with `get`. Never recreate it automatically to resume monitoring. + +On authentication or API errors, report the actual error and retain IDs for recovery. Do not classify every error as an outdated CLI or every permission error as insufficient credit. Failed reads are not evidence that a monitor stopped; reading events does not cancel it. ## If the `parallel-cli` binary is not installed -If the shell reports `command not found: parallel-cli` (i.e. the binary itself is missing — distinct from a `No such command` error from a stale CLI, which the in-body guidance above covers), **stop immediately**. Do NOT search the web yourself, do NOT use any built-in search tools, and do NOT try to answer the query from your own knowledge. Instead, tell the user: +If the shell reports `command not found: parallel-cli`, stop and tell the user to run `/parallel-setup`, then retry their request. Do not substitute built-in search, another provider or an answer from memory. + +### Command and authentication failures + +`No such command`, `No such option` or `unrecognized arguments` from an installed CLI indicate a stale or mismatched interface. Check its version and upgrade through its installation method using `/parallel-setup`; `parallel-cli update` is for standalone installs only. Verify the required command in the same Cursor terminal before retrying. + +For authentication errors, run `parallel-cli auth --json` and inspect `authenticated`; exit zero alone does not prove authentication. Use `/parallel-setup` for terminal login or environment-key guidance, without requesting credentials in chat. A `403` can be an authorization or billing error: report the actual error and do not assume insufficient balance or add funds automatically. -1. `parallel-cli` is not installed -2. Run `/parallel-setup` to install it -3. Then retry their request +For other API/input errors, report the error without calling it a version problem. Reuse saved run IDs to resume asynchronous work. After an ambiguous creation failure, resolve whether a job exists before retrying creation. diff --git a/skills/parallel-web-extract/SKILL.md b/skills/parallel-web-extract/SKILL.md index bfab3cd..580166d 100644 --- a/skills/parallel-web-extract/SKILL.md +++ b/skills/parallel-web-extract/SKILL.md @@ -1,6 +1,6 @@ --- name: parallel-web-extract -description: "URL content extraction. Use for fetching any URL - webpages, articles, PDFs, JavaScript-heavy sites. Token-efficient: runs in forked context. Prefer over built-in WebFetch." +description: "CLI content extraction from one or more URLs, including webpages, articles and PDFs. Save JSON, preserve successful content and report per-URL failures." compatibility: Requires parallel-cli and internet access. allowed-tools: Bash(parallel-cli:*) metadata: @@ -15,30 +15,29 @@ Extract content from: $ARGUMENTS Choose a short, descriptive filename based on the URL or content (e.g., `vespa-docs`, `react-hooks-api`). Use lowercase with hyphens, no spaces. Substitute it into the command **inline** — `$FILENAME` is a placeholder, not a shell variable. -```bash -parallel-cli extract "$ARGUMENTS" --json -o "/tmp/$FILENAME.json" -``` - -Concrete example: +Pass each requested URL as a separate quoted positional argument, up to 20 per call. Do not collapse multiple URLs into one quoted `$ARGUMENTS` string or use `eval` to split them. Construct arguments directly from the requested URLs. For example: ```bash -parallel-cli extract "https://docs.parallel.ai" --json -o "/tmp/parallel-docs.json" +parallel-cli extract "https://docs.parallel.ai/integrations/cli" "https://docs.parallel.ai/integrations/cursor-marketplace" --json -o "/tmp/parallel-docs.json" ``` -Note: `-o` always saves JSON. The extension must be `.json`. +`-o` saves JSON. Use a `.json` extension and inspect an existing path before use because Extract overwrites it. Read the saved file as authoritative; stdout may truncate and human-readable output previews only part of the content. Do not treat a stale file as a successful response after a failed call. Options if needed: + - `--objective "focus area"` to focus extraction on a specific goal (also silences the "neither objective nor search_queries" warning that V1 emits when neither is set) - `-q "keyword"` (repeatable) to prioritize keywords in excerpts - `--full-content` to include the complete page body (for long articles, PDFs, or when excerpts may not capture what you need) - `--full-content-max-chars N` to cap full-content size per result - `--no-excerpts` to strip excerpts when you only want full content +- `--session-id ""` to group related Search/Extract calls. A session ID is not a Task interaction ID or run ID; never use it with research status/poll or `--previous-interaction-id` ## Handling failed extractions -If the response has an `errors` field, an empty `results` array, or a 404/timeout for the URL, do NOT fabricate content. Tell the user the extraction failed, surface the upstream status, and suggest: +Inspect the exit status, API error, `results`, per-URL `errors` and any warnings. `errors: []` is normal success. Nonempty errors can coexist with successful results: retain and present successful content, then name each failed URL and its returned reason. Empty results or missing content are not a successful extraction. Do not fabricate content. For affected URLs, suggest: + - Verifying the URL (the page may have moved) -- Retrying with `--full-content` if excerpts came back empty but the page exists +- Requesting `--full-content` if excerpts are empty but the returned metadata supports that the page was fetched - Using `parallel-cli search` to locate the current URL if the page was renamed ## Response format @@ -47,18 +46,25 @@ Return content as: **[Page Title](URL)** -Then the extracted content verbatim, with these rules: +Use returned `full_content` for full-page requests; excerpts alone are selected passages and must be labelled as such. Even full content may be capped by `--full-content-max-chars` or upstream limits; do not promise completeness when capped. Preserve retrieved content verbatim, with these rules: + - Keep content verbatim - do not paraphrase or summarize -- Parse lists exhaustively - extract EVERY numbered/bulleted item +- Preserve every numbered/bulleted item in the retrieved content; do not claim an excerpt contains the whole page - Strip only obvious noise: nav menus, footers, ads - Preserve all facts, names, numbers, dates, quotes After the response, mention the output file path (`/tmp/$FILENAME.json`) so the user knows it's available for follow-up questions. +For large content, keep the full verbatim text in the saved file and provide a brief labelled preview plus its path. Never silently truncate content while claiming it is the complete extraction. + ## If the `parallel-cli` binary is not installed -If the shell reports `command not found: parallel-cli` (i.e. the binary itself is missing — distinct from a `No such command` error from a stale CLI, which the in-body guidance above covers), **stop immediately**. Do NOT search the web yourself, do NOT use any built-in search tools, and do NOT try to answer the query from your own knowledge. Instead, tell the user: +If the shell reports `command not found: parallel-cli`, stop and tell the user to run `/parallel-setup`, then retry their request. Do not substitute built-in search, another provider or an answer from memory. + +### Command and authentication failures + +`No such command`, `No such option` or `unrecognized arguments` from an installed CLI indicate a stale or mismatched interface. Check its version and upgrade through its installation method using `/parallel-setup`; `parallel-cli update` is for standalone installs only. Verify the required command in the same Cursor terminal before retrying. + +For authentication errors, run `parallel-cli auth --json` and inspect `authenticated`; exit zero alone does not prove authentication. Use `/parallel-setup` for terminal login or environment-key guidance, without requesting credentials in chat. A `403` can be an authorization or billing error: report the actual error and do not assume insufficient balance or add funds automatically. -1. `parallel-cli` is not installed -2. Run `/parallel-setup` to install it -3. Then retry their request +For other API/input errors, report the error without calling it a version problem. Reuse saved run IDs to resume asynchronous work. After an ambiguous creation failure, resolve whether a job exists before retrying creation. diff --git a/skills/parallel-web-search/SKILL.md b/skills/parallel-web-search/SKILL.md index 3a5ee13..8d4bd66 100644 --- a/skills/parallel-web-search/SKILL.md +++ b/skills/parallel-web-search/SKILL.md @@ -1,6 +1,6 @@ --- name: parallel-web-search -description: "DEFAULT for all research and web queries. Use for any lookup, research, investigation, or question needing current info. Fast and cost-effective. Only use parallel-deep-research if user explicitly requests 'deep' or 'exhaustive' research." +description: "CLI web search, the default for lookups, current information and research queries. Save retrieved sources as JSON and cite them. Only use parallel-deep-research when the user explicitly requests deep or exhaustive research." compatibility: Requires parallel-cli and internet access. allowed-tools: Bash(parallel-cli:*) metadata: @@ -28,25 +28,31 @@ parallel-cli search "latest React 19 features and adoption" -q "React 19" -q "co The first argument is the **objective** — a natural language description of what you're looking for. It replaces multiple keyword searches with a single call for broad or complex queries. Add `-q` flags for specific keyword queries to supplement the objective. The `-o` flag saves the full results to a JSON file for follow-up questions. Options if needed: + - `--after-date YYYY-MM-DD` for time-sensitive queries - `--include-domains domain1.com,domain2.com` to limit to specific sources - `--exclude-domains domain.com` to filter out noisy sources -- `--mode advanced` for harder questions (multi-step, agentic search). Default `basic` is right for almost everything; only escalate when basic results are insufficient +- `--mode turbo` for simple fact lookups where speed matters most; supports English and Japanese queries +- `--mode fast` for high-quality search within an approximately one-second latency budget; requires CLI ≥ 0.9.2, and latency is not guaranteed +- `--mode advanced` for harder questions (multi-step, agentic search). Keep the default `basic` unless the request needs another mode - `--location us` (ISO 3166-1 alpha-2) for geo-targeted results +- `--session-id ""` to group related Search/Extract calls when a prior response returned one. A `session_id` or `search_id` is not a Task interaction ID or research run ID; never send it to research status/poll or `--previous-interaction-id` ## Parsing results -Do not set `max_output_tokens` on the command execution — the output is already bounded by `--max-results` and `--excerpt-max-chars-total`. Capping output tokens will truncate the JSON and break parsing. +**Read the saved `-o` JSON file as the authoritative payload.** Result and excerpt limits bound requested content, but stdout can still exceed the tool's output limit. Truncated stdout is not parseable JSON and is not proof of incomplete saved results. Inspect an existing output path before using it because Search overwrites that file. For each result, extract: -**Prefer reading from the saved `-o` file**, not stdout. Even bounded output regularly exceeds harness stdout limits and gets truncated. Read `/tmp/$FILENAME.json` for the authoritative payload. For each result, extract: -- title, url, publish_date +- title, url, and publish_date if provided; omit unknown dates - Useful content from excerpts (skip navigation noise like menus, footers, "Skip to content") +Check the exit status, returned API error and `warnings` before presenting results. On an error or empty `results`, report what happened and do not fabricate an answer. An old output file is not evidence that a failed request succeeded. For sparse results, state the coverage limits; refine the objective or queries only when useful for the user's request. + ## Response format **CRITICAL: Every claim must have an inline citation.** Use markdown links like [Title](URL) pulling only from the JSON output. Never invent or guess URLs. Synthesize a response that: + - Leads with the key answer/finding - Includes specific facts, names, numbers, dates - Cites every fact inline as [Source Title](url) — do not leave any claim uncited @@ -54,7 +60,7 @@ Synthesize a response that: **End with a Sources section** listing every URL referenced: -``` +```text Sources: - [Source Title](https://example.com/article) (Feb 2026) - [Another Source](https://example.com/other) (Jan 2026) @@ -62,12 +68,18 @@ Sources: This Sources section is mandatory. Do not omit it. +Only include source dates that were returned or verified in the retrieved content. Leave the date out when unknown. + After the Sources section, mention the output file path (`/tmp/$FILENAME.json`) so the user knows it's available for follow-up questions. ## If the `parallel-cli` binary is not installed -If the shell reports `command not found: parallel-cli` (i.e. the binary itself is missing — distinct from a `No such command` error from a stale CLI, which the in-body guidance above covers), **stop immediately**. Do NOT search the web yourself, do NOT use any built-in search tools, and do NOT try to answer the query from your own knowledge. Instead, tell the user: +If the shell reports `command not found: parallel-cli`, stop and tell the user to run `/parallel-setup`, then retry their request. Do not substitute built-in search, another provider or an answer from memory. + +### Command and authentication failures + +`No such command`, `No such option` or `unrecognized arguments` from an installed CLI indicate a stale or mismatched interface. Check its version and upgrade through its installation method using `/parallel-setup`; `parallel-cli update` is for standalone installs only. Verify the required command in the same Cursor terminal before retrying. + +For authentication errors, run `parallel-cli auth --json` and inspect `authenticated`; exit zero alone does not prove authentication. Use `/parallel-setup` for terminal login or environment-key guidance, without requesting credentials in chat. A `403` can be an authorization or billing error: report the actual error and do not assume insufficient balance or add funds automatically. -1. `parallel-cli` is not installed -2. Run `/parallel-setup` to install it -3. Then retry their request +For other API/input errors, report the error without calling it a version problem. Reuse saved run IDs to resume asynchronous work. After an ambiguous creation failure, resolve whether a job exists before retrying creation.