version: "1.0.1" name: platform-metadata-deploy description: "Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code (use platform-apex-generate), building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate or platform-custom-field-generate), or querying org data (use platform-data-manage)." metadata: version: "1.1" domains: ["Platform", "Developer Experience"] relatedSkills:

• "agentforce-generate"
• "agentforce-test"
• "automation-flow-generate"
• "experience-lwc-generate"
• "integration-connectivity-connected-app-configure"
• "integration-connectivity-generate"
• "platform-apex-generate"
• "platform-apex-test-run"
• "platform-custom-field-generate"
• "platform-custom-object-generate"
• "platform-data-manage"

cliTools:

• tool: ["curl"]

semver: ">=7.0.0"

• tool: ["git"]

semver: ">=2.0.0"

• tool: ["jq"]

semver: ">=1.7.0"

• tool: ["sf"]

semver: ">=2.0.0"

platform-metadata-deploy: Comprehensive Salesforce DevOps Automation

Use this skill when the user needs deployment orchestration: dry-run validation, targeted or manifest-based deploys, CI/CD workflow advice, scratch-org management, failure triage, or safe rollout sequencing for Salesforce metadata.

When This Skill Owns the Task

Use platform-metadata-deploy when the work involves:

• sf project deploy start, quick, report, or retrieval workflows
• release sequencing across objects, permission sets, Apex, and Flows
• CI/CD gates, test-level selection, or deployment reports
• troubleshooting deployment failures and dependency ordering

Delegate elsewhere when the user is:

• authoring Apex code → platform-apex-generate
• authoring LWC components → experience-lwc-generate
• creating custom objects or fields → platform-custom-object-generate, platform-custom-field-generate
• building Flows → automation-flow-generate
• doing org data operations → platform-data-manage
• authoring or testing Agentforce agents → agentforce-generate

Critical Operating Rules

• Use `sf` CLI v2 only.
• On non-source-tracking orgs, deploy/retrieve commands require an explicit scope such as --source-dir, --metadata, or --manifest.
• Prefer `--dry-run` first before real deploys.
• For Flows, deploy safely and activate only after validation.
• Keep test-data creation guidance delegated to `platform-data-manage` after metadata is validated or deployed.

Default deployment order

This ordering prevents many dependency and FLS failures.

Required Context to Gather First

Ask for or infer:

• target org alias and environment type
• deployment scope: source-dir, metadata list, or manifest
• whether this is validate-only, deploy, quick deploy, retrieve, or CI/CD guidance
• required test level and rollback expectations
• whether special metadata types are involved (Flow, permission sets, agents, packages)

Preflight checks:

sf --version
sf org list
sf org display --target-org <alias> --json
test -f sfdx-project.json

Recommended Workflow

1. Preflight

Confirm auth, repo shape, package directories, and target scope.

2. Validate first

sf project deploy start --dry-run --source-dir force-app --target-org <alias> --wait 30 --json

Use manifest- or metadata-scoped validation when the change set is targeted.

3. If validation succeeds, offer the next safe workflow

After a successful validation, guide the user to the correct next action:

1. deploy now
2. assign permission sets
3. create test data via platform-data-manage
4. run tests / smoke checks
5. orchestrate multiple post-deploy steps in order

4. Deploy the smallest correct scope

# source-dir deploy
sf project deploy start --source-dir force-app --target-org <alias> --wait 30 --json
 
# manifest deploy
sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunLocalTests --wait 30 --json
 
# manifest deploy with Spring '26 relevant-test selection
sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunRelevantTests --wait 30 --json
 
# quick deploy after successful validation
sf project deploy quick --job-id <validation-job-id> --target-org <alias> --json

5. Verify

sf project deploy report --job-id <job-id> --target-org <alias> --json

Then verify tests, Flow state, permission assignments, and smoke-test behavior.

6. Report clearly

Summarize what deployed, what failed, what was skipped, and what the next safe action is.

Output template: references/deployment-report-template.md

High-Signal Failure Patterns

Full workflows: references/orchestration.md, references/trigger-deployment-safety.md

CI/CD Guidance

Default pipeline shape:

1. authenticate
2. validate repo / org state
3. static analysis
4. dry-run deploy
5. tests + coverage gates
6. deploy
7. verify + notify

• When org policy and release risk allow it, consider --test-level RunRelevantTests for Apex-heavy deployments.
• Pair this with modern Apex test annotations such as @IsTest(testFor=...) and @IsTest(isCritical=true) — see platform-apex-generate for authoring guidance.

Static analysis now uses Code Analyzer v5 (sf code-analyzer), not retired sf scanner.

Deep reference: references/deployment-workflows.md

Agentforce Deployment Note

Use this skill to orchestrate deployment/publish sequencing around agents, but use the agent-specific skill for authoring decisions:

• agentforce-generate for .agent authoring, Agent Builder, Prompt Builder, and metadata config

For full agent DevOps details, including Agent: pseudo metadata, publish/activate, and sync-between-orgs, see:

• references/agent-deployment-guide.md

Cross-Skill Integration

Reference Map

Start here

• references/orchestration.md
• references/deployment-workflows.md
• references/deployment-report-template.md

Specialized deployment safety

• references/trigger-deployment-safety.md
• references/agent-deployment-guide.md
• references/deploy.sh

Asset templates

• assets/package.xml — manifest template covering common metadata types
• assets/destructiveChanges.xml — template for removing metadata from target orgs

Score Guide

Completion Format

Deployment goal: <validate / deploy / retrieve / pipeline>
Target org: <alias>
Scope: <source-dir / metadata / manifest>
Result: <passed / failed / partial>
Key findings: <errors, ordering, tests, skipped items>
Next step: <safe follow-up action>