dx-org-analyze
Compare two Salesforce orgs side-by-side and produce a comparison report with drift score, or analyze a single org to produce an inventory covering metadata components, org permissions, system permissions, profiles, installed packages, licenses, and org limits. Use this skill when the user wants to compare orgs, diff orgs, audit configuration drift, find what changed between two environments, compare sandbox against production, or analyze a single org. Trigger phrases include: 'compare orgs', 'compare these 2 orgs', 'compare my orgs', 'diff orgs', 'org diff', 'what is different between these orgs', 'compare metadata', 'org comparison', 'audit org differences', 'compare sandbox to production', 'introspect org', 'org inventory', 'what is in my org', 'analyze org', 'org analysis', 'analyze my org', 'analyze my Salesforce org'. Do NOT use for retrieving metadata (use platform-metadata-retrieve), deploying metadata (use platform-metadata-deploy), or switching orgs (use dx-org-switch).
- Installs
- 512
- Last 24h
- +13
- Trending rank
- #7657
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/forcedotcom/sf-skills --skill dx-org-analyze- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads dx-org-analyze automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Tool Restrictions
Use ONLY the Bash tool to execute all sf CLI commands and Python scripts. Always include --json for sf commands. Do NOT use mcp__salesforce_dx__* tools.
Output artifacts for eval/testing: When an output directory is available, write results there. After executing the skill: (1) if the user specified an output path, write there immediately; (2) otherwise run [ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output' to detect the eval directory; (3) write the full JSON result to <output-dir>/dx-org-analyze-result.json and the markdown report to <output-dir>/dx-org-analyze-result.md.
Data Access Hierarchy
When querying org data, always follow this priority order:
- SF CLI commands — Preferred. Use
sf org list metadata-types,sf org list metadata,sf org display,sf data query,sf limits api display, etc. - Direct REST/Tooling API calls — Last resort, only when SF CLI cannot provide the data.
Never bypass this hierarchy. If an SF CLI command exists for the operation, use it even if a direct API call would be simpler.
Authentication Rules
- All authentication MUST go through SF CLI (
sf org login web,sf org login jwt,sf org login access-token). - Never accept raw credentials (username + password), session IDs, or access tokens directly from the user.
- The collection script obtains its access token exclusively via
sf org display --json.
Workflow
Step 0: List Authenticated Orgs
Run this command to discover all authenticated orgs:
sf org list --json --skip-connection-status
Parse the JSON output. Collect orgs from all buckets (devHubs, nonScratchOrgs, scratchOrgs, sandboxes, other). Present authenticated orgs in a readable table:
| # | Alias | Username | Instance URL | Org ID | Type |
|---|
If fewer than 2 orgs are authenticated but at least 1 is available, offer the single-org introspect mode (see Introspect Workflow below). If no orgs are authenticated, STOP and advise:
You need at least 1 authenticated org. Run
sf org login web --alias <name>to authenticate.
If the user explicitly requests a single-org introspection or inventory, use the Introspect Workflow regardless of how many orgs are available.
Step 1: User Selects Two Orgs
Ask the user to select two orgs from the list. Both must be explicitly named — do NOT allow implicit/default orgs.
Select two orgs to compare. Which is the source (reference/expected state)? Which is the target (to compare against)?
Accept: alias, username, or number from the list. Resolve each selection to a concrete username. If an org lacks an alias, prompt the user to assign one. Confirm:
Comparing:
- Source:
<alias>(<username>)- Target:
<alias>(<username>)
Step 2: Validate Connectivity
For each org, confirm reachability with a lightweight query that does not expose secrets:
sf data query --target-org <alias-or-username> --query "SELECT Id FROM Organization LIMIT 1" --json
If the query succeeds (exit 0 and a record is returned), the org is connected. If it fails with INVALID_SESSION_ID or auth errors:
sf org login web --alias <alias>
Step 3: Collect Data (per org)
Generate a unique run ID and run the collection script for each org:
RUN_ID=$(date +%Y%m%d-%H%M%S)
python3 ./scripts/collect_org_data.py \
--org-alias "$SOURCE_ORG" \
--output /tmp/dx-org-comparison-${RUN_ID}-source
python3 ./scripts/collect_org_data.py \
--org-alias "$TARGET_ORG" \
--output /tmp/dx-org-comparison-${RUN_ID}-target
Exit codes: 0 = success, 1 = fatal error (report stderr to user), 2 = session expired (re-authenticate Step 2 and retry).
For details on what the collection script gathers, see references/collection-details.md.
Step 4: Compute Diff and Report
python3 ./scripts/compute_diff.py \
--org-a /tmp/dx-org-comparison-${RUN_ID}-source \
--org-b /tmp/dx-org-comparison-${RUN_ID}-target \
--output /tmp/dx-org-comparison-${RUN_ID} \
--format both \
--org-a-label "Source" \
--org-b-label "Target"
Use --show-shared if the user wants shared components listed in detail.
Step 5: Present Results
Read /tmp/dx-org-comparison-${RUN_ID}.md and present to the user. If the user asks follow-up questions, use /tmp/dx-org-comparison-${RUN_ID}.json for data lookups. Then resolve the output directory and copy both files there:
OUTPUT_DIR=""
if [ -n "$USER_OUTPUT_PATH" ]; then
OUTPUT_DIR="$USER_OUTPUT_PATH"
elif [ -d "force-app/main/adk-eval-output" ]; then
OUTPUT_DIR="force-app/main/adk-eval-output"
fi
if [ -n "$OUTPUT_DIR" ]; then
cp /tmp/dx-org-comparison-${RUN_ID}.json "$OUTPUT_DIR/dx-org-analyze-result.json"
cp /tmp/dx-org-comparison-${RUN_ID}.md "$OUTPUT_DIR/dx-org-analyze-result.md"
fi
Introspect Workflow (Single-Org Mode)
Use this workflow when the user wants to inspect a single org's configuration, or when only one org is authenticated.
Introspect Step 1: Validate Connectivity
sf data query --target-org <alias-or-username> --query "SELECT Id FROM Organization LIMIT 1" --json
Introspect Step 2: Collect Data
RUN_ID=$(date +%Y%m%d-%H%M%S)
python3 ./scripts/collect_org_data.py \
--org-alias "$ORG" \
--output /tmp/dx-org-analysis-${RUN_ID}
Introspect Step 3: Generate Report
python3 ./scripts/introspect_org.py \
--org /tmp/dx-org-analysis-${RUN_ID} \
--output /tmp/dx-org-analysis-${RUN_ID} \
--format both \
--label "OrgName"
Introspect Step 4: Present Results
Read /tmp/dx-org-analysis-${RUN_ID}.md and present to the user. The report covers: metadata inventory, org settings, org limits, installed packages, licenses, system permissions, and deep data records. Then resolve the output directory and copy both files there:
OUTPUT_DIR=""
if [ -n "$USER_OUTPUT_PATH" ]; then
OUTPUT_DIR="$USER_OUTPUT_PATH"
elif [ -d "force-app/main/adk-eval-output" ]; then
OUTPUT_DIR="force-app/main/adk-eval-output"
fi
if [ -n "$OUTPUT_DIR" ]; then
cp /tmp/dx-org-analysis-${RUN_ID}.json "$OUTPUT_DIR/dx-org-analyze-result.json"
cp /tmp/dx-org-analysis-${RUN_ID}.md "$OUTPUT_DIR/dx-org-analyze-result.md"
fi
Report Structure
The generated report includes:
- Drift Score — Weighted overall score (60% metadata, 30% permissions, 10% profiles) with severity level (LOW/MODERATE/HIGH/CRITICAL)
- Summary Statistics — Counts per metadata type with Identical/Different columns from deep data
- Metadata Components by Type — Only-in-Source, only-in-Target, shared per type
- Profiles — Shared, source-only, target-only
- Installed Packages — Version comparison, only-in-Source, only-in-Target
- Package Components — Namespaced components grouped by namespace
- Org Permissions — Boolean enabled/disabled diffs by category, plus value diffs
- System Permissions — PermissionsXxx fields on PermissionSet, per-set diffs
- Org Values & Limits — Grouped by Identity, Storage, API, Feature Limits
- Licenses — User, Permission Set, Package license quantity diffs
- Deep Data — Content-level diffs for Apex, Flows, Validation Rules, Custom Fields, etc.
Rules / Constraints
| Constraint | Rationale |
|---|---|
Always use --json with sf commands | Structured output for reliable parsing |
| Resolve orgs to usernames, not aliases | Aliases can be ambiguous; usernames are unique |
| Skip expired and disconnected orgs | Cannot query metadata from inaccessible orgs |
| Read-only — never deploy or modify | This skill compares only, never mutates either org |
| SF CLI auth only | All authentication through SF CLI credential store |
| Both orgs must be explicit | Never compare unnamed or implicit/default orgs |
Troubleshooting
| Issue | Resolution |
|---|---|
| "No org found for <alias>" | Org not authenticated — run sf org login web --alias <name> |
| Fewer than 2 authenticated orgs | Authenticate additional orgs before comparing |
| "INVALID_SESSION_ID" or auth errors | Session expired — re-run sf org login web --alias <name> |
| Collection script exits with code 2 | Session expired — re-authenticate and retry |
| API limit errors during metadata listing | Use --skip-deep-data for a faster pass with less detail |
| Edition differences (DE vs EE) | Many differences are edition-inherent, not configuration drift |
| Large orgs timeout on deep data | Use --skip-deep-data flag; run full deep data on targeted follow-ups |
Cross-Skill Integration
| Need | Delegate to |
|---|---|
| Retrieve specific metadata from an org | platform-metadata-retrieve |
| Deploy metadata to an org | platform-metadata-deploy |
| Create a scratch org for comparison | dx-org-manage |
| Switch default org after comparison | dx-org-switch |
Reference File Index
| File | When to read |
|---|---|
references/collection-details.md | For details on what the collection script gathers and how |
references/report-format.md | For drift score formula and report section details |
scripts/collect_org_data.py | Data collection script (per org) |
scripts/compute_diff.py | Diff computation and report generation script |
scripts/introspect_org.py | Single-org introspection report script |
FAQ
What does the dx-org-analyze skill do?
Compare two Salesforce orgs side-by-side and produce a comparison report with drift score, or analyze a single org to produce an inventory covering metadata components, org permissions, system permissions, profiles, installed packages, licenses, and org limits. Use this skill when the user wants to compare orgs, diff orgs, audit configuration drift, find what changed between two environments, compare sandbox against production, or analyze a single org. Trigger phrases include: 'compare orgs', 'compare these 2 orgs', 'compare my orgs', 'diff orgs', 'org diff', 'what is different between these orgs', 'compare metadata', 'org comparison', 'audit org differences', 'compare sandbox to production', 'introspect org', 'org inventory', 'what is in my org', 'analyze org', 'org analysis', 'analyze my org', 'analyze my Salesforce org'. Do NOT use for retrieving metadata (use platform-metadata-retrieve), deploying metadata (use platform-metadata-deploy), or switching orgs (use dx-org-switch).
How do I install dx-org-analyze?
Run npx skills add https://github.com/forcedotcom/sf-skills --skill dx-org-analyze in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/dx-org-analyze/ (personal) or .claude/skills/dx-org-analyze/ (project).
Which AI agents can use dx-org-analyze?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is dx-org-analyze safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains dx-org-analyze?
It is published by forcedotcom in forcedotcom/sf-skills. It has 512 recorded installs.
More from forcedotcom/sf-skills
platform-apex-generate
forcedotcom/sf-skills
Primary Apex authoring skill for class generation, refactoring, and review. ALWAYS ACTIVATE when the user mentions Apex, .cls, triggers, or asks to create/refactor a class (service, selector, domain, batch, queueable, schedulable, invocable, DTO, utility, interface, abstract, exception, REST resource). Use this skill for requests involving SObject CRUD, mapping collections, fetching related records, scheduled jobs, batch jobs, trigger design, @AuraEnabled controllers, @RestResource endpoints, custom REST APIs, or code review of existing Apex.
platform-apex-test-generate
forcedotcom/sf-skills
Use to generate and validate Apex test classes with TestDataFactory patterns, bulk testing (251+ records), mocking, assertions, and disciplined test-fix loops. Use when creating Apex test classes (for triggers, services, controllers, batch jobs, queueables, and callouts), improving coverage, debugging or fixing failing Apex tests, or running test/coverage analysis. Triggers on Test.cls files, sf apex run test, coverage reports. Do NOT trigger for production Apex (use platform-apex-generate) or Jest/LWC tests.
platform-apex-test-run
forcedotcom/sf-skills
Apex test execution, coverage analysis, and test-fix loops with 120-point scoring. Use when the user runs Apex tests, checks code coverage, fixes failing tests, or touches Test.cls / Test.cls files. DO NOT TRIGGER when writing Apex production code (use platform-apex-generate), Agentforce agent testing (use agentforce-test), or Jest/LWC tests (use experience-lwc-generate).
platform-apex-logs-debug
forcedotcom/sf-skills
Salesforce debug log analysis and troubleshooting with 100-point scoring. TRIGGER when: user analyzes debug logs, hits governor limits, reads stack traces, or touches .log files from Salesforce orgs. DO NOT TRIGGER when: running Apex tests (use platform-apex-test-run), generating or fixing Apex code (use platform-apex-generate), or Agentforce session tracing (use agentforce-observe).
platform-soql-query
forcedotcom/sf-skills
Use when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan/selectivity analysis, and performance or safety improvements. TRIGGER when the user writes, optimizes, or debugs SOQL/SOSL, touches .soql files, or asks about relationship queries, aggregates, or query performance. DO NOT TRIGGER for bulk data operations (use platform-data-manage), Apex DML logic (use platform-apex-generate), or report/dashboard queries.
platform-metadata-deploy
forcedotcom/sf-skills
Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, validates a deploy or does a dry-run, deploys to a Production org, quick-deploys a validated job ID, ships/promotes to prod, 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, building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate), deleting metadata from an org (use platform-destructive-deploy), or querying org data (use platform-data-manage).
Popular security skills
azure-compliance
microsoft/azure-skills
Run Azure compliance and security audits with azqr plus Key Vault expiration checks. Covers best-practice assessment, resource review, policy/compliance validation, and security posture checks. WHEN: compliance scan, security audit, BEFORE running azqr (compliance cli tool), Azure best practices, Key Vault expiration check, expired certificates, expiring secrets, orphaned resources, compliance assessment.
minimal-run-and-audit
lllllllama/rigorpilot-skills
Rigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation command and write standardized reprooutputs/ files, including patch notes when repository files changed. Do not use for training execution, initial repo intake, generic environment setup, paper lookup, target selection, hidden scientific-meaning changes, or end-to-end orchestration by itself.
seo-audit
coreyhaines31/marketingskills
When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," "indexing issues," "stuck on page 2," "striking distance keywords," "title tag rewrite," "low CTR," "local SEO," "Google Business Profile," or "map pack." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema. For AI search optimization, see ai-seo.
firebase-security-rules-auditor
firebase/agent-skills
Audits Firebase (Firestore, Cloud Storage) security rules for vulnerabilities, privilege escalation, role bypasses, create vs update inconsistencies, resource exhaustion, type safety, size limits, and hasOnly ownership checks. Use when auditing/reviewing rules, running red-team rule assessments, or scoring against auditor checklists. Don't use for Firebase CLI (login, deploy), Auth, Crashlytics, Remote Config, or database queries.
audit
pbakaus/impeccable
Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review.
competitors
coreyhaines31/marketingskills
When the user wants to create competitor comparison or alternative pages for SEO and buyer-facing use. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' 'competitive landing pages,' 'how do we compare to X,' 'competitor teardown,' 'audit our competitor pages,' 'are our comparison pages out of date,' or 'competitive asset audit.' Use this for any content that positions your product against competitors. Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. For auditing existing claims (not researching competitors from scratch, which is competitor-profiling; not technical SEO on these pages, which is seo-audit), use the asset audit here. For internal battle cards and sales-specific competitor docs, see sales-enablement.