Add parallel-develop skill for bootstrapping integrations#14
Draft
NormallyGaussian wants to merge 5 commits intomainfrom
Draft
Add parallel-develop skill for bootstrapping integrations#14NormallyGaussian wants to merge 5 commits intomainfrom
NormallyGaussian wants to merge 5 commits intomainfrom
Conversation
Mirrors the /onboarding-guest landing-page experience as a user-invocable skill: when a user says "integrate Parallel" / "add Parallel to my app", the agent picks the matching API (Search / Task / FindAll / Monitor / Extract) and client (Python / TypeScript / cURL / MCP), then emits install + env + a working code example with best-practice comments inline. Structure (progressive disclosure per the Agent Skills spec): - SKILL.md (71 lines): decision table, guardrails, and routing to a per-client recipe file. - references/python.md: client.search, client.task_run (research + enrichment), client.beta.findall, client.extract, and an httpx fallback for the alpha Monitor API. - references/typescript.md: same surface, with explicit guardrails that the TS SDK uses snake_case body fields (task_spec, output_schema, run_id) and a tsconfig note for the private-field lib-check issue. - references/curl.md: raw HTTP equivalents with the correct endpoint versions (v1, v1beta, v1alpha). - references/mcp.md: Claude Code / Cursor / VS Code / Claude Desktop configs for the hosted Search + Task MCP servers, including the macOS Claude Desktop gotchas (env inheritance, npx PATH, relaunch). Complements, rather than replaces, the existing runtime skills (parallel-web-search, parallel-deep-research, parallel-data-enrichment, parallel-web-extract): those invoke parallel-cli to get work done now; this one writes code the user will ship. Bumps plugin + marketplace version to 0.3.0.
Follow-up from eval feedback: - Python recipe now pins 'parallel-web>=0.5,<1.0' (both evals hit install friction without a pin). - TS recipe pins 'parallel-web@^0.4' with a response-shape cheat-sheet. - Python recipe documents how to import APIError/RateLimitError and the optional TaskSpecParam/JsonSchemaParam TypedDicts for strict pyright. - Documents result.output.content shape (flagged as a guess by both evals). - Adds a Task Group batch-enrichment snippet for the 50+ row case.
The hosted Search MCP is launching at search.parallel.ai/mcp rather than search-mcp.parallel.ai/mcp. Updated all references in the MCP recipe: remote URL configs for Cursor / VS Code / Claude Desktop, the Claude Code CLI install commands, and the programmatic Bearer-token example.
Pulled concrete, often counterintuitive guidance from the dedicated docs
pages into the SKILL.md guardrails and the per-language recipes, with
deep-dive links in each API section rather than paraphrasing.
Highlights:
- Task output schemas: every property must be in 'required', use
{type: ['string','null']} union for optional fields, always set
additionalProperties: false, root must be type: object.
- FindAll: if you get 0 matches, UPGRADE the generator before rewriting
the query — issue is usually pool size, not query quality. Match
generator to expected volume (base/core/pro guidance).
- Search / Extract: session_id groups related calls, client_model
enables server-side optimization for the consuming LLM. Expose only
objective + search_queries as LLM tool params.
- Extract: warning that full_content without objective is redundant.
- Added a 'Canonical best-practice pages' block in SKILL.md linking to
Search/Extract/Task/FindAll/MCP best-practice docs.
Most MCP clients (Claude Code, Claude Desktop Connectors UI, Cursor, VS Code, Windsurf, Cline) just need the URL — OAuth handles auth on first use. Previous recipe led with the mcp-remote stdio bridge + inline API key + Claude Desktop shell-env gotchas, which only apply to older clients without remote-HTTP support. Now: - URL-first, one config block per client, tiny snippets - mcp-remote bridge demoted to a 'Stdio fallback' section at the bottom - Per-client quirks captured in one line each (Windsurf uses serverUrl, Cline needs type=streamableHttp, VS Code wraps in mcp.servers) - Points at docs.parallel.ai/integrations/mcp/search-mcp for any client not listed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new user-invocable skill
parallel-developthat helps an agent bootstrap a Parallel API integration in the user's codebase — mirroring the experience of the/onboarding-guestlanding page on platform.parallel.ai, but available inside any MCP-compatible agent (Claude Code, Cursor, Codex, etc.).When a user types
/parallel:parallel-develop <intent>, the agent:What's in the box
skills/parallel-develop/SKILL.mdskills/parallel-develop/references/python.mdparallel-webSDK recipes (Search, Task, enrichment, FindAll, Extract, Monitor via httpx)skills/parallel-develop/references/typescript.mdtask_spec,output_schema,json_schema,run_id). Also covers the#private-field tsconfig issue.skills/parallel-develop/references/curl.mdskills/parallel-develop/references/mcp.md.claude-plugin/plugin.json,.claude-plugin/marketplace.jsonREADME.mdHow it relates to existing skills
The existing skills (
parallel-web-search,parallel-deep-research,parallel-data-enrichment,parallel-web-extract) are runtime — they invokeparallel-clito get work done right now.parallel-developis for the build-and-ship case — when the user is adding Parallel to their own codebase and wants starter code they can commit. The SKILL.md body explicitly disambiguates between the two.How this was validated
docs.parallel.ai— verified every endpoint path, SDK method surface, processor/generator enum, and MCP URL.py_compile. Reports used to iterate on recipe clarity.Test plan