/field-service-data-capture-form-editor-configure

name: field-service-data-capture-form-editor-configure
description: "Patch an existing Data Capture Flow that's already deployed in a connected Salesforce org. Retrieves the live Flow Metadata JSON via the Tooling API, applies the user's requested change, and PATCHes it back. Use when the user names an existing flow and asks to add/remove/rename a field, change visibility, fix a bug, add visual polish, or swap a placeholder for a real component ('add a Notes field to Inventory_Transfer', 'fix the visibility rule on Work_Order_Number', 'make the parts repeater optional', 'replace the Signature placeholder with the real dcSignature component'). Do NOT use this skill to build a brand-new flow — that's fs-data-capture-form-designer followed by fs-data-capture-form-deployer."
user-invocable: false
metadata:
  version: "1.0"
  domains: ["Field Service"]

Edit a Data Capture Form (in an org)

This skill patches a flow that already exists in a connected org. The source of truth is the deployed flow's `Metadata` JSON, retrieved live from the Tooling `Flow` sObject — there is no spec file, no `.flow-meta.xml`, no zip, no SFDX project. The skill retrieves the JSON, edits it in memory, and PATCHes it back.

> **Runtime contract:** every org interaction in this skill is a REST call > dispatched through the Codey runtime (`dispatch` locally / the hosted > Headless 360 MCP in shared surfaces). This skill has **no dependency on the > execution environment** — no `sf` CLI, no local Python, no temp files, no > scratch SFDX project. Auth probes, the flow retrieve, and the redeploy are > single REST calls; the JSON patch is authored by the agent inline. Do not > shell out.

When this skill fires

• The user names an existing flow (`Inventory_Transfer`, `Asset_Inspection`, etc.) and asks for a change.
• The user pastes a Flow Builder URL and asks for a change.
• The user describes a deploy error or runtime bug in a deployed flow.

If the user is starting from scratch (prose, PDF, image), route to a `design-*` skill instead.

Workflow

1. Verify org auth

Confirm the connected org is reachable with a cheap auth probe — dispatch `SELECT Id FROM Organization LIMIT 1` (`GET /services/data/vXX.0/query`):

• 2xx with `totalSize=1` → the session token is live; continue.
• 401/403 → the org needs re-authentication. Surface that to the user and **stop**. (The Codey runtime resolves and refreshes the connected org — this skill does not manage org aliases.)

2. Retrieve the live flow's Metadata JSON

The Tooling `Flow` sObject exposes the flow definition as a JSON `Metadata` field — the same shape the deployer assembles and POSTs. Retrieving is a two-call round-trip, no CLI and no file:

1. **Resolve the latest version id from the API name.** Dispatch `GET /services/data/vXX.0/tooling/query` with:

   SELECT Id, ActiveVersionId, LatestVersionId FROM FlowDefinition WHERE DeveloperName = '<FlowApiName>'

Edit the **latest** version (`LatestVersionId`) so the patch builds on the newest draft, not a stale active version. If `LatestVersionId` is null, fall back to `ActiveVersionId`.

2. **Read the Metadata blob.** Dispatch `GET /services/data/vXX.0/tooling/sobjects/Flow/<versionId>` and take the `Metadata` object from the response. This JSON is the flow — screens, choices, decisions, variables, and the post-screen chain. See [../fs-data-capture-form-deployer/reference/flow-metadata-json.md](../fs-data-capture-form-deployer/reference/flow-metadata-json.md) for the shape.

If the FlowDefinition query returns zero rows, the API name is wrong or the user is pointed at the wrong org. Confirm with the user before retrying. List the candidate flows in the org if useful — dispatch `GET /services/data/vXX.0/tooling/query` with `SELECT DeveloperName FROM FlowDefinition ORDER BY DeveloperName`.

3. Read the retrieved Metadata JSON and the rule sheet

Before patching, **read** the retrieved `Metadata` JSON to understand the current structure, then read [fs-data-capture-reference/SKILL.md](../fs-data-capture-reference/SKILL.md) for the platform's hard constraints. The constraints are identical whether the flow is expressed as XML or JSON — a repeated XML element is a JSON array, so "grouping" becomes "the array" (see the JSON↔XML mapping rule in [../fs-data-capture-form-deployer/reference/flow-metadata-json.md](../fs-data-capture-form-deployer/reference/flow-metadata-json.md)). Pay particular attention to:

• **Element arrays**: `screens`, `choices`, `decisions`, `recordLookups`, `recordCreates`, `recordUpdates`, `loops`, `assignments`, `variables` are each a single JSON array. Add a new element by appending to the right array — never introduce a duplicate top-level key.
• **CUD ordering**: no record-lookup or screen after any CUD (recordCreate/recordUpdate/recordDelete) in the connector chain. No decision between sequential CUDs.
• **`.AllItems` vs `.AddedItems` Repeater accessor** — use what the deployed flow uses, don't change it.
• **Visibility rules**: in a `visibilityRule.conditions` entry, `leftValueReference` is the *choice* api-name, not the parent field's name.
• **Required-field behind visibility-rule** anti-pattern (see `fs-data-capture-reference` SKILL.md).
• **`isLlmTargetable`**: carried as a `{ "stringValue": "true" }`-style wrapper, not a raw JSON boolean — match whatever the retrieved flow uses.

The prohibited-patterns table at the bottom of [fs-data-capture-reference/SKILL.md](../fs-data-capture-reference/SKILL.md) is the fastest reference for "what would break this patch".

4. Plan the patch and confirm with the user

Before editing, tell the user:

1. **What you're going to change** — specific element, specific lines (cite `path:line` references), and what the result will look like. 2. **Whether the change requires schema reordering** — e.g. adding a new `<recordLookups>` element when none exist requires placing it in the right group. Call this out. 3. **Activatio