# Sync Permissions

> Reconcile the current project's Claude and Codex permission surfaces with the canonical global policy. Use when project permissions are missing, stale, or inconsistent after setup or migration. Not for syncing skills, hooks, or agents; use $sync-ai-infra.

- Skill: `flonat/sync-permissions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add flonat/sync-permissions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/flonat/sync-permissions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: flonat (https://skillmd.com/u/flonat)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/flonat/sync-permissions

---


# 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 `<skills-root>/` 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 `<skills-root>/` exists and has content:
- If missing or empty, warn: "Skills directory missing — run the documented managed-copy installer or deployment command"
- 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 the documented managed-copy installer or deployment command"
- 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 `web fetch` and `Skill(literature)` to `~/.claude/settings.json`:

```
Permissions sync complete:
- Global permissions: 25
- Local permissions (before): 64
- New permissions added: 2 — web fetch, 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