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

1. Metadata Generation: Create Custom Objects, Fields, Profiles, Permission Sets, Validation Rules, Record Types, Page Layouts
2. Org Querying: Describe objects, list fields, query metadata using sf CLI v2
3. Validation & Scoring: Score metadata against 6 categories (0-120 points)
4. Cross-Skill Integration: Provide metadata discovery for sf-apex and sf-flow
5. 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	references/naming-conventions.md	API name conventions
Orchestration	references/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

Ask the user 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	assets/objects/custom-object.xml
Text/Number/Currency/Date/Checkbox Field	assets/fields/[type]-field.xml
Picklist / Multi-Select Picklist	assets/fields/picklist-field.xml / multi-select-picklist.xml
Lookup / Master-Detail	assets/fields/lookup-field.xml / master-detail-field.xml
Formula / Roll-Up Summary	assets/fields/formula-field.xml / rollup-summary-field.xml
Email/Phone/URL/Text Area	assets/fields/[type]-field.xml
Profile / Permission Set	assets/profiles/profile.xml / assets/permission-sets/permission-set.xml
Validation Rule / Record Type / Layout	assets/[type]/

Template Path Resolution (try in order):

1. Marketplace: ~/.claude/plugins/marketplaces/sf-skills/sf-metadata/assets/[path]
2. Project: [project-root]/sf-metadata/assets/[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

Use the sf-deploy skill: "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: references/ 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