sync-permissions

name	sync-permissions
description	Use when you need to sync global permissions into the current project.
allowed-tools	Bash(jq*), Bash(ls*), Bash(test*), Bash(readlink*), Read, Write, Edit
argument-hint	(no arguments)

Update Rules Skill

Sync global permissions, skills, and agents into the current project without losing project-specific settings.

Purpose

The SessionStart hook only copies permissions when .claude/settings.local.json doesn't exist yet. After that, new global permissions never propagate to existing projects. This skill fills that gap — run it anytime to pull in new permissions additively.

When to Use

• After adding new permissions to ~/.claude/settings.json
• When starting work in a project that hasn't been updated in a while
• After creating a new skill and wanting it available everywhere
• When the user says "sync permissions", "update rules", "update my permissions"

What It Does

1. Merge permissions — adds global permissions into project-local, keeping any project-specific ones
2. Verify skills directory — ensures ~/.claude/skills/ exists and has content
3. Verify agents directory — ensures ~/.claude/agents/ exists and has content
4. Report changes — shows exactly what was added

What It Does NOT Do

• Never removes existing project permissions (additive only)
• Never modifies ~/.claude/settings.json (reads it, never writes)
• Never touches model, hooks, or other global settings keys

---

Workflow

Step 1: Read Both Permission Files

Read these two files:

• Global: ~/.claude/settings.json → extract permissions.allow array
• Local: .claude/settings.local.json → extract permissions.allow array

If the local file doesn't exist, create it with global permissions (same as the SessionStart hook).

Step 2: Compute the Union

Merge the two permission arrays:

• Start with all existing local permissions (preserve everything)
• Add any global permissions not already present in local
• Sort the final array for readability

The merge logic:

new_permissions = local_permissions ∪ global_permissions
added = new_permissions - local_permissions

Step 3: Write the Merged Result

If there are new permissions to add:

1. Read the full local settings file (preserve any non-permissions keys)
2. Replace permissions.allow with the merged array
3. Write back to .claude/settings.local.json

If no new permissions, skip the write.

Step 4: Verify Skills Directory

Check that ~/.claude/skills/ exists and has content:

• If missing or empty, warn: "Skills directory missing — run sync-to-claude-home.sh to populate"
• If present, report file count

Step 5: Verify Agents Directory

Check that ~/.claude/agents/ exists and has content:

• If missing or empty, warn: "Agents directory missing — run sync-to-claude-home.sh to populate"
• If present, report file count

Step 6: Report

Output a summary:

Permissions sync complete:
- Global permissions: [N]
- Local permissions (before): [N]
- New permissions added: [N] — [list them]
- Local permissions (after): [N]
- Skills directory: ✓ [N] files / ✗ missing
- Agents directory: ✓ [N] files / ✗ missing

If nothing changed:

Everything up to date. No new permissions to add. Skills OK. Agents OK.

---

Example

Running /sync-permissions after adding WebFetch and Skill(literature) to ~/.claude/settings.json:

Permissions sync complete:
- Global permissions: 25
- Local permissions (before): 64
- New permissions added: 2 — WebFetch, Skill(literature)
- Local permissions (after): 66
- Skills directory: ✓ 496 files
- Agents directory: ✓ 16 files

---

Safety

• Additive only — the skill can only add permissions, never remove them
• No global writes — global settings are read-only
• Directory check — verifies skills/agents directories exist and have content
• Idempotent — safe to run multiple times; re-running with no changes produces no writes