/audit-permissions

name: audit-permissions
description: >-
  This skill should be used when the user asks to "audit claude permissions",
  "audit permissions", "review local claude settings", "promote permissions to global",
  "clean up claude settings", "find permission patterns", or wants to identify
  project-local Claude Code permissions that should be added to global configuration.
allowed-tools:
  # Scripts
  - Bash(*/audit-permissions/scripts/*)
  - Bash(readlink *)
  # Global settings
  - Read(~/.claude/settings.json)
  - Edit(~/.claude/settings.json)
  - Write(~/.claude/settings.json)
  # Local settings (per-project)
  - Read(**/.claude/settings.local.json)
  - Edit(**/.claude/settings.local.json)
  - Write(**/.claude/settings.local.json)
  # User preferences
  - Read(~/.claude/cc-maintenance.local.md)
  - Edit(~/.claude/cc-maintenance.local.md)
  - Write(~/.claude/cc-maintenance.local.md)
  # Policy detection
  - Read(~/.claude/CLAUDE.md)

Audit Claude Permissions

Scan project-local Claude Code settings files, aggregate permission patterns, and recommend promotions to global configuration.

Workflow Overview

This audit runs in three phases, each as a separate task. Use TaskCreate at the start to create all three tasks, then work through them sequentially with user input via AskUserQuestion.

• **Phase 1: Promote to Global** — Requires user judgment. Present candidates, get decisions, apply to global config.
• **Phase 2: Automated Redundancy Cleanup** — Script-driven. After Phase 1 promotions, run cleanup script to remove local permissions now covered by global. Present for sanity-checking, then apply.
• **Phase 3: Judgment Calls** — Everything requiring user input: security hygiene, policy conflicts, one-off cruft, empty file deletion, moderate-risk items.

Initial Setup

1. **Check for symlinked global settings:**

readlink -f ~/.claude/settings.json

If the global settings file is a symlink, note the real path. All writes to `~/.claude/settings.json` must edit the symlink target, not create a new file that replaces the symlink.

2. **Load user preferences** from `~/.claude/cc-maintenance.local.md` (if it exists). See User Preferences section below. Apply any configured defaults (risk tolerance, auto-cleanup preference).

3. **Read global CLAUDE.md** from `~/.claude/CLAUDE.md` to identify tool preference policies for Phase 3 policy conflict detection.

4. **Run the discovery and extraction pipeline:**

scripts/discover-settings.sh | xargs scripts/extract-permissions.py

5. **Read the actual global settings** from `~/.claude/settings.json` — compare against the real allow list, not just the static examples in this skill.

6. **Create tasks** for the three phases:

TaskCreate: "Review and promote permissions to global config"
TaskCreate: "Automated redundancy cleanup"
TaskCreate: "Judgment calls: security, policy, and cruft"

7. **Analyze the data** and categorize permissions (see Categorization Rules below).

---

Phase 1: Promote to Global

**Goal:** Identify permissions worth adding to global config and get user approval.

Present Findings

Show a summary table of promotion candidates:

## Promotion Candidates

### Strong Recommendations (safe patterns, multiple projects)

| Permission | Projects | Suggested Global Pattern |
| ---------- | -------- | ------------------------ |
| ...        | ...      | ...                      |

### Moderate Recommendations (review carefully)

| Permission | Projects | Notes |
| ---------- | -------- | ----- |
| ...        | ...      | ...   |

### Cross-Project File Patterns

[If any Read/Write/Edit permissions reference paths outside their project directory
and appear in multiple projects, flag them here. Example: multiple projects have
`Write(~/.config/some-tool/config.json)` - might indicate a shared config worth
adding globally.]

Get User Decision

Use AskUserQuestion to let the user decide:

Question: "Which permissions should I add to global settings?"
Options:
- "Add all strong recommendations"
- "Add strong + moderate recommendations"
- "Let me pick specific ones" (then list individually)
- "Skip - don't add any"

Apply Changes

If user approves additions:

1. Add selected permissions to `~/.claude/settings.json` (or symlink target) 2. Respect existing logical groupings (git, nix, gh, etc.) 3. Sort alphabetically within groups 4. Use space-syntax: `Bash(cmd *)` not `Bash(cmd:*)` 5. Mark Phase 1 task as completed

---

Phase 2: Automated Redundancy Cleanup

**Goal:** Remove local permissions now covered by global config. This is mechanical — the script identifies exact matches; user just sanity-checks the list.

Preview Cleanup

Run the cleanup script in dry-run mode:

scripts/discover-settings.sh | scripts/cleanup-redundant.py

Present Findings

Show what would be removed:

## Redundant Permissions

| File      | Permissions to Remove | Remaining |
| --------- | --------------------- | --------- |
| project-a | 5 (ls _, grep _, ...) | 12        |
| project-b | 3 (gh api \*, ...)    | 8         |
| ...       | ...                   | ...       |

**Total:** X permissions across Y files

The script also normalizes any remaining colon-syntax (`Bash(cmd:*)`) to space-syntax (`Bash(cmd *)`) when applying.

Get User Decision

If `auto_cleanup_redundant: true` in user preferences, skip the question and apply directly (still show the summary). Otherwise:

Question: "Should I remove these redundant permissions from local files?"
Options:
- "Yes, clean them up"
- "Show me the full list first"
- "Skip cleanup"

Apply Changes

If user approves:

scripts/discover-settings.sh | scripts/cleanup-redundant.py --apply

Mark Phase 2 task as completed.

---

Phase 3: Judgment Calls

**Goal:** Everything that requires real user judgment — security risks, policy conflicts, stale cruft, and cleanup opportunities. Pre