Skip to content

kugamon/salesforce-core-skills / plugins/salesforce-core/skills/sf-metadata

sf-metadata

Verified

Salesforce metadata operations expert. Use when creating custom objects, fields, validation rules, record types, permission sets, or querying org metadata structures via a Salesforce MCP server. Do NOT use for comparing metadata across two orgs (use sf-orgdiff), Named or External Credentials and Platform Events (use sf-integration), or querying and loading records (use sf- data). Usage: /sf-metadata [create|update|delete|describe] {ObjectName|FieldName|type} ...

FileKindSize
CREDITS.mdmarkdown2.3 KB
LICENSEother1.1 KB
README.mdmarkdown3.5 KB
SKILL.mdskill md33.8 KB
assets/fields/checkbox-field.xmlconfig971 B
assets/fields/currency-field.xmlconfig1.3 KB
assets/fields/date-field.xmlconfig1.0 KB
assets/fields/email-field.xmlconfig1.1 KB
assets/fields/formula-field.xmlconfig2.3 KB
assets/fields/lookup-field.xmlconfig2.1 KB
assets/fields/master-detail-field.xmlconfig1.8 KB
assets/fields/multi-select-picklist.xmlconfig2.0 KB
assets/fields/number-field.xmlconfig1.4 KB
assets/fields/phone-field.xmlconfig1.0 KB
assets/fields/picklist-field.xmlconfig2.1 KB
assets/fields/rollup-summary-field.xmlconfig2.7 KB
assets/fields/text-field.xmlconfig1.2 KB
assets/fields/textarea-field.xmlconfig1.1 KB
assets/fields/url-field.xmlconfig940 B
assets/layouts/page-layout.xmlconfig6.5 KB
assets/objects/custom-object.xmlconfig2.4 KB
assets/permission-sets/permission-set.xmlconfig5.7 KB
assets/profiles/profile.xmlconfig5.2 KB
assets/record-types/record-type.xmlconfig3.7 KB
assets/validation-rules/validation-rule.xmlconfig5.1 KB
references/best-practices-scoring.mdmarkdown3.6 KB
references/customfield-metadata-schema.jsonconfig16.1 KB
references/customobject-metadata-schema.jsonconfig49.9 KB
references/execution-modes.mdmarkdown7.0 KB
references/field-types-guide.mdmarkdown8.8 KB
references/flexipage-metadata-schema.jsonconfig11.6 KB
references/fls-best-practices.mdmarkdown7.8 KB
references/layout-metadata-schema.jsonconfig17.8 KB
references/mcp-pagination.mdmarkdown3.1 KB
references/metadata-types-reference.mdmarkdown8.5 KB
references/naming-conventions.mdmarkdown5.6 KB
references/permset-auto-generation.mdmarkdown2.8 KB
references/quickaction-metadata-schema.jsonconfig6.9 KB
references/recordtype-metadata-schema.jsonconfig2.9 KB
references/validationrule-metadata-schema.jsonconfig1.2 KB
scripts/mcp_validator.pyscript4.5 KB
scripts/pre-mcp-validate.pyscript4.3 KB
scripts/validate_metadata_operation.pyscript13.9 KB

references/execution-modes.md

View on GitHub
# Execution Modes

## Tool-name mapping (read this first)

The tool names used across these skills — `org_init`, `soql_query`,
`sobject_dml`, `sobject_describe`, `metadata_create`, `metadata_update`,
`tooling_api_query`, `tooling_api_dml`, `apex_execute` — are **capability
conventions, not literal tool names**. Map each to whatever your connected
Salesforce MCP server actually exposes BEFORE calling anything. Typical
mappings (mcp-salesforce-connector family):

| Convention | Common real tool |
| --- | --- |
| `soql_query` | `run_soql_query` |
| `sobject_describe` | `get_object_fields` |
| `sobject_dml` | `create_record` / `update_record` / `delete_record` (or `bulk_*`) |
| `tooling_api_query` | `tooling_execute` with `query/?q=...` (GET) |
| `tooling_api_dml` | `tooling_execute` POST/PATCH/DELETE on `sobjects/...` |
| `metadata_create` / `metadata_update` | `restful` / `tooling_execute` against Metadata or Tooling endpoints — note CustomObject creation is NOT available via Tooling REST (see sf-metadata) |
| `apex_execute` | `apex_execute` |
| `org_init` | your server's init/connection tool; if none exists, verify with `SELECT Id FROM Organization LIMIT 1` and proceed |

Never report a capability as missing because a conventional name isn't
present — find the connector's equivalent and record the mapping once in
your working notes.

## Headless runs (no user available)

When running non-interactively (subagent, scheduled task, CI): approval
gates degrade predictably rather than blocking. Read-only steps proceed
with assumptions stated in the output. Org WRITES the skill gates behind
user approval stay **propose-only** unless the caller explicitly granted
write permission for named artifacts. `AskUserQuestion` steps become
"choose the safest default and record the decision." Never silently skip a
gate — record what would have been asked and what was chosen.


All These Salesforce skills support four execution modes. The mode
determines how metadata is retrieved, how large responses are handled, and
what local tooling is available.

Detect the mode **once** at the start of a session and record it in any
state files. Skills may define mode-specific behaviour in their own
SKILL.md; this document covers the shared fundamentals.

---

## Mode 1 — `sfdx-repo` (metadata on disk)

The working directory (or a user-specified path) is a Salesforce DX project
with metadata already retrieved.

**Detection:**

```bash
test -f sfdx-project.json && echo "SFDX project found"
```

If found, read `sfdx-project.json` to locate the source directory (usually
`force-app/main/default`). Confirm the user wants to use local metadata —
it may be stale relative to the live org.

**Capabilities:**

- Read `.cls`, `.trigger`, `.flow-meta.xml`, LWC bundles, and other
  metadata directly from disk — no API calls for body retrieval.
- Use MCP tools only for live-only data (permission assignments, user
  counts, org limits, etc.).
- For incremental operations: use `git log` to detect changed files.
- Code execution (Python, jq, etc.) is available.

---

## Mode 2 — `cli` (Salesforce CLI)

The Salesforce CLI (`sf`) is installed and authenticated to the target org.

**Detection:**

```bash
command -v sf >/dev/null 2>&1 && sf --version
sf org display --target-org <alias-or-username> --json 2>/dev/null
```

Both checks must pass — the CLI must be installed **and** authenticated to
a usable org. Verify the target org matches the org selected during
`org_init()`. If the CLI is present but not authenticated, or if the
orgs differ, warn the user and fall back to `mcp-plus-code-execution`.

**Capabilities:**

- Bulk retrieve via `sf project retrieve start -m <type>`.
- Queries via `sf data query -q "..." --target-org <org> --json`.
- Code execution (Python, jq, etc.) is available.
- Use MCP tools for targeted lookups when CLI is not needed.

---

## Mode 3 — `mcp-plus-code-execution` (MCP + local tooling)

MCP tools are the only connection to Salesforce, but the environment has a
writable filesystem and can execute code (Python, shell, jq, etc.).

This is the typical mode in most AI coding tools with
**OpenAI Codex**.

**Detection:**

Neither `sfdx-project.json` nor an authenticated `sf` CLI is available,
but the environment supports code execution and file writes:

```bash
# Verify code execution
python3 --version >/dev/null 2>&1 || python --version >/dev/null 2>&1
# Verify writable filesystem
test -w . && echo "writable"
```

Both checks must pass. Being able to write files to disk **and** execute
code is the key differentiator from `mcp-core`.

**Capabilities:**

- All metadata via `tooling_api_query`, `metadata_read`, `soql_query`,
  `sobject_describe`, etc.
- **Artifact download**: when a response includes `instructions.artifactUrl`,
  fetch the URL and write the full JSON to a local file for processing.
  See `references/mcp-pagination.md` for details.
- Code execution for post-processing (scoring scripts, report generation,
  jq transforms, etc.).

---

## Mode 4 — `mcp-core` (MCP only)

MCP tools are the only connection to Salesforce, and there is **no local
filesystem or code execution**.

This is the typical mode in **chat interfaces** and **API-only** contexts.

**Detection:**

Fallback when none of the above modes are detected. If `python3 --version`
fails and you cannot write files to disk, you are in `mcp-core`.

**Capabilities:**

- All metadata via MCP tools (same as `mcp-plus-code-execution`).
- **No artifact download** — cannot fetch URLs or write files.
- Large responses must be paged through in-context using
  `fetch_more(artifactId=..., cursor=...)`. See
  `references/mcp-pagination.md` for details.
- Process data in small batches; discard between batches to manage context.

---

## Mode summary

| Mode                      | Body retrieval   | Artifact handling                     | Code execution | Speed   |
| ------------------------- | ---------------- | ------------------------------------- | -------------- | ------- |
| `sfdx-repo`               | Local filesystem | N/A (data on disk)                    | Yes            | Fastest |
| `cli`                     | `sf` CLI bulk    | N/A (CLI writes to disk)              | Yes            | Fast    |
| `mcp-plus-code-execution` | MCP tools        | Download `artifactUrl` to working dir | Yes            | Medium  |
| `mcp-core`                | MCP tools        | `fetch_more` with cursor (in-context) | No             | Slowest |

In all modes, call `org_init()` first to establish the MCP connection.

---

## Plugin root path

Skills reference validation scripts via `${CLAUDE_PLUGIN_ROOT}`. This env
var is set automatically by Claude Code when a plugin is active. Other
hosts should set their own equivalent before invoking skill scripts:

| Host         | Environment variable  |
| ------------ | --------------------- |
| Claude Code  | `$CLAUDE_PLUGIN_ROOT` |
| OpenAI Codex | `$CODEX_PLUGIN_ROOT`  |
| Other        | `$PLUGIN_ROOT`        |

If none of these are set, skills fall back to searching for the script:

```bash
find ~/ -name "<script_name>.py" 2>/dev/null | head -1
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall