settings-sync

file	./.claude/skills/settings-sync/SKILL.md
name	settings-sync
description	Deterministic bi-directional sync between settings.local.json and settings.json. Local-only keys stay in local; all other keys are merged into both files.
scope	agent
updated-at	"2026-05-31T00:00:00.000Z"
allowed-tools	Read Edit Write

/settings-sync

Synchronize .claude/settings.local.json and .claude/settings.json so both files share all common keys. Local-only keys remain in settings.local.json only and are never written to settings.json.

Local-only keys

These keys are rejected by Claude Code when present in the git-tracked settings.json. They must live only in settings.local.json.

• autoMemoryDirectory
• autoMode
• useAutoModeDuringPlan

When merging: strip these keys from the settings.json output. Keep them in settings.local.json.

Rules

• settings.local.json always wins on conflicts for shared keys.
• Missing shared keys are filled from the other file.
• Local-only keys are never copied to settings.json.
• Result must be deterministic and idempotent.

Steps

1. Read files

Read .claude/settings.json and .claude/settings.local.json. If one does not exist, use the existing file as source and create the missing file (omitting local-only keys if creating settings.json).

2. Show diff

Classify keys into:

• only_local (not local-only key) -> will be added to shared
• only_local (local-only key) -> stays in local only, NOT copied to shared
• only_shared -> will be added to local
• conflict -> values differ (local will overwrite)
• same -> no change

Highlight conflicts and local-only keys clearly. Wait for user confirmation before writing.

3. Merge

For settings.json: start with all keys, add missing shared keys from local (excluding local-only), local overwrites on conflict, never include local-only keys.

For settings.local.json: start with all keys, add missing keys from shared, local overwrites.

Array merge rules (for permissions.allow / deny / ask): union + deduplicate, then:

• Wildcard consolidation: a specific entry is redundant if a wildcard in the same array covers it. Bash(mv *) covers Bash(mv "D:/some/path"). Remove redundant specifics.
• Proactive wildcard creation: if 2+ specific entries share an obvious common prefix and no wildcard exists, propose Tool(prefix *) and drop the specifics. Confirm before writing (wildcards widen scope).
• Dangerous commands -> put in ask, never deny, unless the user explicitly says "deny".

Hooks: merge by event name -> then by matcher; local overwrites on conflict.

4. Write

Write both files. They will NOT be identical: settings.local.json has local-only keys that settings.json does not. All shared keys must be identical after write.

5. Report

Report: keys added (local->shared), keys added (shared->local), local-only keys kept, conflicts resolved, redundant entries removed, wildcards introduced, unchanged keys.