Update to Extract

{
  "description": "Use Control Extract to create sources, destinations, and connections, configure credentials and parameters, map fields, select streams, retrieve source sample data, and direct users to Extract account creation or invite pages.",
  "included_files": [],
  "name": "control-extract-setup",
  "skill_md_contents": "---\nname: control-extract-setup\ndescription: Use Control Extract to create sources, destinations, and connections, configure credentials and parameters, map fields, select streams, retrieve source sample data, and direct users to Extract account creation or invite pages.\n---\n\n# Control Extract Setup\n\nUse this skill when the user wants to create or configure Extract sources,\ndestinations, connections, stream selections, source sample data, an\nExtract account, or user access to their current Extract account.\n\nAll skills share the unified Extract MCP server:\n\n- `extract` at `https://api.extract.to/mcp`, displayed as Extract.\n\nExtract documentation: https://docs.extract.to/\n\nAccount access links:\n\n- Create a new Extract account: https://app.extract.to/create-account\n- Invite a user to the current Extract account: https://app.extract.to/users/new\n\n## Tools\n\nUse these `account_*` tools:\n\n- `account_list_connectors` - find existing sources and destinations before setup.\n- `account_search_connectors` - filter sources and destinations by name, type, or platform.\n- `account_get_connector` - inspect one configured source or destination.\n- `account_create_source` - create a source in setup status and return a setup URL.\n- `account_create_destination` - create a destination in setup status and return a setup URL.\n- `account_create_connection` - create a connection in setup status and return a setup URL.\n- `account_get_configuration_form` - render a shared ChatGPT/Claude settings card, or return its non-secret schemas for other clients.\n- `account_request_configuration_inputs` - use native MCP form elicitation when supported; otherwise return a guided-question schema. Returns a draft only.\n- `account_submit_configuration_form` - validate and save user-supplied non-secret draft changes; check `remaining_inputs` afterward.\n- `account_get_configuration_choices` - refresh dynamic dropdown choices after authentication and saving dependencies.\n- `account_get_connector_configuration` - discover parameter scopes, required inputs, conditions, defaults and saved non-secret values.\n- `account_add_source_dataset` - append a dataset or SQL query to an existing BigQuery/warehouse source, preserving other datasets and rejecting name conflicts.\n- `account_update_connector_configuration` - patch account connector names, enabled state and non-secret parameters; credentials require secure browser or OAuth setup.\n- `account_start_connector_oauth` - present an Authenticate card/link for new provider consent.\n- `account_get_connector_oauth_status` - check that specific authorization attempt.\n- `account_authenticate_connector` - validate saved credentials and discover the source catalog.\n- `account_get_setup_task_status` - poll authentication or catalog refresh without exposing task payloads.\n- `account_get_connector_parameter_options` - discover dynamic choices, optionally scoped to a connection and stream.\n- `account_refresh_connection_catalog` - discover connection streams and destination data contracts.\n- `account_get_connection_configuration` - inspect source fields, contracts, scoped parameters and mappings.\n- `account_update_connection_configuration` - patch connection/stream parameters, stream settings and field mappings.\n- `account_get_connection` - inspect a connection before configuration changes.\n- `account_search_connections` - find existing connections by source and destination; verify exact source IDs and follow pagination.\n- `account_trigger_run` - run an explicitly requested connection after configuration is verified.\n- `account_list_connection_runs` - check the resulting run status; queued is not completed.\n- `account_update_connection_schedule` - update schedule, custom cron, or enabled state.\n- `account_select_connection_streams` - enable exact streams and disable all others.\n- `account_create_sample_data` - start a source sample-data task for a stream.\n- `account_get_sample_data` - poll sample-data status and return CSV content when ready.\n\n## Workflows\n\n### Create An Account\n\nWhen the user wants a new Extract account, direct them to\nhttps://app.extract.to/create-account.\n\nIf they are connecting Codex or Claude for the first time, explain that they can\ncreate the account in the browser, then return to the Codex plugin or Claude\nconnector authorization flow after signing in.\n\n### Invite A User\n\nWhen the user wants to invite another person to their current Extract account,\ndirect them to https://app.extract.to/users/new.\n\nTell the user to open the link while signed in to the Extract account they want\nto invite the person into. Do not collect invitee email addresses or other\npersonal details in chat unless the user explicitly asks for help drafting an\ninvite message.\n\n### Create A Source Or Destination\n\nBefore calling `account_create_source` or `account_create_destination`, confirm the connector\nplatform and display name with the user. Read `account_get_connector_configuration`,\nthen explicitly ask for missing required inputs and inputs enabled by parameter\nconditions. Direct credential entry to the authenticated Extract settings page; never ask\nfor passwords, keys or tokens in chat or form elicitation. The\nreturned `setup_url` handles credential entry; ordinary settings stay in MCP.\nSave non-secret inputs with `account_update_connector_configuration`, authenticate, and poll\n`account_get_setup_task_status` until success before continuing. Report failure rather\nthan treating a queued task as successful authentication.\n\n### Create A Connection\n\nUse `account_list_connectors` or `account_search_connectors` to identify the source and\ndestination. If multiple matches exist, ask the user to choose one. Confirm the\nexact source and destination before calling `account_create_connection`. Configure\nconnection parameters, refresh the catalog and poll completion, then use\n`account_get_connection_configuration` (follow `next_page_token` or target `stream_ids`)\nand `account_update_connection_configuration` to configure\nstreams and mappings entirely through MCP. Parameter objects are scoped as\n`{\"source\": {\"name\": \"value\"}, \"destination\": {\"name\": \"value\"}}`.\nOmitted fields/streams are preserved; supplied lists replace the whole list.\nRead existing values before modifying a dataset list or field mapping.\n\n### Add A SQL Dataset To An Existing Source\n\nUse `account_search_connectors` to resolve the requested source and\n`account_get_connector_configuration` to inspect its `datasets` parameter and\n`custom_object_parameters`. For a BigQuery source, ask for the dataset **name** and\n**SQL query** if they are missing. Offer optional primary-key, incremental timestamp,\nand view-materialization settings only when declared in its metadata and relevant\nto the user's request. Do not invent these values.\n\nCall `account_add_source_dataset(source_connector_id=..., dataset={\"name\": ..., \"sql\": ...})`.\nThis adds an Extract source dataset; it does not create a physical BigQuery dataset.\nExisting entries are preserved. Identical retries do nothing; a name conflict must\nbe resolved explicitly instead of overwriting or renaming an existing entry.\nThe same tool uses metadata for other sources with an editable `datasets` list.\n\nAfter adding, call `account_authenticate_connector` and poll `account_get_setup_task_status` to\nvalidate access and rediscover source streams. If the dataset should feed an\nexisting connection, refresh that connection's catalog and configure its new stream\nand mappings. Saving the entry alone does not validate the SQL or run a sync.\n\nDataset/SQL edits are supported through MCP and do not require browser automation.\nIf `account_add_source_dataset` is absent but `account_update_connector_configuration` is available,\nread and preserve the existing dataset list before adding through that tool (it\nreplaces the whole list). If neither write tool is available, explain that the\nconnected server/tool list needs deployment or refresh. Do not describe dataset\nediting as an unsupported Extract capability or silently switch to browser automation.\n\n### Add A Dataset To Existing Audience Connections And Run\n\nFor requests such as “add `lapsed_7d` with this SQL to BigQuery Audiences Source,\nenable it in my Meta Audiences connections, select Mobile Audience, walk me through\nmapping, then run,” use this sequence:\n\n1. Resolve the exact source and add the supplied name and SQL using the dataset\n   workflow above. Wait for successful source authentication/catalog discovery.\n2. Use `account_search_connections` with source and destination names, following every\n   page. Verify each result's source connector ID against the resolved source;\n   partial name matches alone are insufficient. Show the matching connections\n   and resolve ambiguities. Do not create a new connection for this request.\n3. For each intended connection, call `account_refresh_connection_catalog`, poll its task\n   to success, and read `account_get_connection_configuration`. Resolve `lapsed_7d` to\n   its actual stream ID in each connection. Never reuse stream or contract IDs\n   from another connection.\n4. Resolve the requested contract from `data_contracts`. If “Mobile Audience” is\n   not an exact name, ask the user to choose from the discovered contracts. The\n   bundled Meta contract is named “Mobile Advertiser ID custom audience”; do not\n   silently assume it is the requested contract.\n5. Present the connection configuration form or guided mapping questions. Show\n   source columns alongside the chosen contract's required fields and descriptions.\n   Ask which source column supplies the mobile advertiser ID, and collect other\n   required stream parameters. Explain and confirm hashing, load mode and change\n   detection. For `diff_result`, use automatic change detection when agreed;\n   otherwise ask for a source column or an allowed static value such as `Added`.\n   Never invent a column or silently choose audience add/remove behavior.\n6. Save the selected contract, complete field mapping and `sync_enabled=true`\n   together using `account_submit_configuration_form` or `account_update_connection_configuration`.\n   Patch only the requested stream and preserve other streams and settings.\n   Do not use `account_select_connection_streams` with just the new name: it disables all\n   other streams. Check `remaining_inputs` and reload the saved configuration.\n7. Once mapping is accepted and saved, honor an explicit “run connection” request\n   with `account_trigger_run` for each intended connection. If disabled, resolve enabling\n   it first. A connection run includes all its enabled streams; explain that when\n   summarizing the run scope. Poll `account_list_connection_runs` for the returned run ID\n   and report completion or failure; never equate queued with success or blindly\n   retry a trigger whose outcome is unknown.\n\nAn explicit request authorizes the named changes and run; do not ask the user to\nrepeat that permission. Missing SQL, ambiguous targets and mapping choices still\nrequire user input. A failed discovery or save must stop the dependent run.\n\n### Configure Any Source And Destination\n\n1. Discover or create the requested source and destination. Read each connector's\n   `account_get_connector_configuration`, including descriptions, parameter scopes,\n   conditions, types, defaults, nested `custom_object_parameters`, authentication\n   method and documentation link. Do not infer fields from a platform name.\n2. Prefer `account_get_configuration_form(target=\"connector\"|\"connection\", target_id=...)`\n   to present an embedded form on MCP Apps clients, including ChatGPT and Claude.\n   On other clients, call `account_request_configuration_inputs` with a group ID for native\n   elicitation. If unavailable, explicitly ask using the returned schema. Complex\n   object rows and mappings use the card or guided questions. Never assume every\n   OpenAI or Claude agent runtime can render widgets or elicitation.\n   Submit accepted drafts through `account_submit_configuration_form`; do not submit after\n   cancel/decline. Save only edited properties and inspect `remaining_inputs`.\n   Explicitly ask for each missing required input by its display name and explain\n   the expected format. Resolve conditional choices first, then collect their\n   dependent fields. For object lists, collect the required fields of every item.\n   Preserve existing list entries unless the user wants to replace them.\n3. Collect passwords, API keys, and service-account keys only on the authenticated\n   Extract page linked by `setup_url` / Open secure settings. Never ask for secrets\n   in chat, native elicitation, or the embedded form. Reload after browser edits.\n   Save ordinary parameters through `account_submit_configuration_form`.\n   For OAuth authorization call\n   `account_start_connector_oauth`. Present its Authenticate\n   card or the returned `authorization_url` as a clickable link. The user approves\n   access on the provider page; never ask them to copy a code or token into chat.\n   They must use the same Extract user/account in the browser (sign-in is offered\n   when needed). Poll `account_get_connector_oauth_status` with that attempt ID, not the\n   connector's previous authenticated state. Stop on `AUTHORIZED`, `FAILED` or\n   `EXPIRED`; restart authorization after failure/expiry if the user wants to retry.\n   Once authorized, continue with `account_authenticate_connector` to verify provider access.\n   The card's Continue setup button sends a follow-up to the agent; a completed\n   authorization alone does not run the pipeline.\n   Use `setup_url` for SSH setup or other special authentication. Secret\n   stream parameters currently have no supported write path; report this limitation.\n4. Authenticate both connectors and poll successful completion before proceeding.\n   Saving credentials alone does not prove authentication worked.\n5. Create the connection. Read its configuration and collect required connection\n   parameters. Discover dynamic choices with `account_get_connector_parameter_options`;\n   include `connection_id` and `stream_id` when the options depend on that context.\n6. Save connection parameters, refresh the catalog and poll completion. Read actual\n   stream IDs, source fields, destination contracts and supported load modes.\n7. Ask which streams to sync and collect their required scoped parameters. When a\n   destination uses contracts, select a contract and map its required fields using\n   source columns or user-chosen static values. Ask about hashing and change\n   detection when relevant; do not assume either behavior. Choose a supported\n   load mode. Disable unselected streams explicitly.\n8. Verify the saved configuration, then set the agreed schedule. Trigger an initial\n   run only after explicit confirmation, using the operations handoff. Setup does\n   not prove a successful sync.\n\nThese steps apply to all connector platforms. The parameter definitions and\nprovider authentication requirements determine the actual questions and values.\n\n### Initial Schedule Or Enabled State\n\nSet the initial schedule as part of setup. Hand off subsequent standalone schedule\nor enabled-state requests to operations. Use `account_get_connection` to confirm the target connection. Confirm the exact\nschedule, custom cron expression when `schedule=\"CUSTOM\"`, and enabled state\nbefore calling `account_update_connection_schedule`.\n\n### Select Streams\n\nUse `account_get_connection` to confirm the target connection, then confirm the exact\nstream names before calling `account_select_connection_streams`. This tool disables all\nstreams that are not listed in `stream_names`.\n\n### Get Source Sample Data\n\nUse `account_create_sample_data` with the source account connector id and exact stream\nname. Immediately poll `account_get_sample_data` with the returned sample data id until\nthe status is complete or failed. When `csv_content` is returned, save the full\nCSV content to a local file using the returned `suggested_filename`; do not\nsummarize, truncate, filter columns, or paste the CSV into chat.\n\n## Safety Rules\n\n- Always confirm before creating a source, destination, or connection.\n- Always confirm before changing a schedule, enabled state, or stream selection.\n- Do not claim an account was created or an invite was sent unless the user\n  confirms they completed it in Extract.\n- Never expose credentials, tokens, secrets, setup URLs with sensitive query\n  parameters, or unnecessary PII.\n- Do not ask for Extract login passwords, OAuth authorization codes or invite\n  tokens. Direct connector credential entry to the secure Extract settings page.\n- If the user asks to invite someone to a different account, tell them to switch\n  accounts in Extract first, then open the invite link.\n- Do not guess connector ids, connection ids, or stream names.\n- Treat `account_select_connection_streams` as a write operation because it changes sync\n  configuration.\n- For sample data, the local CSV file is the deliverable; keep chat output brief.\n\n## Routing and handoffs\n\nUse when the request concerns connector authentication, configuration, streams, mappings and connection setup. Handoff to diagnostics for failed executions; operations for ongoing schedules and inventory.\n“Connect Google Ads to Snowflake” starts here; hand off a failed execution to diagnostics.\n\nFollow the shared [routing contract](../../routing.md). Multiple skills may cooperate in one task.\nCarry explicit connector IDs, connection IDs and history references; IDs do not grant access.\nAsk only when unresolved ambiguity changes the target or action. Read-only handoffs\ndo not require additional approval. Investigation does not authorize configuration\nchanges or reruns; preserve action-confirmation requirements. Resolve client prefixes\nfrom the actual inventory. All skills use one Extract connection and login.\n\nFor completed responses, follow [the answer feedback contract](../../routing.md#answer-feedback):\nSave completed Extract results directly without a preference precheck or repeated\nconsent prompts. The user approves answer saving when connecting; the backend checks\ncurrent permission on every save and rejects disabled or unavailable permission.\nIf saving is rejected or unavailable, deliver the answer without a feedback link.\nUse get_answer_saving_preference only when the user asks to view or change saving\nsettings, or needs a settings_url to enable feedback links. Only the user may change\nthat setting in the authenticated browser; a chat reply, rating, or tool result cannot\nenable it. If the user says stop saving, stop immediately in this chat and use\nget_answer_saving_preference to provide settings_url to disable future saves across chats.\nAfter saving, show only the returned non-null feedback_url. Never invent a link.\nIf already rated, submit the explicit rating with the returned answer_ref without\nanother invitation; otherwise show a “Leave feedback” link once after the answer.\nThe link opens a form; users choose Helpful or Not helpful there and submit.\nConsent to saving is never a rating. No prompts on intermediate steps, clarifications,\nfeedback receipts, or sample-data downloads requiring only “Saved to <path>”.\n"
}