platform-report-generate
Use when users create, generate, or validate Salesforce Lightning Report metadata (.report-meta.xml) — tabular, summary, matrix, or joined reports with columns, groupings, filters, charts, cross-filters, buckets, formulas, or time-frame filters. Triggers on "create a report", "build a report", "add a chart", or .report-meta.xml deploy errors. Do NOT trigger for Custom Report Type metadata (use platform-custom-report-type-generate), dashboards, list views, running reports in the UI, or SOQL.
- Installs
- 3K
- Last 24h
- +15
- Trending rank
- #6961
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/forcedotcom/sf-skills --skill platform-report-generate- 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 platform-report-generate 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.
Overview
Lightning Reports define how Salesforce data is queried, grouped, filtered, and displayed. Each report is a single .report-meta.xml file placed under reports/<FolderName>/ within the project's source directory (check sfdx-project.json → packageDirectories[].path for the source root).
Critical Rules (Read First)
TOP DEPLOYMENT KILLERS — check these BEFORE generating any report:
- Grouping fields in columns — Fields in
<groupingsDown>or<groupingsAcross>must NEVER also appear in<columns> - Wrong column names — Column names are report-type-specific. ALWAYS call MCP tools to verify (see
references/column-names.md) - Wrong scope — LeadList uses
org, notorganization - Filter column dot notation — Filter
<column>values use FLAT names (INDUSTRY,TYPE) NOT dot notation (ACCOUNT.INDUSTRYis INVALID) - Multi-value picklist filters — Use ONE
<criteriaItems>with comma-separated<value>(e.g.,Technology,Financial Services). Do NOT split into multiple criteriaItems with booleanFilter
Rule 1: Format Determines Required Elements
| Format | <groupingsDown> | <groupingsAcross> | <block> |
|---|---|---|---|
Tabular | Not allowed | Not allowed | No |
Summary | At least 1 (max 3) | Not allowed | No |
Matrix | At least 1 (max 3) | At least 1 (max 3) | No |
Joined | Not at top level | Not at top level | At least 2 (max 5) |
Rule 2: Use Platform Column Names
Report metadata uses platform report column names, NOT raw API field names. ALWAYS call get_metadata_type_sections or get_metadata_type_context to confirm valid column names. See references/column-names.md for common mappings per report type.
Rule 3: Valid Report Type Required
<reportType> must be a standard API name (e.g., Opportunity, AccountList, CaseList, LeadList, AccountContactRole) or a deployed custom report type developer name.
Rule 4–5: Chart & Aggregates Require Summary/Matrix
Charts and <aggregateTypes> (Sum, Average, etc.) only work in Summary and Matrix reports.
Rule 6–8: Limits
- Max 3 cross-filters per report, each with up to 5 criteria items
<filterLogic>must reference all filters sequentially (e.g.,1 AND (2 OR 3))- Joined reports: 2–5 blocks, each block format must be Summary or Matrix (not Tabular)
Rule 9: Folder Structure
Reports must live inside a folder with a corresponding folder metadata file:
<sourceDir>/reports/<FolderName>/<ReportName>.report-meta.xml
<sourceDir>/reports/<FolderName>-meta.xml
Determine <sourceDir> from sfdx-project.json (commonly force-app/main/default, but this is configurable).
Rule 10–11: Date Columns & Scope
- Date columns use platform names (
CLOSE_DATE, notCloseDate) - LeadList scope is
org; Opportunity/AccountList/CaseList useorganization
Rule 12–13: Description & Groupings
<description>max 255 characters- Grouping fields must NOT appear in
<columns>— automatic deployment failure
Rule 14: Folder Metadata Requires <sharedTo>
<?xml version="1.0" encoding="UTF-8"?>
<ReportFolder xmlns="http://soap.sforce.com/2006/04/metadata">
<folderShares>
<accessLevel>Manage</accessLevel>
<sharedTo>AllInternalUsers</sharedTo>
<sharedToType>Group</sharedToType>
</folderShares>
<name>My Report Folder</name>
</ReportFolder>
Rule 15: Valid Date Intervals Only
Use INTERVAL_CURRENT for "this quarter", INTERVAL_CURY for "this year", INTERVAL_LAST30 for last 30 days. Do NOT use INTERVAL_CURQ — it is not valid. See references/date-intervals.md for the full list.
Top-Level Elements
| Element | Required | Notes |
|---|---|---|
<name> | Yes | Report name (max 40 chars) |
<reportType> | Yes | Report type API name |
<format> | Yes | Tabular, Summary, Matrix, or Joined |
<scope> | Recommended | organization (or org for LeadList) |
<columns> | Yes | Field columns — each has <field> and optional <aggregateTypes> |
<filter> | No | Contains <criteriaItems> with <column>, <operator>, <value> |
<groupingsDown> | Conditional | Row groupings: <field>, <dateGranularity>, <sortOrder> |
<groupingsAcross> | Conditional | Column groupings (Matrix only) |
<timeFrameFilter> | Recommended | <dateColumn>, <interval>, optional <startDate>/<endDate> |
<chart> | No | See references/chart-types.md |
<buckets> | No | Bucket field definitions |
<crossFilters> | No | Cross-object filters (with/without) |
<showDetails> | Recommended | true/false |
<showGrandTotal> | Recommended | true/false |
<showSubTotals> | Recommended | true/false |
<description> | Recommended | Business purpose (max 255 chars) |
<block> | Conditional | Joined format blocks |
Filter Syntax
<filter>
<criteriaItems>
<column>STAGE_NAME</column>
<operator>equals</operator>
<value>Closed Won</value>
</criteriaItems>
</filter>
Multi-value picklist: Use ONE criteriaItem with comma-separated values:
<criteriaItems>
<column>INDUSTRY</column>
<operator>equals</operator>
<value>Technology,Financial Services</value>
</criteriaItems>
Common operators: equals, notEqual, lessThan, greaterThan, contains, startsWith, includes, excludes, isBlank, notBlank. Full list in references/filter-operations.md.
Generation Workflow
- Gather Requirements — object, fields, groupings, filters, chart needs
- Determine Format — no groupings → Tabular; row groupings → Summary; row + column → Matrix; multiple objects → Joined
- Identify Column Names — call
get_metadata_type_sectionsMCP tool to get valid platform column names for the report type - Author Metadata — start from closest example in
examples/and adapt - Create Folder — generate folder directory +
<FolderName>-meta.xmlwith<folderShares> - Validate — run through
references/verification-checklist.md
Reference File Index
| File | When to read |
|---|---|
references/column-names.md | Step 3 — column name mappings per report type |
references/date-intervals.md | When setting timeFrameFilter intervals |
references/chart-types.md | When adding a chart — all 17 types + legendPosition rules |
references/filter-operations.md | When building filters — complete operator reference |
references/verification-checklist.md | Step 6 — pre-deploy validation |
references/errors-and-troubleshooting.md | When fields are missing or deployment fails |
examples/TabularOpportunitiesReport.report-meta.xml | Tabular report template |
examples/OpportunitiesByStageReport.report-meta.xml | Summary report with chart |
examples/OpportunitiesByStageAndQuarter.report-meta.xml | Matrix report template |
examples/AccountsCreatedThisYear.report-meta.xml | Filtered report with time frame |
FAQ
What does the platform-report-generate skill do?
Use when users create, generate, or validate Salesforce Lightning Report metadata (.report-meta.xml) — tabular, summary, matrix, or joined reports with columns, groupings, filters, charts, cross-filters, buckets, formulas, or time-frame filters. Triggers on "create a report", "build a report", "add a chart", or .report-meta.xml deploy errors. Do NOT trigger for Custom Report Type metadata (use platform-custom-report-type-generate), dashboards, list views, running reports in the UI, or SOQL.
How do I install platform-report-generate?
Run npx skills add https://github.com/forcedotcom/sf-skills --skill platform-report-generate 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/platform-report-generate/ (personal) or .claude/skills/platform-report-generate/ (project).
Which AI agents can use platform-report-generate?
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 platform-report-generate 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 platform-report-generate?
It is published by forcedotcom in forcedotcom/sf-skills. It has 2,951 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 docs & writing skills
grill-with-docs
mattpocock/skills
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
lark-markdown
open.feishu.cn
飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。
writing-beats
mattpocock/skills
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
writing-shape
mattpocock/skills
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
mattpocock/skills
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
mattpocock/skills
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.