| 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
- Merge permissions — adds global permissions into project-local, keeping any project-specific ones
- Verify skills directory — ensures
~/.claude/skills/ exists and has content
- Verify agents directory — ensures
~/.claude/agents/ exists and has content
- 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:
- Read the full local settings file (preserve any non-permissions keys)
- Replace
permissions.allow with the merged array
- 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