Managed Settings

When an organization grows beyond a handful of developers, sharing skills through individual repositories is not enough. You need a way to distribute standardized skills, enforce policies, and ensure that every agent instance across the company operates within approved boundaries. This is the domain of managed settings — enterprise-grade configuration that administrators control centrally and individual users cannot override.

What Are Managed Settings?

Managed settings are configuration files deployed to developer machines through enterprise management tools like MDM (Mobile Device Management), Chef, Puppet, Ansible, or similar infrastructure. They live at a system-level path that the agent reads at startup, separate from the user's personal settings or project-level settings.

The key property of managed settings is their override priority. Managed settings take precedence over both personal and project-level settings. If the enterprise configuration says a particular tool is disallowed, no individual user or project setting can re-enable it. This creates a governance layer that administrators can rely on.

// Managed settings file location (macOS)
// /Library/Application Support/ClaudeCode/managed-settings.json
//
// Managed settings file location (Linux)
// /etc/claude-code/managed-settings.json

{
  "permissions": {
    "allowedTools": [
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep",
      "Bash"
    ],
    "deniedTools": [
      "WebFetch"
    ],
    "allowedDomains": [],
    "maxTokensPerRequest": 100000
  },
  "skills": {
    "managedSkillPaths": [
      "/opt/company/claude-skills/global/",
      "/opt/company/claude-skills/engineering/"
    ],
    "disableUserSkills": false,
    "requireApprovedSkillsOnly": false
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "/opt/company/scripts/compliance-check.sh "$CLAUDE_FILE_PATH""
      }
    ]
  },
  "policies": {
    "requireSkillReviewBeforeExecution": false,
    "auditLogPath": "/var/log/claude-code/audit.jsonl",
    "maxConcurrentSubagents": 3
  }
}

This configuration demonstrates the breadth of managed settings. The administrator controls tool access, skill discovery paths, compliance hooks, and audit logging — all from a single JSON file that gets deployed to every developer machine.

Enterprise Skill Distribution

The managedSkillPaths array points to directories on the local filesystem where enterprise skills are installed. These paths are scanned at startup, and any skills found there are loaded with the highest priority — above both personal and project-level skills.

Enterprise skills are typically deployed via package managers or configuration management. The skills directory is updated centrally, and every developer gets the latest versions on their next agent startup without any manual action.

Override Policies

Managed settings support fine-grained control over what users and projects can customize versus what is locked down by the administrator. The override model follows a clear hierarchy:

• Managed settings (highest priority) — Administrators control these. Users cannot modify or override them.
• Project settings (.claude/settings.json) — Project-level configuration that applies to everyone working in that repository. Can be overridden by managed settings.
• User settings (~/.claude/settings.json) — Personal preferences. Lowest priority, overridden by both project and managed settings.

// Example: Managed settings restrict tool access
// managed-settings.json
{
  "permissions": {
    "deniedTools": ["WebFetch", "Bash"]
  }
}

// Project settings try to allow Bash
// .claude/settings.json
{
  "permissions": {
    "allowedTools": ["Bash"]
  }
}

// Result: Bash remains DENIED because managed settings
// take precedence. The project cannot override the
// enterprise restriction.

The disableUserSkills flag is a particularly powerful override. When set to true, the agent ignores any skills in the user's personal ~/.claude/skills directory. This ensures that only enterprise-approved and project-level skills are available, preventing users from introducing unapproved automation.

The requireApprovedSkillsOnly flag goes even further. When enabled, the agent only loads skills from the managedSkillPaths. Both personal skills and project-level skills are ignored. This is the strictest mode, suitable for highly regulated environments.

Enterprise Skill Governance

Organizations that invest in managed skills need a governance process to maintain quality and security. This typically involves:

Centralized Review Process

Establish a review workflow for new enterprise skills, similar to how you review internal libraries or shared packages. A typical process looks like this:

1. An engineer authors a new skill and tests it in their project.
2. They submit the skill to a central repository (e.g., an internal Git repo dedicated to enterprise skills).
3. A platform or DevEx team reviews the skill for correctness, security implications, and adherence to organizational standards.
4. Approved skills are tagged with a version and deployed to managedSkillPaths via the organization's configuration management pipeline.
5. Developers automatically receive the updated skill on next startup.

Audit Logging

The auditLogPath setting directs the agent to write structured logs of every skill invocation, tool call, and significant action. In regulated industries, this audit trail can be essential for compliance.

// Example audit log entries (one JSON object per line)
{"timestamp":"2025-03-15T14:32:01Z","event":"skill_invoked","skill":"security-review","user":"alice","project":"payments-api"}
{"timestamp":"2025-03-15T14:32:05Z","event":"tool_call","tool":"Read","path":"src/auth/jwt.ts","skill":"security-review","user":"alice"}
{"timestamp":"2025-03-15T14:32:12Z","event":"tool_call","tool":"Grep","pattern":"password|secret|key","skill":"security-review","user":"alice"}
{"timestamp":"2025-03-15T14:32:18Z","event":"skill_completed","skill":"security-review","user":"alice","duration_ms":17000}

Deployment Automation

For organizations managing hundreds or thousands of developer machines, manual skill deployment is not feasible. Here is a typical automation pipeline using common infrastructure tools:

Multi-Team Configuration

Large organizations often need different skill sets for different teams. The backend team needs database migration skills while the frontend team needs component scaffolding skills. Managed settings support this through team-specific skill paths:

// managed-settings.json for backend team
{
  "skills": {
    "managedSkillPaths": [
      "/opt/company/claude-skills/global/",
      "/opt/company/claude-skills/backend/"
    ]
  }
}

// managed-settings.json for frontend team
{
  "skills": {
    "managedSkillPaths": [
      "/opt/company/claude-skills/global/",
      "/opt/company/claude-skills/frontend/"
    ]
  }
}

// managed-settings.json for SRE team
{
  "skills": {
    "managedSkillPaths": [
      "/opt/company/claude-skills/global/",
      "/opt/company/claude-skills/infrastructure/"
    ]
  }
}

All teams share the global/ skills (security review, compliance headers, incident response) while receiving team-specific skills tailored to their domain. The configuration management system deploys the appropriate managed settings file based on the team assignment.

What's Next

Managed settings provide enterprise-grade skill governance within an organization. The next lesson covers plugin skills — how to package and distribute skills as reusable plugins that can be shared across organizations through npm, Git repositories, and other public or private registries.