settings-management

name	settings-management
description	Configure Claude Code behavior via .claude/settings.json — hooks, MCP servers, custom commands, agents, and global options. Trigger on /settings-management, or when tuning Claude Code configuration.
user-invocable	true
allowed-tools	Read, Grep, Glob, Bash, Edit

Settings Management

Claude Code is configured via .claude/settings.json at the project root.

Configuration Sections

{
  "hooks": { ... },
  "mcpServers": { ... },
  "commands": [ ... ],
  "agents": [ ... ],
  "skills": [ ... ],
  "customCommands": [ ... ],
  "allowedTools": { ... },
  "permissions": { ... }
}

Key Settings

permissions

Control what the agent can do without asking:

{
  "permissions": {
    "allow": ["Bash", "Read", "Edit", "Write", "Glob", "Grep"],
    "allowEdit": ["*.ts", "*.js", "*.json", "*.md"],
    "deny": ["rm", "git push --force"]
  }
}

Custom Commands

Define slash commands for common tasks:

{
  "customCommands": [
    {
      "name": "build",
      "description": "Build the project",
      "prompt": "Run the build command and fix any errors.",
      "command": "pnpm build"
    },
    {
      "name": "test-file",
      "description": "Run tests for a specific file",
      "prompt": "Run tests for @:file and fix any failures.",
      "command": "pnpm test -- --run @:file",
      "withFiles": true
    }
  ]
}

Agents

Define persistent autonomous agents — Claude that runs continuously on a task:

{
  "agents": [
    {
      "name": "monitor",
      "description": "Background file watcher",
      "command": "node watch.mjs",
      "restart": "always"
    }
  ]
}

Rules

• Keep settings.json in version control (without secrets).
• Use .env files or environment variables for sensitive values.
• Test configuration changes with claude --debug.
• Do not add settings that override project conventions.
• Document non-obvious settings with comments (JSON5 supports comments).

Experience Log

This skill learns from experience. Mechanism:

• Read .claude/experience/settings-management.md at skill start to benefit from past lessons.

• Write to .claude/experience/settings-management.md after use if you learned something new.

• Format: YYYY-MM-DD: <lesson> — one line per entry.

• Evolve: If the same issue repeats 3+ times, update this SKILL.md itself.

This skill improves over time. After each use, append lessons learned.

Record format: YYYY-MM-DD: <lesson> Read this at skill start to apply past lessons.