/platform-sharing-rules-generate

name: platform-sharing-rules-generate
description: "Use this skill when users need to 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 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.2"
  minApiVersion: "60.0"
  relatedSkills:
    - "platform-custom-object-generate"
    - "platform-permission-set-generate"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"

Sharing Rules Generator

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, and deleting `sharingCriteriaRules`, `sharingOwnerRules`, and `sharingGuestRules` metadata; retrieving existing sharing rules from an org; appending new rules to existing files; modifying rule criteria, access levels, or shared-to targets; 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 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, shared-to target, criteria, label)

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 1 — Discover

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

2. **Check for existing sharing rules** — look for `<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml`. If found, read it to understand existing rules and avoid duplicates.

3. **If no local file exists**, retrieve from the org: `sf project retrieve start --metadata "SharingRules:<ObjectName>" --target-org <org>`

Phase 2 — Determine Operation and Rule Type

4. **Identify the operation** — determine whether the user wants to **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 Create:

8a. **Construct the XML** following the schema in `references/rule-types.md`. Key structure:

• One `.sharingRules-meta.xml` file per object
• All rules for the same object go in the same file
• If appending to an existing file, add the new rule element inside the existing `<SharingRules>` root

8b. **Name the rule** — derive `<fullName>` from the intent (PascalCase, no spaces, descriptive). Generate a matching `<label>` in Title Case with spaces.

For Edit:

8a. **Locate the target rule** — find the rule by `<fullName>` or `<label>` in the existing `.sharingRules-meta.xml` file.

8b. **Determine modifications** — identify which elements to change (e.g., `<accessLevel>`, `<sharedTo>`, `<criteriaItems>`, `<label>`) and what the new values will be. Do not write yet — all disk writes happen in Phase 5 after user confirmation.

For Delete:

8a. **Locate the target rule** — find the rule by `<fullName>` or `<label>` in the existing `.sharingRules-meta.xml` file.

8b. **Count remaining rules** — run: `grep -c '<sharingCriteriaRules>\|<sharingOwnerRules>\|<sharingGuestRules>' <file>` to get the total rule count. If the count is 1 (only the rule being deleted), the file must be removed entirely in Phase 5. Do not write yet — all disk writes happen in Phase 5 after user confirmation.

Phase 4 — Confirm with User CRITICAL

9. **Present a