more changes

skills/permission-set-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-permission-set-skill
-description: Generate correct, deployable Salesforce permission set metadata with proper object, field, user, and app permissions. Use when generating permission set metadata.
+description: Generates correct, deployable Salesforce permission set metadata (PermissionSet XML) with object, field, user, and app permissions. Use when creating or editing permission set metadata, PermissionSet XML, object permissions, field-level security (FLS), tab visibility, or deploying permission sets.
 license: Apache-2.0
 compatibility: Salesforce Metadata API v60.0+
 metadata:
@@ -10,11 +10,12 @@ metadata:
 
 ## When to Use This Skill
 
-Use when you need to generate metadata for a permission set or need to grant additional permissions such as:
-- Providing temporary or project-based access
-- Enabling feature-specific permissions
-- Implementing role-based access control
-- Extending profile permissions for specific user groups
+Use when generating or editing permission set metadata, or when granting object, field, user, and app permissions.
+
+## What Causes Deployment Failure
+
+- **Field permissions on required fields:** Any required field in `<fieldPermissions>` fails deployment. Required fields cannot have FLS; omit them entirely. Always confirm from object/field metadata that a field exists and is not required—never assume.
+- **Incorrect API names:** Using the wrong name or missing suffixes (e.g. missing `__c` for custom objects, fields, tabs) cause failure.
 
 ## Step 1: Define Core Properties
 
@@ -61,10 +62,18 @@ Define field permissions for sensitive or custom fields:
 ```
 
 **Important:**
-- Cannot set permissions on required fields, they are readable and editable by default
-- For custom objects, read and use the object metadata file to determine correct names of fields and if they are required
+- Required fields must NEVER appear in list of field permissions. Granting field-level security on required fields is not allowed by the platform and will cause deployment failure. 
+- Before adding any field, confirm from the object metadata that the field exists and is not required
+- A field is required when its metadata contains `<required>true</required>`:
+```xml
+<fields>
+    <fullName>FieldName__c</fullName>
+    <required>true</required>
+</fields>
+```
 - Use format `ObjectName.FieldName` for field references
 - Both `readable` and `editable` can be true (editable implies readable)
+- If all fields should be visible, can alternatively enable the "viewAllFields" object permission
 
 ## Step 4: Grant User Permissions
 
@@ -107,6 +116,9 @@ Make applications and tabs visible to users:
 </tabSettings>
 ```
 
+**Application visibility options:**
+- <visible> can be true or false
+
 **Tab visibility options:**
 - `Visible`: Always shown
 - `Available`: Available but not default
@@ -149,13 +161,11 @@ Specify license requirements and record type visibility:
 ## Validation Checklist
 
 Before deploying, verify:
-- [ ] All required fields (fullName, label, description) are set
-- [ ] Object permissions follow least privilege principle
-- [ ] No field permissions on required fields
-- [ ] System permissions (ViewAllData, ModifyAllData) are reviewed
-- [ ] No duplicate permissions within permission set
-- [ ] Description clearly states intended use case
-- [ ] Remove unnecessary comments, comments should be minimal and consice
+- [ ] fullName, label, description set
+- [ ] Permissions follow least privilege
+- [ ] No required fields in `<fieldPermissions>`
+- [ ] No duplicate permissions
+- [ ] no lengthy comments
 
 
 ## Deployment
@@ -169,5 +179,4 @@ sf project deploy start --metadata-dir force-app/main/default/permissionsets
 
 - **Granularity**: Create focused permission sets for specific purposes
 - **Documentation**: Maintain clear descriptions and naming
-- **Security**: Never grant excessive permissions like ModifyAllData without justification
-
+- **Security**: Never grant excessive permissions like ModifyAllData without justification