tools-only sf-metadata: Salesforce Metadata Generation and Org Querying
Expert Salesforce administrator specializing in metadata architecture, security model design, and schema best practices. Generate production-ready metadata XML and query org structures using sf CLI v2.
Core Responsibilities
- Metadata Generation: Create Custom Objects, Fields, Profiles, Permission Sets, Validation Rules, Record Types, Page Layouts
- Org Querying: Describe objects, list fields, query metadata using sf CLI v2
- Validation & Scoring: Score metadata against 6 categories (0-120 points)
- Cross-Skill Integration: Provide metadata discovery for sf-apex and sf-flow
- Deployment Integration: Deploy metadata via sf-deploy skill
Document Map
| Need | Document | Description |
|---|---|---|
| PermSet auto-gen | references/permset-auto-generation.md | Phase 3.5 rules, field type filters, XML example |
| Scoring details | references/best-practices-scoring.md | 6-category breakdown, field template tips |
| Field & CLI ref | references/field-and-cli-reference.md | Field types, relationships, validation patterns, CLI commands |
| Naming | docs/naming-conventions.md | API name conventions |
| Orchestration | docs/orchestration.md | Extended orchestration patterns |
CRITICAL: Orchestration Order
sf-metadata → sf-flow → sf-deploy → sf-data (you are here: sf-metadata)
sf-data requires objects deployed to org. Always deploy BEFORE creating test data.
CRITICAL: Field-Level Security
Deployed fields are INVISIBLE until FLS is configured! Always prompt for Permission Set generation after creating objects/fields. See references/permset-auto-generation.md for auto-generation workflow.
Workflow (5-Phase Pattern)
Phase 1: Requirements Gathering
Use AskUserQuestion to gather:
- Operation type: Generate metadata OR Query org metadata
- If generating: Metadata type, target object, specific requirements
- If querying: Query type, target org alias, object name or metadata type
Then: Check existing metadata (Glob: **/*-meta.xml), verify sfdx-project.json exists.
Phase 2: Template Selection / Query Execution
For Generation
| Metadata Type | Template |
|---|---|
| Custom Object | templates/objects/custom-object.xml |
| Text/Number/Currency/Date/Checkbox Field | templates/fields/[type]-field.xml |
| Picklist / Multi-Select Picklist | templates/fields/picklist-field.xml / multi-select-picklist.xml |
| Lookup / Master-Detail | templates/fields/lookup-field.xml / master-detail-field.xml |
| Formula / Roll-Up Summary | templates/fields/formula-field.xml / rollup-summary-field.xml |
| Email/Phone/URL/Text Area | templates/fields/[type]-field.xml |
| Profile / Permission Set | templates/profiles/profile.xml / templates/permission-sets/permission-set.xml |
| Validation Rule / Record Type / Layout | templates/[type]/ |
Template Path Resolution (try in order):
- Marketplace:
~/.claude/plugins/marketplaces/sf-skills/sf-metadata/templates/[path] - Project:
[project-root]/sf-metadata/templates/[path]
For Querying (sf CLI v2)
| Query Type | Command |
|---|---|
| Describe object | sf sobject describe --sobject [Name] --target-org [alias] --json |
| List custom objects | sf org list metadata --metadata-type CustomObject --target-org [alias] --json |
| List metadata types | sf org list metadata-types --target-org [alias] --json |
See references/field-and-cli-reference.md for complete CLI commands and interactive generation.
Phase 3: Generation / Validation
File locations:
- Objects:
force-app/main/default/objects/[ObjectName__c]/[ObjectName__c].object-meta.xml - Fields:
force-app/main/default/objects/[ObjectName]/fields/[FieldName__c].field-meta.xml - Permission Sets:
force-app/main/default/permissionsets/[PermSetName].permissionset-meta.xml - Validation Rules:
force-app/main/default/objects/[ObjectName]/validationRules/[RuleName].validationRule-meta.xml
Validation Report Format:
Score: 105/120 ⭐⭐⭐⭐ Very Good
├─ Structure & Format: 20/20 (100%)
├─ Naming Conventions: 18/20 (90%)
├─ Data Integrity: 15/20 (75%)
├─ Security & FLS: 20/20 (100%)
├─ Documentation: 18/20 (90%)
└─ Best Practices: 14/20 (70%)
See references/best-practices-scoring.md for detailed category breakdowns and field template tips.
Phase 3.5: Permission Set Auto-Generation
See references/permset-auto-generation.md for the complete workflow, field type rules, and XML template.
Quick rules: Exclude required fields (auto-visible) and Name fields. Formula/Roll-Up fields get editable: false. Master-Detail controlled by parent.
Phase 4: Deployment
Skill(skill="sf-deploy", args="Deploy metadata at force-app/main/default/objects/[ObjectName] to [target-org]")
Post-deployment: sf org assign permset --name [ObjectName]_Access --target-org [alias]
Phase 5: Verification
Verify in Setup → Object Manager, check FLS for new fields, add to Page Layouts if needed.
Scoring (120 Points)
See references/best-practices-scoring.md for full criteria.
Categories: Structure & Format (20), Naming Conventions (20), Data Integrity (20), Security & FLS (20), Documentation (20), Best Practices (20).
Thresholds: 108+ Excellent | 96+ Good | 84+ Acceptable | <72 BLOCKED
Cross-Skill Integration
| From Skill | To sf-metadata | When |
|---|---|---|
| sf-apex | → sf-metadata | "Describe Invoice__c" (discover fields before coding) |
| sf-flow | → sf-metadata | "Describe object fields, record types, validation rules" |
| sf-data | → sf-metadata | "Describe Custom_Object__c fields" (discover structure) |
| From sf-metadata | To Skill | When |
|---|---|---|
| sf-metadata | → sf-deploy | "Deploy with --dry-run" |
| sf-metadata | → sf-flow | After creating objects/fields that Flow will reference |
Metadata Anti-Patterns
| Anti-Pattern | Fix |
|---|---|
| Profile-based FLS | Use Permission Sets for granular access |
| Hardcoded IDs in formulas | Use Custom Settings or Custom Metadata |
| Validation rule without bypass | Add $Permission.Bypass_Validation__c check |
| Too many picklist values (>200) | Consider Custom Object instead |
| Auto-number without prefix | Add meaningful prefix: INV-{0000} |
| No description on custom objects | Always document purpose |
Key Insights
| Insight | Issue | Fix |
|---|---|---|
| FLS is the Silent Killer | Deployed fields invisible without FLS | Always prompt for Permission Set generation |
| Required Fields ≠ Permission Sets | Salesforce rejects required fields in PS | Filter out required fields from fieldPermissions |
| Orchestration Order | sf-data fails if objects not deployed | sf-metadata → sf-flow → sf-deploy → sf-data |
Common Errors
| Error | Fix |
|---|---|
Cannot deploy to required field |
Remove from fieldPermissions (auto-visible) |
Field does not exist |
Create Permission Set with field access |
SObject type 'X' not supported |
Deploy metadata first |
Element X is duplicated |
Reorder XML elements alphabetically |
Validation
python3 ~/.claude/plugins/marketplaces/sf-skills/sf-metadata/hooks/scripts/validate_metadata.py <file_path>
Scoring: 120 points / 6 categories. Minimum 84 (70%) for deployment.
Dependencies
Docs: docs/ folder — metadata-types-reference, field-types-guide, fls-best-practices, naming-conventions
Required: sf-deploy (optional) for deployment | API 65.0 | Block if score < 72