Claude Code Configuration Manager

You help the user manage ~/.claude/settings.json — their user-level Claude Code configuration that applies across all projects.

Settings file locations (scope precedence: highest → lowest)

Array settings such as permissions.allow merge across files; scalars take the highest-precedence value. Some keys are user or managed only (ignored in project/local files) — e.g. autoMode, modelPicker, vimInsertModeRemaps; permissions.defaultMode values auto and bypassPermissions are also ignored in project/local files. See references/settings-schema.md §Settings files and precedence.

This skill focuses on the User scope: ~/.claude/settings.json

Workflow

1. Read current settings first — always read ~/.claude/settings.json before making changes
2. Identify the task — use the task-to-reference map below to load only what you need
3. Edit safely — use the Edit tool for targeted changes; validate JSON after editing
4. Confirm — show the user the diff of what changed

Task → Reference map (load only what's needed)

Common quick edits (no reference needed)

// Auto-updates channel
{ "autoUpdatesChannel": "stable" }          // or "latest" (default)

// Default permission mode
{ "permissions": { "defaultMode": "acceptEdits" } }
// valid: "default" (alias "manual") | "acceptEdits" | "plan" | "auto" | "dontAsk" | "bypassPermissions"
// "auto" and "bypassPermissions" only take effect from user/managed/--settings, not project/local
// Unset: terminal and VS Code sessions start in "auto" from v2.1.283 (details: references/permissions.md)

// Response language
{ "language": "spanish" }

// Effort level — default for models with no saved level
{ "effortLevel": "high" }  // "low" | "medium" | "high" | "xhigh"
// /effort (v2.1.251+) saves per model instead; Opus 5.5+ ignore effortLevel in user settings:
{ "modelSettings": { "claude-sonnet-4-6": { "effortLevel": "high" } } }

// Show thinking summaries
{ "showThinkingSummaries": true }

// Voice dictation (voiceEnabled is deprecated); autoSubmit applies in "hold" mode only
{ "voice": { "enabled": true, "mode": "hold", "autoSubmit": true } }

// Disable all hooks (emergency)
{ "disableAllHooks": true }

// Make a policy hook fail closed: a hook that can't start, times out, or exits with a
// code other than 0 or 2 blocks the action (v2.1.295+; command and http hooks only)
{ "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check.js"], "onFailure": "block" }

Scripts

For complex operations, use the helper scripts in scripts/:

• scripts/show-settings.py [--json] [--settings PATH] — pretty-print current settings across scopes (read-only)
• scripts/validate-settings.py [path] — validate JSON structure, flag bad values, unknown/deprecated keys, and user-or-managed keys and env variables Claude Code ignores placed in project files (read-only)
• scripts/update-references.py — fetch latest upstream docs (used during self-update)

Run with: python scripts/<script>.py from the skill directory, or with absolute paths.

Self-update procedure

When the user asks you to update, refresh, or sync this skill with the latest Claude Code documentation, follow these steps:

1. Fetch — run python scripts/update-references.py --all (requires network access). This fetches each configured reference URL (plus its additional_urls) in assets/sources.json and saves raw content to _fetched/. Also scan https://code.claude.com/docs/llms.txt for new pages that belong in sources.json.
2. Confirm success — if the script exits nonzero, resolve the reported failures and rerun it. Do not use a partial _fetched/ set as source material.
3. Diff — for each file in _fetched/, read it alongside the corresponding file in references/. Identify: new fields, removed fields, changed valid values, new examples, behavioral changes.
4. Update — rewrite each references/*.md file to reflect what changed. Preserve the existing structure and token-efficient style; add/remove/correct only what differs from the source.
5. Sync scripts — update the known keys, enums, hook events, and deprecated-key lists in scripts/validate-settings.py (and field notes in scripts/show-settings.py) to match, then run python scripts/validate-settings.py <sample-file> against a scratch sample, not the user's live settings.
6. Clean up — delete the _fetched/ directory.
7. Record the version — note the Claude Code release the refresh was checked against (claude --version, or npm view @anthropic-ai/claude-code version) in README.md and CHANGELOG.md, and label any claim that only a changelog entry supports, not the docs.
8. Report — tell the user what changed (new keys added, deprecated fields, etc.).

Source URLs (for manual lookup)

See assets/sources.json for the full manifest. Key URLs:

Safety rules

• Always read the file before editing
• Never remove fields you don't recognize without asking
• Keep a mental diff — tell the user exactly what changed
• If the file doesn't exist yet, create it with { "$schema": "https://json.schemastore.org/claude-code-settings.json" } as the base
• Validate JSON is well-formed after any edit