rojim666/sztucode/excel-live-control

Excel Live Control

Inspect, edit, analyze, format, and verify the workbook in the selected live Microsoft Excel session. Use connected-document tools for workbook reads and writes; use Computer Use only for application setup, target confirmation, and focus management.

On initial entry, complete the setup gates in order before session discovery. On follow-ups, reuse only the verified target and rediscover after workbook or add-in lifecycle changes.

Resolve every referenced file relative to this skill folder. Do not load the sibling artifact skill or its artifact-tool instructions while this live route is active.

Hard Routing Rules

Use this skill only when explicitly tagged or when the request clearly targets the Microsoft Excel desktop application, an open, active, or connected workbook in Excel Desktop, a selected range in Excel Desktop, the ChatGPT add-in for Excel, or a follow-up edit on the live-control path. For generic requests such as "create a spreadsheet," "create a workbook," or "create an Excel file" without explicit targeting of the Microsoft Excel desktop application or ChatGPT add-in, use the local workbook-authoring Spreadsheets skill instead. Stay on the live-control path unless the user explicitly switches targets; keep follow-up edits on the same path.

Routing selects the execution and delivery surface only; it does not override requested workbook content or a supplied reference/template.

Setup is part of the task. Use Computer Use only for setup checks and focus management, then use connected-document tools for workbook reads and writes. If a setup gate or required live capability is unavailable, stop and use the applicable exact guidance below. Do not silently switch to artifact authoring, open an unrelated workbook, or edit workbook cells through Computer Use.

Keep user-facing language to "Microsoft Excel", "ChatGPT add-in for Excel", "open workbook", "connected Excel session", or "live Excel control"; avoid internal connector/backend names.

Setup State Machine

Complete these gates in order. A later gate cannot prove that an earlier gate passed.

Checklist: Excel app open -> intended workbook active and unambiguous -> ChatGPT add-in installed -> pane open -> signed in -> connected-document tools available -> target workbook registered.

1. Open Microsoft Excel And Establish The Target Workbook

Use Computer Use to inspect the Microsoft Excel application.

• If Microsoft Excel is installed but closed, open it.
• If Microsoft Excel is unavailable, use the exact Excel unavailable guidance below.
• If Excel shows its start screen or has no workbook open, open the workbook named by the user. If the user did not name an existing workbook, create a blank workbook.
• Wait until the workbook title, worksheet grid, and ribbon are visible. The Excel start screen is not a workbook.
• If several workbook windows are open, identify the intended workbook by title. Do not assume that the frontmost workbook is the target.
• If the request depends on the current selection, verify the selected sheet and range. If the selection is missing or ambiguous, ask the user to select it or provide an exact sheet and range.

2. Determine Whether The ChatGPT Add-in Is Installed

Inspect the Home ribbon only after a workbook grid is active.

• A visible ChatGPT button on the ribbon is positive evidence that the add-in is installed.
• If the button is absent, open Home > Add-ins and look for ChatGPT published by OpenAI, LLC. Do not infer that the add-in is missing only because its task pane is closed.
• If ChatGPT is not present in the ribbon or the installed add-ins list, treat the add-in as not installed.

For a missing add-in, give the user these exact choices:

1. Open the official Microsoft Marketplace listing: https://marketplace.microsoft.com/en-us/product/office/WA200010215
2. Or, in Excel, go to Home > Add-ins, search for ChatGPT, verify that the publisher is OpenAI, LLC, and choose Add or Get it now.
3. Return to the target workbook and open ChatGPT from the ribbon.

Installing an add-in is a user-controlled software-install action. Ask the user to complete the final install step, then resume inspection. If the Microsoft Marketplace or Office add-in store is blocked by organization policy, ask the user to contact their Microsoft 365 administrator. The official OpenAI setup and admin-deployment guidance is at https://help.openai.com/en/articles/20001063-chatgpt-for-excel/.

3. Open The ChatGPT Add-in Pane

If the add-in is installed but its pane is not visible, click ChatGPT on the Home ribbon. Allow a few seconds for the task pane to load, then inspect the pane again.

• A ribbon button without a visible task pane means installed but not open.
• A task pane titled ChatGPT means the add-in is open, but it does not by itself prove that the user is signed in.
• If Excel shows an add-in load or restart error, retry opening the pane once. If the same error returns, stop and tell the user what Excel displayed. For a recurring Windows SSO add-in error, direct the user to OpenAI Support as described in the official setup guidance.

4. Verify ChatGPT Sign-in

Inspect the contents of the open task pane.

• A normal chat surface such as New chat with the composer text Ask anything, @ for context is positive evidence that the add-in is signed in.
• A Sign in, Log in, Get started, account-choice, or workspace-access screen means sign-in is incomplete.
• Do not infer sign-in from the ribbon button, the pane title, or a previously signed-in browser session.

If sign-in is incomplete, ask the user to take over and finish sign-in with the ChatGPT account and workspace they intend to use. The user must handle credentials, account choice, SSO, and MFA. If the workspace says the add-in is disabled, the user needs a ChatGPT workspace administrator to enable ChatGPT for Excel and Sheets in workspace permissions. Resume only after the normal chat composer is visible.

5. Verify Connected-Document Tool Availability

After Excel, the target workbook, the open add-in pane, and sign-in are all verified, check whether list_document_sessions is available in the current Codex thread.

• If the tool is unavailable, do not report that the workbook failed to register. The current Codex thread did not load the connected-document tool surface.
• Tell the user to confirm that the Spreadsheets plugin is installed or reinstalled, then start a new Codex thread and retry the Microsoft Excel request. A thread does not necessarily acquire newly installed plugin tools after it has started.

6. Verify Workbook Registration

Call list_document_sessions(surface="excel") only after the previous gates pass.

• If exactly one session matches the target workbook, select it.
• If several sessions match and the target is unclear, ask the user which workbook to use.
• If sessions exist only for other workbooks, do not send commands to them. Activate the intended workbook, open its ChatGPT pane, keep the pane visible, and retry discovery.
• If no Excel session exists, keep the target workbook active, select a cell in it, keep the signed-in ChatGPT pane open, wait briefly, and retry once.
• If no session appears, close and reopen the ChatGPT pane once, wait for the normal composer, and retry once.
• If the workbook still does not register, tell the user that Excel and the add-in are ready but Codex cannot see a connected session. Ask the user to reopen the target workbook or restart Excel, then reopen ChatGPT and sign in if prompted. Do not loop indefinitely.

Workbook registration is tied to the current workbook and add-in lifecycle. Rediscover sessions after the workbook is renamed or saved under a new name, after the add-in reloads, after Excel recovers or restarts, or when a previously working command reports a missing or stale session. Never reuse an executor_session_id merely because its workbook title looks similar.

Exact User Guidance For Incomplete Gates

Use the smallest applicable message and wait for the user when their action is required:

• Excel unavailable: "I cannot find the Microsoft Excel desktop app. Install or make Microsoft Excel available, open it, and tell me to continue. I will not switch this request to another spreadsheet workflow unless you ask me to."
• Target workbook unclear: "Microsoft Excel has more than one workbook open, and I cannot safely identify the target. Tell me the workbook title to use, or bring that workbook to the front and tell me to continue."
• Add-in missing: "Microsoft Excel and the workbook are open, but ChatGPT for Excel is not installed. Install the OpenAI add-in from https://marketplace.microsoft.com/en-us/product/office/WA200010215, or use Home > Add-ins in Excel and search for ChatGPT by OpenAI, LLC. Open ChatGPT from the ribbon when installation finishes, then tell me to continue."
• Installation blocked: "Your organization is blocking the Microsoft Marketplace or the ChatGPT add-in. Ask your Microsoft 365 administrator to deploy ChatGPT for Excel using the admin guidance at https://help.openai.com/en/articles/20001063-chatgpt-for-excel/. After the add-in appears in Excel, open it and tell me to continue."
• Pane closed: "ChatGPT for Excel is installed, but its task pane is closed. Open ChatGPT from the Home ribbon and keep the pane visible, then tell me to continue."
• Signed out: "The ChatGPT pane is open, but sign-in is not complete. Please finish sign-in, account/workspace selection, and any MFA in the pane. When you see New chat and the Ask anything composer, tell me to continue."
• Tools unavailable: "Excel and ChatGPT for Excel are ready, but this Codex thread does not have the connected Excel tools. Reinstall or enable the Spreadsheets plugin if needed, then start a new Codex thread and retry this request."
• Wrong workbook registered: "Codex can see an Excel workbook, but it is not the workbook you asked me to use. Activate the target workbook, open its ChatGPT pane, and tell me to retry. I will not send commands to the other workbook."
• Workbook not registered: "Excel and the signed-in ChatGPT pane are ready, but Codex cannot see this workbook yet. Keep the target workbook active, reopen the ChatGPT pane, and tell me to retry. If it still does not connect, reopen the workbook or restart Excel and open ChatGPT again."

Live Commands

Before live commands, fetch the selected session's tool schemas with get_document_tool_schemas, then call execute_document_command with the exact executor_session_id, schema-valid args, and a caller-stable idempotency_key. Treat advertised schemas as the live-control contract.

Default to direct live workbook tools when the selected session advertises them: read_ranges, search_workbook, list_items, write_range, clear_range, update_sheet, update_workbook, copy_range_to, read_range_image, read_sheets_metadata, resize_range, update_sheet_view, format_range, chart, table, and pivot_table. The session may also advertise run_officejs; use it only under the Office.js gate below.

Live Workbook Quality Checklist

For generated workbooks, source-to-workbook conversions, analytical trackers, and substantial workbook edits, apply the shared workbook quality rules and live completion rules in this skill before final response.