sf-permissions Skill | Agent Skills

sf-permissions

Salesforce Permission Set analysis, visualization, and auditing tool

When to Use This Skill

Use sf-permissions when the user needs to:

Visualize Permission Set and Permission Set Group hierarchies
Find out "who has access to X?" (objects, fields, Apex classes, custom permissions)
Analyze what permissions a specific user has
Export Permission Set configurations for auditing
Generate Permission Set XML metadata
Grant agent access via <agentAccesses> element

Capabilities

| Capability | Description | |------------|-------------| | Hierarchy Viewer | Visualize all PS/PSG in an org as ASCII trees | | Permission Detector | Find which PS/PSG grant a specific permission | | User Analyzer | Show all permissions assigned to a user | | CSV Exporter | Export PS configuration for documentation | | Metadata Generator | Generate Permission Set XML (delegates to sf-metadata) | | Tooling API | Query tab settings, system permissions via Tooling API |

Prerequisites

pip install simple-salesforce rich  # Python dependencies
sf --version                         # Must be installed and authenticated
sf org display                       # Check current org

Phase 1: Understanding the Request

| User Says | Capability | Function | |-----------|------------|----------| | "Show permission hierarchy" | Hierarchy Viewer | hierarchy_viewer.py | | "Who has access to Account?" | Permission Detector | permission_detector.py | | "What permissions does John have?" | User Analyzer | user_analyzer.py | | "Export Sales_Manager PS to CSV" | CSV Exporter | permission_exporter.py | | "Generate PS XML with these permissions" | Metadata Generator | permission_generator.py |

Phase 2: Connecting to the Org

sf org list                          # List available orgs
sf org display --target-org <alias>  # Check specific org

# Run from sf-permissions/scripts/
from auth import get_sf_connection
sf = get_sf_connection('myorg')  # or None for default

Phase 3: Executing Queries

3.1 Permission Hierarchy Viewer

cd ~/.claude/plugins/marketplaces/sf-skills/sf-permissions/scripts
python cli.py hierarchy [--target-org ALIAS] [--format ascii|mermaid]

Output Example:

📦 ORG PERMISSION HIERARCHY
════════════════════════════════════════

📁 Permission Set Groups (3)
├── 🔒 Sales_Cloud_User (Active)
│   ├── View_All_Accounts
│   ├── Edit_Opportunities
│   └── Run_Reports
└── 🔒 Service_Cloud_User (Active)
    └── Case_Management

📁 Standalone Permission Sets (12)
├── Admin_Tools
├── API_Access
└── ... (10 more)

3.2 Permission Detector ("Who has access to X?")

Supported Permission Types: object, field, apex, vf, flow, custom, tab

python cli.py detect object Account --access delete
python cli.py detect field Account.AnnualRevenue --access edit
python cli.py detect apex MyApexClass
python cli.py detect custom Can_Approve_Expenses

3.3 User Permission Analyzer

python cli.py user "john.smith@company.com"
python cli.py user 005xx000001234AAA  # User ID also works

3.4 Permission Set Exporter

python cli.py export Sales_Manager --output /tmp/sales_manager.csv

3.5 Agent Access Permissions

See references/agent-access-guide.md for full <agentAccesses> XML structure, deploy steps, and visibility troubleshooting (missing icon, name mismatch, CopilotSalesforceUser PS).

Employee Agents require <agentAccesses> in a Permission Set — <agentName> must match the agent's developer_name exactly.

Phase 4: Rendering Output

ASCII Tree (Terminal): Uses rich library for trees, tables, panels
Mermaid Diagrams (Docs): python cli.py hierarchy --format mermaid > hierarchy.md

Phase 5: Generating Metadata

python cli.py generate \
    --name "New_Sales_PS" \
    --label "New Sales Permission Set" \
    --objects Account:crud,Opportunity:cru \
    --fields Account.AnnualRevenue:rw \
    --apex MyApexClass,AnotherClass \
    --output /tmp/New_Sales_PS.permissionset-meta.xml

Or delegate to sf-metadata for more complex generation.

SOQL Reference

See references/permission-soql-queries.md for the complete query catalog: Permission Set/Group queries, object permissions, field permissions, setup entity access (Apex, VF, Flows, Custom Permissions).

Quick queries:

-- All Permission Sets (non-profile)
SELECT Id, Name, Label FROM PermissionSet WHERE IsOwnedByProfile = false AND Type != 'Group'

-- User's PS Assignments
SELECT PermissionSetId, PermissionSet.Name FROM PermissionSetAssignment WHERE AssigneeId = '005...'

-- Find PS with delete access to Account
SELECT Parent.Name FROM ObjectPermissions WHERE SobjectType = 'Account' AND PermissionsDelete = true

Troubleshooting

| Issue | Solution | |-------|----------| | INVALID_SESSION_ID | Re-authenticate: sf org login web --alias myorg | | Slow queries | Filter by name: WHERE Name LIKE 'Sales%' | | Tab settings | Requires Tooling API: tooling_query(sf, ...) |

Common Workflows & Examples

See references/workflow-examples.md for detailed step-by-step workflows: audit "Who can delete Accounts?", troubleshoot user access, document a Permission Set, full org audit, security review, and PS creation examples.

Integration with Other Skills

| Skill | Integration | |-------|-------------| | sf-metadata | Generate Permission Set XML from analysis results | | sf-apex | Identify Apex classes to grant access to | | sf-deploy | Deploy generated Permission Sets | | sf-data | Query user assignments in bulk |

Agent Skills: sf-permissions

Install this agent skill to your local

Skill Files