Agent-Skills.md

Agent Skills: sf-metadata: Salesforce Metadata Generation and Org Querying

>

UncategorizedID: Jaganpro/sf-skills/sf-metadata

Repository

Jaganpro/sf-skills
JaganproLicense: MIT
6514

Install this agent skill to your local

pnpm dlx add-skill https://github.com/Jaganpro/sf-skills/tree/HEAD/skills/sf-metadata

Skill Files

Browse the full folder contents for sf-metadata.

Download Skill

Loading file tree…

skills/sf-metadata/SKILL.md

Skill Metadata

Name
sf-metadata
Description
>

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 66.0 | Block if score < 72