/platform-sharing-rules-generate

name: platform-sharing-rules-generate
description: "Use this skill when users need to get, create, edit, delete, or manage Salesforce Sharing Rules metadata. TRIGGER when: users mention sharing rules, record sharing, criteria-based sharing, role-based sharing, guest user sharing, sharingRules, sharingCriteriaRules, sharingGuestRules, sharingOwnerRules, .sharingRules-meta.xml files, or ask to share records with specific roles or groups. Also trigger when users want to retrieve or view existing sharing rules from an org, modify or remove existing sharing rules, or update sharing rule criteria or access levels. DO NOT TRIGGER when user needs permission sets or profiles (use platform-permission-set-generate), or needs object-level security rather than record-level sharing (use platform-permission-set-generate)."
metadata:
  version: "1.3"
  minApiVersion: "60.0"
  relatedSkills:
    - "platform-custom-object-generate"
    - "platform-permission-set-generate"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"

Sharing Rules Generator

Get, create, edit, and delete Salesforce Sharing Rules metadata to control record-level access beyond org-wide defaults. Supports criteria-based rules, role/group-based owner rules, and guest user rules for Experience Sites.

Scope

• **In scope**: Creating, editing, deleting, and retrieving (getting) `sharingCriteriaRules`, `sharingOwnerRules`, and `sharingGuestRules` metadata; retrieving existing sharing rules from an org using the Metadata API Retrieve pattern; appending new rules to existing files; modifying rule criteria or access levels; removing rules from metadata files; configuring rules for Guest and Portal profiles.
• **Out of scope**: Changing org-wide defaults (OWD/sharing model), creating Experience Sites, configuring permission sets or profiles (use `platform-permission-set-generate`), territory-based sharing rules.

---

Clarifying Questions

Before proceeding, confirm with the user if not already clear:

For Get operations:

• Which object's sharing rules should be retrieved? (standard or custom object API name, or all objects)
• Which target org should the rules be retrieved from? (org alias or default)

For Create operations:

• Which object should the sharing rule apply to? (standard or custom object API name)
• What type of rule? (criteria-based, role/group-based owner rule, or guest user rule)
• Who should records be shared with? (role name, group, portal role, or guest user nickname)
• What access level? (Read or Read/Write)
• For criteria-based rules: what field conditions should match?

For Edit operations:

• Which existing rule should be modified? (rule fullName or label)
• What should change? (access level, criteria, label — note: `sharedTo` and `sharedFrom` cannot be edited in place)

For Delete operations:

• Which rule(s) should be removed? (rule fullName or label)
• Confirm the object the rule belongs to

---

Required Inputs

Gather or infer before proceeding:

• **Object API name**: The sObject the rule targets (e.g., `Account`, `Property__c`)
• **Rule type**: One of `sharingCriteriaRules`, `sharingOwnerRules`, or `sharingGuestRules`
• **Shared-to target**: Role, group, portal role, or guest user community nickname
• **Access level**: `Read` or `Edit` (maps to Read-Only or Read/Write)
• **Criteria** (for criteria/guest rules): Field name, operation, and value for each filter item

Defaults unless specified:

• Access level: `Read`
• `includeRecordsOwnedByAll`: `true` for criteria rules
• `includeHVUOwnedRecords`: `false` for guest rules
• Account sharing rules include `accountSettings` with all sub-access levels set to `None`

---

Workflow

Steps are sequential within each phase. Phase 3 branches by operation type — execute only the matching branch. Phase 4 applies to create, edit, and delete only (get operations end at Phase 3).

Phase 1 — Discover

1. **Resolve the SFDX project path** — find the project's `sfdx-project.json` and identify the package directory for `sharingRules/`.

2. **Always retrieve the latest sharing rules from the org** using the Metadata API Retrieve pattern:

   sf project retrieve start --metadata "SharingRules:<ObjectName>" --target-org <org>

This ensures the local file reflects the current org state. Never trust a local file that may be stale — edits or deletes against a stale file can recreate rules that were already removed in the org or overwrite changes made by other users.

3. **Read the retrieved file** — parse `<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml` to understand existing rules and avoid duplicates.

Phase 2 — Determine Operation and Rule Type

4. **Identify the operation** — determine whether the user wants to **get**, **create**, **edit**, or **delete** a sharing rule.

5. **Select the rule type** based on user intent. Read `references/rule-types.md` for the complete schema of each type and its required elements.

6. **For Account sharing rules**: the `accountSettings` element is required. Default sub-access levels to `None` unless the user specifies otherwise.

7. **For Guest rules**: the `sharedTo` must use `<guestUser>` with the site guest user's community nickname. Never use `<role>` or `<group>` for guest rules.

Phase 3 — Execute Operation

For Get:

8a. **Use the file already retrieved in Phase 1** — the retrieve in step 2 already pulled the latest `<ObjectName>.sharingRules-meta.xml` from the org. No additional retrieve is needed.

8b. **Read and present the retrieved rules** — parse the `.sharingRules-meta.xml` file and present the rules to the user in a readable format showing:

• Rule name (`fullName`) and label
• Rule type (criteria-based, owner-based, or guest)
• Access level
• Shared-to target
• Criteria (if applicable)

For get operations, skip Phase 4 (no write needed). The retrieve itself writes the metadata file to the local project.

For Create:

8a.