Update Config Skill

Modify Claude Code configuration by updating settings.json files.

When Hooks Are Required (Not Memory)

If the user wants something to happen automatically in response to an EVENT, they need a hook configured in settings.json. Memory/preferences cannot trigger automated actions.

These require hooks:

• "Before compacting, ask me what to preserve" → PreCompact hook
• "After writing files, run prettier" → PostToolUse hook with Write|Edit matcher
• "When I run bash commands, log them" → PreToolUse hook with Bash matcher
• "Always run tests after code changes" → PostToolUse hook

Hook events: PreToolUse, PostToolUse, PreCompact, PostCompact, Stop, Notification, SessionStart

CRITICAL: Read Before Write

Always read the existing settings file before making changes. Merge new settings with existing ones - never replace the entire file.

CRITICAL: Use AskUserQuestion for Ambiguity

When the user's request is ambiguous, use AskUserQuestion to clarify:

• Which settings file to modify (user/project/local)
• Whether to add to existing arrays or replace them
• Specific values when multiple options exist

Decision: /config command vs Direct Edit

Suggest the /config slash command for these simple settings:

• theme, editorMode, verbose, model
• language, alwaysThinkingEnabled
• permissions.defaultMode

Edit settings.json directly for:

• Hooks (PreToolUse, PostToolUse, etc.)
• Complex permission rules (allow/deny arrays)
• Environment variables
• MCP server configuration
• Plugin configuration

Workflow

1. Clarify intent - Ask if the request is ambiguous
2. Read existing file - Use Read tool on the target settings file
3. Merge carefully - Preserve existing settings, especially arrays
4. Edit file - Use Edit tool (if file doesn't exist, ask user to create it first)
5. Confirm - Tell user what was changed

Merging Arrays (Important!)

When adding to permission arrays or hook arrays, merge with existing, don't replace:

WRONG (replaces existing permissions):

{ "permissions": { "allow": ["Bash(npm *)"] } }

RIGHT (preserves existing + adds new):

{
  "permissions": {
    "allow": [
      "Bash(git *)",      // existing
      "Edit(.claude)",    // existing
      "Bash(npm *)"       // new
    ]
  }
}

Settings File Locations

Choose the appropriate file based on scope:

Settings load in order: user → project → local (later overrides earlier).

Settings Schema Reference

Permissions

{
  "permissions": {
    "allow": ["Bash(npm *)", "Edit(.claude)", "Read"],
    "deny": ["Bash(rm -rf *)"],
    "ask": ["Edit(//etc/*)"],
    "defaultMode": "default" | "plan" | "acceptEdits" | "dontAsk",
    "additionalDirectories": ["/extra/dir"]
  }
}

Permission Rule Syntax:

• Exact match: "Bash(npm run test)"
• Prefix wildcard: "Bash(git *)" - matches git, git status, git commit, etc.
• Tool only: "Read" - allows all Read operations
• File paths: "Edit(src/**)" - path rules in permissions use Edit(path) for every file-writing tool (Write, Edit, NotebookEdit) and Read(path) for reads. Write(path), NotebookEdit(path) and Glob(path) rules are not matched by file permission checks. Bare tool names ("Write"), deny/ask Tool(param:value) rules and hook if conditions still use each tool's own name

Environment Variables

{
  "env": {
    "DEBUG": "true",
    "MY_API_KEY": "value"
  }
}

Model & Agent

{
  "model": "sonnet",  // or "fable", "opus", "haiku", full model ID
  "agent": "agent-name",
  "alwaysThinkingEnabled": true
}

Attribution (Commits & PRs)

{
  "attribution": {
    "commit": "Custom commit trailer text",
    "pr": "Custom PR description text"
  }
}

Set commit or pr to empty string "" to hide that attribution. To hide all of it, set both to "" and also set "sessionUrl": false. Write this object form, not "attribution": false: older Claude Code versions reject true or false here and then skip the whole settings file.

MCP Server Management

{
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["server1", "server2"],
  "disabledMcpjsonServers": ["blocked-server"]
}

Plugins

{
  "enabledPlugins": {
    "formatter@anthropic-tools": true
  }
}

Plugin syntax: plugin-name@source where source is claude-code-marketplace, claude-plugins-official, or builtin.

Other Settings

• language: Preferred response language (e.g., "japanese")
• cleanupPeriodDays: Days to keep transcripts before automatic cleanup (default: 30; minimum 1)
• respectGitignore: Whether to respect .gitignore (default: true)
• spinnerTipsEnabled: Show tips in spinner
• timeFormat: Clock format for times shown in the UI: "auto" (default), "12-hour", "24-hour", "24-hour-utc", or a strftime pattern such as "%H:%M"
• timeZone: IANA time zone for times shown in the UI, e.g. "UTC" (default: system time zone)
• spinnerVerbs: Customize spinner verbs ({ "mode": "append" | "replace", "verbs": [...] })
• spinnerTipsOverride: Override spinner tips ({ "excludeDefault": true, "tips": ["Custom tip"] })
• syntaxHighlightingDisabled: Disable diff highlighting

Hooks Configuration

Hooks run commands at specific points in Claude Code's lifecycle.

Hook Structure

{
  "hooks": {
    "EVENT_NAME": [
      {
        "matcher": "ToolName|OtherTool",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here",
            "timeout": 60,
            "statusMessage": "Running..."
          }
        ]
      }
    ]
  }
}

Hook Events

Common tool matchers: Bash, Write, Edit, Read, Glob, Grep

Hook Types

1. Command Hook - Runs a shell command:

{ "type": "command", "command": "prettier --write $FILE", "timeout": 30 }

2. Prompt Hook - Evaluates a condition with LLM:

{ "type": "prompt", "prompt": "Is this safe? $ARGUMENTS" }

Only available for tool events: PreToolUse, PostToolUse, PermissionRequest.

3. Agent Hook - Runs an agent with tools:

{ "type": "agent", "prompt": "Verify tests pass: $ARGUMENTS" }

Only available for tool events: PreToolUse, PostToolUse, PermissionRequest.

Hook Input (stdin JSON)

{
  "session_id": "abc123",
  "tool_name": "Write",
  "tool_input": { "file_path": "/path/to/file.txt", "content": "..." },
  "tool_response": { "success": true }  // PostToolUse only
}

Hook JSON Output

Hooks can return JSON to control behavior:

{
  "systemMessage": "Warning shown to user in UI",
  "continue": false,
  "stopReason": "Message shown when blocking",
  "suppressOutput": false,
  "decision": "block",
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Context injected back to model"
  }
}

Fields:

• systemMessage - Display a message to the user (all hooks)
• continue - Set to false to block/stop (default: true)
• stopReason - Message shown when continue is false
• suppressOutput - Hide stdout from transcript (default: false)
• decision - "block" for PostToolUse/Stop/UserPromptSubmit hooks (deprecated for PreToolUse, use hookSpecificOutput.permissionDecision instead)
• reason - Explanation for decision
• hookSpecificOutput - Event-specific output (must include hookEventName):
• additionalContext - Text injected into model context
• permissionDecision - "allow", "deny", or "ask" (PreToolUse only)
• permissionDecisionReason - Reason for the permission decision (PreToolUse only)
• updatedInput - Modified tool input (PreToolUse only)

Common Patterns

Auto-format after writes:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true"
      }]
    }]
  }
}

Log all bash commands:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
      }]
    }]
  }
}

Stop hook that displays message to user:

Command must output JSON with systemMessage field:

# Example command that outputs: {"systemMessage": "Session complete!"}
echo '{"systemMessage": "Session complete!"}'

Run tests after code changes:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path // .tool_response.filePath' | grep -E '\\.(ts|js)$' && npm test || true"
      }]
    }]
  }
}

Constructing a Hook (with verification)

Given an event, matcher, target file, and desired behavior, follow this flow. Each step catches a different failure class — a hook that silently does nothing is worse than no hook.

1. Dedup check. Read the target file. If a hook already exists on the same event+matcher, show the existing command and ask: keep it, replace it, or add alongside.

1. Construct the command for THIS project — don't assume. The hook receives JSON on stdin. Build a command that:

• Extracts any needed payload safely — use jq -r into a quoted variable or { read -r f; ... "$f"; }, NOT unquoted | xargs (splits on spaces)
• Invokes the underlying tool the way this project runs it (npx/bunx/yarn/pnpm? Makefile target? globally-installed?)
• Skips inputs the tool doesn't handle (formatters often have --ignore-unknown; if not, guard by extension)
• Stays RAW for now — no || true, no stderr suppression. You'll wrap it after the pipe-test passes.

1. Pipe-test the raw command. Synthesize the stdin payload the hook will receive and pipe it directly:

• Pre|PostToolUse on Write|Edit: echo '{"tool_name":"Edit","tool_input":{"file_path":"<a real file from this repo>"}}' | <cmd>
• Pre|PostToolUse on Bash: echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | <cmd>
• Stop/UserPromptSubmit/SessionStart: most commands don't read stdin, so echo '{}' | <cmd> suffices

Check exit code AND side effect (file actually formatted, test actually ran). If it fails you get a real error — fix (wrong package manager? tool not installed? jq path wrong?) and retest. Once it works, wrap with 2>/dev/null || true (unless the user wants a blocking check).

1. Write the JSON. Merge into the target file (schema shape in the "Hook Structure" section above). If this creates .claude/settings.local.json for the first time, add it to .gitignore — the Write tool doesn't auto-gitignore it.

1. Validate syntax + schema in one shot:

jq -e '.hooks.<event>[] | select(.matcher == "<matcher>") | .hooks[] | select(.type == "command") | .command' <target-file>

Exit 0 + prints your command = correct. Exit 4 = matcher doesn't match. Exit 5 = malformed JSON or wrong nesting. A broken settings.json silently disables ALL settings from that file — fix any pre-existing malformation too.

1. Prove the hook fires — only for Pre|PostToolUse on a matcher you can trigger in-turn (Write|Edit via Edit, Bash via Bash). Stop/UserPromptSubmit/SessionStart fire outside this turn — skip to step 7.

For a formatter on PostToolUse/Write|Edit: introduce a detectable violation via Edit (two consecutive blank lines, bad indentation, missing semicolon — something this formatter corrects; NOT trailing whitespace, Edit strips that before writing), re-read, confirm the hook fixed it. For anything else: temporarily prefix the command in settings.json with echo "$(date) hook fired" >> /tmp/claude-hook-check.txt; , trigger the matching tool (Edit for Write|Edit, a harmless true for Bash), read the sentinel file.

Always clean up — revert the violation, strip the sentinel prefix — whether the proof passed or failed.

If proof fails but pipe-test passed and jq -e passed: the settings watcher isn't watching .claude/ — it only watches directories that had a settings file when this session started. The hook is written correctly. Tell the user to open /hooks once (reloads config) or restart — you can't do this yourself; /hooks is a user UI menu and opening it ends this turn.

1. Handoff. Tell the user the hook is live (or needs /hooks/restart per the watcher caveat). Point them at /hooks to review, edit, or disable it later. The UI only shows "Ran N hooks" if a hook errors or is slow — silent success is invisible by design.

Example Workflows

Adding a Hook

User: "Format my code after Claude writes it"

1. Clarify: Which formatter? (prettier, gofmt, etc.)
2. Read: .claude/settings.json (or create if missing)
3. Merge: Add to existing hooks, don't replace
4. Result:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true"
      }]
    }]
  }
}

Adding Permissions

User: "Allow npm commands without prompting"

1. Read: Existing permissions
2. Merge: Add Bash(npm *) to allow array
3. Result: Combined with existing allows

Environment Variables

User: "Set DEBUG=true"

1. Decide: User settings (global) or project settings?
2. Read: Target file
3. Merge: Add to env object

{ "env": { "DEBUG": "true" } }

Common Mistakes to Avoid

1. Replacing instead of merging - Always preserve existing settings
2. Wrong file - Ask user if scope is unclear
3. Invalid JSON - Validate syntax after changes
4. Forgetting to read first - Always read before write

Troubleshooting Hooks

If a hook isn't running:

1. Check the settings file - Read ~/.claude/settings.json or .claude/settings.json
2. Verify JSON syntax - Invalid JSON silently fails
3. Check the matcher - Does it match the tool name? (e.g., "Bash", "Write", "Edit")
4. Check hook type - Is it "command", "prompt", or "agent"?
5. Test the command - Run the hook command manually to see if it works
6. Use --debug - Run claude --debug to see hook execution logs

Full Settings JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "$schema": {
      "description": "JSON Schema reference for Claude Code settings",
      "type": "string"
    },
    "apiKeyHelper": {
      "description": "Path to a script that outputs authentication values",
      "type": "string"
    },
    "proxyAuthHelper": {
      "description": "Shell command that outputs a Proxy-Authorization header value (EAP)",
      "type": "string"
    },
    "awsCredentialExport": {
      "description": "Path to a script that exports AWS credentials",
      "type": "string"
    },
    "awsAuthRefresh": {
      "description": "Path to a script that refreshes AWS authentication",
      "type": "string"
    },
    "gcpAuthRefresh": {
      "description": "Command to refresh GCP authentication (e.g., gcloud auth application-default login)",
      "type": "string"
    },
    "processWrapper": {
      "description": "Corporate launcher argv prefix for the background-agent supervisor, the sessions and workers it hosts, and the other covered background processes listed in the Claude Code corporate-launcher documentation. Equivalent to the CLAUDE_CODE_PROCESS_WRAPPER environment variable, which takes precedence when set. Honored from managed settings, a --settings/SDK-supplied settings file, and user settings, in that precedence order; project and local settings are ignored.",
      "type": "string"
    },
    "policyHelper": {
      "description": "Executable that computes managed settings at startup. Honored only from admin-controlled policy sources.",
      "type": "object",
      "properties": {
        "path": {
          "description": "Absolute path to the helper executable",
          "type": "string"
        },
        "timeoutMs": {
          "type": "integer",
          "minimum": 1000,
          "maximum": 9007199254740991
        },
        "refreshIntervalMs": {
          "anyOf": [
            {
              "type": "number",
              "const": 0
            },
            {
              "type": "integer",
              "minimum": 60000,
              "maximum": 9007199254740991
            }
          ]
        }
      },
      "required": [
        "path"
      ]
    },
    "fileSuggestion": {
      "description": "Custom file suggestion configuration for @ mentions",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "command"
        },
        "command": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "command"
      ]
    },
    "respectGitignore": {
      "description": "Whether file picker should respect .gitignore files (default: true). Note: .ignore files are always respected.",
      "type": "boolean"
    },
    "cleanupPeriodDays": {
      "description": "Number of days to retain chat transcripts before automatic cleanup (default: 30). Minimum 1. Use a large value for long retention; use --no-session-persistence to disable transcript writes entirely.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "desktopSessionCleanupPeriodDays": {
      "description": "Retention ceiling in days for session transcripts created or last written by a desktop-host surface (Claude Desktop, Cowork), which are otherwise exempt from the cleanupPeriodDays sweep. 0 (the default) means no ceiling: such transcripts are kept until deleted another way. Unlike cleanupPeriodDays, 0 is allowed because this setting never disables writes — it only bounds an exemption from deletion. The ceiling is a hard cap: it also bounds an active archive grace, so the grace window of a release marker never keeps files past the ceiling. Ignored when cleanupPeriodDays is managed by org policy. A ceiling at or below cleanupPeriodDays effectively disables the exemption: those transcripts age out on the regular cleanupPeriodDays schedule, so the effective retention is whichever of the two periods is longer.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "syncClaudeAiSkills": {
      "description": "Set to false to turn off syncing of the skills you have enabled on claude.ai. In your user settings (or managed settings): nothing more is downloaded, previously synced skills (~/.claude/skills/synced) can no longer be run, are hidden from every session started afterwards, and are moved to ~/.claude/skills/.trash at the next launch (deleted after cleanupPeriodDays; re-downloaded, not restored, if you re-enable). In .claude/settings.local.json or --settings: downloads stop and synced skills are blocked and hidden for sessions in that workspace or invocation only (nothing is moved). Not read from project settings (.claude/settings.json). Only false is honored — the feature is enabled server-side for your account, so setting true does not turn it on early. While it is on, synced skills are available in every session, re-synced about every 10 minutes while a session is in use and a quarter as often otherwise, and removed when you disable them on claude.ai. Only applies when signed in with your Claude account.",
      "type": "boolean"
    },
    "syncClaudeAiPlugins": {
      "description": "Set to false to turn off syncing of the plugins you have enabled on claude.ai. In your user settings (or managed settings): nothing more is downloaded, previously synced plugins (~/.claude/plugins/synced) are hidden from every session started afterwards and moved to ~/.claude/plugins/.trash at the next launch (deleted after cleanupPeriodDays; re-downloaded, not restored, if you re-enable). In .claude/settings.local.json or --settings: downloads stop and synced plugins are hidden for sessions in that workspace or invocation only (nothing is moved). Not read from project settings (.claude/settings.json). Only false is honored — the feature is enabled server-side for your account, so setting true does not turn it on early. While it is on, synced plugins load in every session like plugins you installed yourself (a plugin you installed with the same name takes precedence), are re-synced at each launch, and are removed when you disable them on claude.ai. Only applies when signed in with your Claude account.",
      "type": "boolean"
    },
    "skillListingMaxDescChars": {
      "description": "Per-skill description character cap in the skill listing sent to Claude (default: 1536). Descriptions longer than this are truncated. Raise to opt in to higher per-turn context cost.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "skillListingBudgetFraction": {
      "description": "Fraction of the context window (in characters) reserved for the skill listing sent to Claude (default: 0.01 = 1%). When the listing exceeds this, descriptions are shortened to fit. Raise to opt in to higher per-turn context cost.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1
    },
    "wslInheritsWindowsSettings": {
      "description": "When set to true in either admin-only Windows source — the HKLM SOFTWARE/Policies/ClaudeCode registry key or C:/Program Files/ClaudeCode/managed-settings.json — WSL reads managed settings from the full Windows policy chain (HKLM, C:/Program Files/ClaudeCode via DrvFs, HKCU) in addition to /etc/claude-code. Windows sources take priority. The flag is also required in HKCU itself for HKCU policy to apply on WSL (double opt-in: admin enables the chain, user confirms HKCU). On native Windows the flag has no effect.",
      "type": "boolean"
    },
    "env": {
      "description": "Environment variables to set for Claude Code se