按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Automation: Sandbox Post-Copy Configure、Tool Restrictions、STOP — do this before making any API call、Per-entry procedure (the core of this skill)、Step A — Resolve the Tooling API sobject and lookup filter、Step B — Verify the candidate exists and supports Metadata writes。 其中含规范建议的小节:分步指令。
Apply a Salesforce sandbox post-copy automation JSON config against a target org. For each entry, the skill derives the correct Tooling API sobject from the entry's `ConfigurationName`, verifies the derivation via a describe probe, resolves the record Id via SOQL-over-REST, then PATCHes the record via the compound `Metadata` field using `sf api request rest`. `ScheduledApex` entries run anonymous Apex `System.schedule(...)` via `sf apex run` (because `CronTrigger` is read-only) and verify via a `CronTrigger` SOQL read-back. Use when the user asks to apply, run, execute, dry-run, or preview a post-copy or post-refresh config file (e.g. `post-copy-config.json`) against a sandbox. Trigger phrases: \"apply post-copy config\", \"run post-copy automation\", \"execute sandbox post-refresh JSON\", \"apply sandbox refresh config\", \"configure sandbox after refresh\". DO NOT TRIGGER for generating the config JSON from an SOP (delegate to `automation-sandbox-post-copy-config-generate`), or for deploying metadata XML.
Automation: Sandbox Post-Copy ConfigureTool RestrictionsSTOP — do this before making any API callPer-entry procedure (the core of this skill)Step A — Resolve the Tooling API sobject and lookup filterStep B — Verify the candidate exists and supports Metadata writesStep C — Resolve the record Id (SOQL-over-REST)SOQL to a variable + separate jq call — avoids the most commonshell-quoting failure in this skill.Step D — GET current Metadata, mutate, PATCH backStep E — Verify the change landedStep F — Scheduled Apex (anonymous Apex route)
Apply a Salesforce sandbox post-copy automation JSON config against a target org. For each entry, the skill derives the correct Tooling API sobject from the entry's `ConfigurationName`, verifies the derivation via a describe probe, resolves the record Id via SOQL-over-REST, then PATCHes the record via the compound `Metadata` field using `sf api request rest`. `ScheduledApex` entries run anonymous Apex `System.schedule(...)` via `sf apex run` (because `CronTrigger` is read-only) and verify via a `CronTrigger` SOQL read-back. Use when the user asks to apply, run, execute, dry-run, or preview a post-copy or post-refresh config file (e.g. `post-copy-config.json`) against a sandbox. Trigger phrases: \"apply post-copy config\", \"run post-copy automation\", \"execute sandbox post-refresh JSON\", \"apply sandbox refresh config\", \"configure sandbox after refresh\". DO NOT TRIGGER for generating the config JSON from an SOP (delegate to `automation-sandbox-post-copy-config-generate`), or for deploying metadata XML.
---
name: automation-sandbox-post-copy-configure
description: "Apply a Salesforce sandbox post-copy automation JSON config against a target org. For each entry, the skill derives the correct Tooling API sobject from the entry's `ConfigurationName`, verifies the derivation via a describe probe, resolves the record Id via SOQL-over-REST, then PATCHes the record via the compound `Metadata` field using `sf api request rest`. `ScheduledApex` entries run anonymous Apex `System.schedule(...)` via `sf apex run` (because `CronTrigger` is read-only) and verify via a `CronTrigger` SOQL read-back. Use when the user asks to apply, run, execute, dry-run, or preview a post-copy or post-refresh config file (e.g. `post-copy-config.json`) against a sandbox. Trigger phrases: \"apply post-copy config\", \"run post-copy automation\", \"execute sandbox post-refresh JSON\", \"apply sandbox refresh config\", \"configure sandbox after refresh\". DO NOT TRIGGER for generating the config JSON from an SOP (delegate to `automation-sandbox-post-copy-config-generate`), or for deploying metadata XML."
allowed-tools: Bash Read Write
metadata:
relatedSkills:
- "automation-sandbox-post-copy-config-generate"
- "dx-org-permission-set-assign"
- "platform-metadata-deploy"
version: "1.1"
domains: ["Automation"]
cliTools:
- tool: ["curl"]
semver: ">=7.0.0"
- tool: ["jq"]
semver: ">=1.6"
- tool: ["node"]
semver: ">=18.0.0"
- tool: ["sf"]
semver: ">=2.0.0"
---
# Automation: Sandbox Post-Copy Configure
Apply a Salesforce sandbox post-copy automation JSON config to a target
org. Three canonical `ConfigurationName` values are pinned:
`OutboundMessages` and `RemoteSiteSettings` take the compound-`Metadata`
PATCH route (Steps A–E); `ScheduledApex` takes the anonymous-Apex route
(Step F), because `CronTrigger` is read-only in the Tooling API. Any
other `ConfigurationName` is derived and describe-verified. Every A–E
entry — pinned or derived — must pass Step B (describe returns 200 with
a `Metadata` compound field) before any PATCH is planned; Step B does
not apply to `ScheduledApex`. Entries whose API cannot be verified are
surfaced in the summary and skipped — never guessed at.
## Tool Restrictions
**Use ONLY the Bash tool** to execute `sf` CLI commands (`sf data query
--use-tooling-api`, `sf api request rest`, `sf org display`). Do NOT
use MCP tools like `execute_soql` — ignore them completely; the
compound `Metadata` PATCH pattern this skill requires is not available
through MCP tool wrappers. If the target org alias is not explicitly
named by the user, invoke `sf` commands **without** `--target-org` —
the harness has already set the CLI's default target-org. Never pass
`--target-org default` — `default` is not an alias and will fail with
`NamedOrgNotFoundError`.
SOQL-over-REST (`sf data query --use-tooling-api ...`) is treated as
an API call — same OAuth session, same authorization boundary as the
subsequent PATCH. No direct database / non-Salesforce SQL access.
## STOP — do this before making any API call
Never call the org from memory. Before the first request:
1. Read the config JSON end-to-end from the exact path the user gave
(default `./post-copy-config.json`). Every entry must have all five
keys (`ConfigurationName`, `Label`, `Fields`, `IsActive`,
`ExecutionOrder`). If any entry is malformed, abort and surface the
file path + entry index — do **not** partially apply. **Do not
invent entries.** If the file is missing, stop and ask; never
fabricate a plan against synthetic labels.
2. For each distinct `ConfigurationName` in the config, run the
derivation + describe-verify step (below) **before** planning any
PATCH. An entry whose API cannot be verified must never appear as
a planned PATCH — it is rejected up front.
3. Confirm the target org alias with the user unless they supplied one
explicitly. This skill mutates a live org — writing to the wrong
org (e.g., a production alias set as default) is the most expensive
failure mode.
If you announce "I will apply … now" without having read the config
file and run the describe-verify for every distinct
`ConfigurationName`, stop and do those first.
---
## Per-entry procedure (the core of this skill)
The skill carries a pinned mapping for the canonical types below, and
a derive-then-verify path for anything else. Follow these steps **for
every entry**, in order. `Step B` (describe-verify) is mandatory
regardless of whether the mapping came from the pinned table or the
derive path — its HTTP status must appear in the summary.
### Step A — Resolve the Tooling API sobject and lookup filter
**Pinned canonicals (authoritative — use these exactly, do NOT
substitute a different sobject name):**
| ConfigurationName | Tooling API sobject | Record-lookup SOQL |
|-------------------|---------------------|--------------------|
| `OutboundMessages` | `WorkflowOutboundMessage` | `SELECT Id, FullName FROM WorkflowOutboundMessage WHERE EntityDefinition.QualifiedApiName = ''` — then client-side pick the row whose `FullName == '.'`. SOQL cannot filter on `FullName` directly for this sobject. |
| `RemoteSiteSettings` | `RemoteProxy` | `SELECT Id, SiteName FROM RemoteProxy WHERE SiteName = ''`. |
| `ScheduledApex` | `CronTrigger` (read-only — Anonymous Apex route, see Step F) | See Step F — pre-flight `SELECT Id FROM CronTrigger WHERE CronJobDetail.Name = ''` gate. |
For canonical entries use the pinned sobject and SOQL as-is; skip
"derive". Do not invent `OutboundMessage`, `RemoteSiteSetting`, or
`MasterLabel` variants — plausible-looking but wrong.
Field-name resolution (overrides + case rule + existence check) is
owned by `scripts/map-metadata-key.mjs`.
**Non-canonical**: derive a candidate (usually singular of the
Metadata API type name, sometimes prefixed); Step B rules out wrong
guesses. Use the generic SOQL patterns in Step C.
### Step B — Verify the candidate exists and supports Metadata writes
For each candidate, GET the describe:
```bash
sf api request rest \
"/services/data/v/tooling/sobjects//describe/"
```
Accept the candidate only if **both** are true:
- HTTP 200 (the sobject exists on this org's Tooling API), AND
- The describe response's `fields` array contains a field named
`Metadata` (compound field — this is what PATCH writes through).
If no candidate passes both gates, mark the entry
`API_NOT_IDENTIFIED` and skip. **Do not guess a REST path** — the
wrong path 404s in the best case and updates the wrong record in the
worst case.
### Step C — Resolve the record Id (SOQL-over-REST)
**For pinned canonicals**: run the SOQL from the Step A table
verbatim (substituting `` / ``). Do not
substitute a different filter column such as `MasterLabel` — the
pinned SOQL is the tested-and-correct filter for that sobject.
**For non-canonical (derived) sobjects**: query the verified sobject
for the record identified by the entry's `Label` (and `Fields.Object`
when present):
```bash
# SOQL to a variable + separate jq call — avoids the most common
# shell-quoting failure in this skill.
SOQL='SELECT Id, FullName FROM WHERE '
sf data query --use-tooling-api --json --query "$SOQL" \
> /tmp/entry--lookup.json
ID=$(jq -r '.result.records[0].Id // empty' /tmp/entry--lookup.json)
```
Pick `` based on the queryable fields shown in the
describe response from Step B. If the row contains a `FullName` field,
SOQL usually rejects a direct `FullName = ...` filter — filter by
whichever direct column the describe surfaces (e.g.
`EntityDefinition.QualifiedApiName`, `DeveloperName`, `SiteName`) and
apply the `FullName` match client-side (`jq -r
'.result.records[] | select(.FullName == "