Add retool-import skill content#2
Draft
rsuresh-retool wants to merge 1 commit into
Draft
Conversation
Adds the actual retool-import plugin to the marketplace:
- plugin.json manifest
- SKILL.md: local state machine (recon -> discovery -> matching -> HITL
-> cleaned tree + partial IMPORT_PLAN.md -> handoff via
retool_submit_prepared_import MCP tool)
- agents/discovery-subagent.md: parent-pasted subagent brief for
Phase 2 vendor-agnostic discovery fan-out
- references/IMPORT_PLAN.template.md: template the skill fills in
- references/filter-constants.ts: duplicated zip filter from
retool_development/packages/common/retoolReactAgent/
Discovery is LLM-driven against a closed category taxonomy with vendor
as a free-text string - no vendor-specific code paths. The skill must
work on any React app, not just Lovable + Supabase.
Bumps retool-import marketplace version from 0.1.0 to 0.2.0 so existing
installs pull the new contents.
9 tasks
justinpchen94
approved these changes
May 20, 2026
justinpchen94
left a comment
justinpchen94
left a comment
There was a problem hiding this comment.
thanks for doing all this! unblocking approval but there's a lot of open questions from me on this first pass
| { | ||
| "name": "retool-import", | ||
| "version": "0.1.0", | ||
| "description": "Import an existing React app into Retool as an R^2 app. Discovers external services in your repo, matches them against your Retool resources, and hands a prepared import plan to Retool's R^2 sandbox agent.", |
There was a problem hiding this comment.
im gonna start an R2 swear jar 😈
| @@ -0,0 +1,81 @@ | |||
| # Discovery subagent brief | |||
|
|
|||
| The Phase 2 parent agent dispatches one subagent per cluster of files. Paste this entire brief verbatim into each dispatched subagent's prompt, filling the `Scope:` and `Question:` slots. Do NOT omit any slot. | |||
There was a problem hiding this comment.
this seems a little odd to be the instruction we tell a subagent. i don't think this is meant to be written as if a human were going to read this?
| Run all four heuristics across every file in scope. A single file can match multiple heuristics — record the strongest evidence, not all of it. | ||
|
|
||
| 1. **Third-party package imports.** Look at `import ... from '<package>'` statements. If the package name looks like a service SDK (cloud provider, BaaS, ORM, payments processor, observability tool, etc.), classify it by the role its API plays in the file — not by a list of known vendors. Examples of the kind of judgment to make: a package whose top-level export creates a database client → category `database`; a package whose API revolves around `signIn` / `getUser` / `onAuthStateChange` → category `auth`; a package whose API revolves around uploading files / returning signed URLs → category `object_storage`. | ||
| 2. **Env var references.** Look for `process.env.X` / `import.meta.env.X` / Vite-style `VITE_X` references. Names like `*_URL`, `*_API_KEY`, `*_SECRET`, `DATABASE_URL`, `*_PROJECT_ID` signal an external service. Cross-reference with `.env.example` at the repo root (NEVER read `.env` or `.env.local`). The variable name often discloses the vendor (`SUPABASE_URL`, `FIREBASE_API_KEY`, `STRIPE_SECRET_KEY`) — use that as the vendor string. |
There was a problem hiding this comment.
nit: .env.example always exists beacuse this is lovable specific?
| @@ -0,0 +1,119 @@ | |||
| // Mirrors retool_development/packages/common/retoolReactAgent/appImportFileFilters.ts | |||
| '.toml', | ||
| '.yaml', | ||
| '.yml', | ||
| '.svg', |
|
|
||
| ### 5b. Partial IMPORT_PLAN.md | ||
|
|
||
| Start from `references/IMPORT_PLAN.template.md`. Fill in every section the local skill can confidently populate; leave a `<!-- TODO: R2 fills this in -->` marker in sections it cannot. |
| - **Open questions / known gaps** — populate with: every `category=unknown` service, every service for which the user picked `USE_MOCK_DATA`, the matcher's name+type-only limitation, any prerequisite-check soft warnings. | ||
| - **Phased build order** — leave the TODO marker. | ||
|
|
||
| Do NOT fill sections you cannot fill confidently. R2 expects to see the TODO markers and treats them as work assignments. |
| ## Hard rules / safety | ||
|
|
||
| - Never write outside the user's repo without asking. The skill's only outputs are the in-terminal prompts and the `retool_submit_prepared_import` MCP tool call. | ||
| - Never read `.env` or `.env.local`. Only `.env.example` is safe. |
There was a problem hiding this comment.
this instruction has appeared a few times and im not super confident in this being exhaustive but sh🤷♂️
| - Never write outside the user's repo without asking. The skill's only outputs are the in-terminal prompts and the `retool_submit_prepared_import` MCP tool call. | ||
| - Never read `.env` or `.env.local`. Only `.env.example` is safe. | ||
| - If discovery finds a service the user did not acknowledge in Phase 4, do NOT silently skip — surface it as an open question in the plan. | ||
| - If `retool_submit_prepared_import` is not available as an MCP tool, stop at Phase 5 and tell the user to enable `mcpServerRetoolImportEnabled` for their org. |
There was a problem hiding this comment.
shouldn't we do this earlier and save tokens?
|
|
||
| ## Summary for the user | ||
|
|
||
| This skill recons your React repo, fans out parallel discovery subagents to find every external service your code talks to (databases, auth, storage, realtime, HTTP APIs, payments, etc.), looks up matching Retool resources for each one, asks you to pick the right resource (or `USE_MOCK_DATA`) per service in the terminal, packages your source tree with secrets and large files stripped out, builds a partially-populated `IMPORT_PLAN.md`, and hands it all to Retool's R^2 sandbox agent. R^2 finishes classification and execution; you end up with a working Retool app whose editor URL is printed at the end. |
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
2 participants
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 the actual
retool-importplugin to the marketplace scaffolded in #1. The plugin teaches Claude Code how to run the local side of the React-app-import-via-MCP flow: recon → vendor-agnostic discovery → resource matching → in-terminal HITL → cleaned source tree + partialIMPORT_PLAN.md→ handoff to Retool's R^2 sandbox agent via the newretool_submit_prepared_importMCP tool (retool_development#77325).Stacked on top of #1.
What's in here
plugins/retool-import/.claude-plugin/plugin.jsonplugins/retool-import/skills/retool-import/SKILL.md(263 lines)plugins/retool-import/agents/discovery-subagent.md(81 lines)database/auth/object_storage/realtime/http_api/email/sms/payments/queue/analytics/search/ai/unknown). Vendor is a free-text string the subagent fills in.plugins/retool-import/references/IMPORT_PLAN.template.md(78 lines)<plan_state>status=prepared_by_mcp</plan_state>at the top and<!-- TODO: R2 fills this in -->markers in sections R2 owns (Source → target mappingclasscolumn, Backend functions to author, Phased build order, etc.).plugins/retool-import/references/filter-constants.ts(119 lines)retool_development/packages/common/retoolReactAgent/appImportFileFilters.ts+ size caps fromappImportLimits.ts. Skill uses these to produce the cleaned source tree before handoff. Top-of-file comment points at the canonical location..claude-plugin/marketplace.json0.1.0→0.2.0so existing installs pick up the contents.Design rails worth noting
vendorfield and the resource matches. If we ever feel a pull toward "let's add a Supabase-specific branch," that's a smell.USE_MOCK_DATAas a first-class option, plus a free-text path for "pick a different resource."retool_get_resource_match_metadatatool (A5/A6) was deferred — the SKILL.md surfaces this limitation honestly to the user rather than pretending the matcher knows more than it does.Data needs (resolved)+External services (resolved)split mirrors R2's Phase 2 axes (which the local skill is effectively producing). R2's Phase M (added in retool_development#77302) explicitly tells Phase 4 not to re-author these tables, so the structure passes through unchanged to Phase 5. If E2E surfaces an issue, we can collapse into a single section.authandrealtimedon't map cleanly to any Retool resource type today. The SKILL.md surfaces them in HITL anyway and expectsUSE_MOCK_DATAor a user-supplied resource as the resolution.retool_developmentdirectly. The file header comment pins the canonical location so we can keep them in sync.Validation
python3 -m json.toolparsesplugin.jsonandmarketplace.jsoncleanly.diffconfirmsfilter-constants.tsis byte-identical to the canonical source on every constant + helper function, minus a non-load-bearing module-header comment that doesn't apply once the constants are merged into a single duplicate file.claude plugin validatenot run here; recommend running locally before merge.Follow-up
Pre-flight checks in the SKILL.md fail gracefully if
retool_submit_prepared_importisn't visible (i.e., the user's org doesn't havemcpServerRetoolImportEnabledon). The skill will tell the user to ask their Retool admin to enable the flag rather than silently producing nothing.🤖 Generated with Claude Code