alirezarezvani/claude-skills / engineering/coding-agent-rollout/skills/coding-agent-rollout
coding-agent-rollout
FlaggedRoll out Claude Code to a team: shared or managed settings, MCP and plugin approval, layered CLAUDE.md, adoption. Use whenever the user sets up Claude Code for their team or org, or asks if a rollout or settings file is right.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.0 KB |
| assets/approved-components.example.json | config | 249 B |
| assets/managed-settings.example.json | config | 865 B |
| assets/rollout_plan.md | markdown | 2.0 KB |
| references/mcp_and_plugin_governance.md | markdown | 4.2 KB |
| references/memory_and_adoption.md | markdown | 5.0 KB |
| references/settings_and_permissions.md | markdown | 6.0 KB |
| scripts/adoption_tracker.py | script | 11.7 KB |
| scripts/claude_md_layering_audit.py | script | 11.9 KB |
| scripts/mcp_plugin_inventory.py | script | 10.2 KB |
| scripts/settings_linter.py | script | 16.5 KB |
references/settings_and_permissions.md
View on GitHub# Settings and permissions for a team
How Claude Code combines settings files, how permission rules are evaluated,
and which keys only mean something in managed settings. Every key name here is
checked against the official docs; `settings_linter.py` encodes the same facts.
Confidence key: π’ verified on code.claude.com/docs Β· π‘ observed locally, not documented Β· π΄ recommendation.
## 1. Five scopes, one effective policy
| Scope | File | Who controls it |
|---|---|---|
| Managed | macOS `/Library/Application Support/ClaudeCode/managed-settings.json`, Linux/WSL `/etc/claude-code/managed-settings.json`, Windows `C:\Program Files\ClaudeCode\managed-settings.json`, plus `managed-settings.d/*.json` drop-ins | IT / MDM |
| Command line | `--settings <file-or-json>` | whoever launches |
| Project local | `.claude/settings.local.json` | one person, not committed |
| Shared project | `.claude/settings.json` | the repo, via code review |
| User | `~/.claude/settings.json` | one person |
Precedence, highest first: managed > command line > project local > shared
project > user. π’ [settings] Within managed, remote/server-managed beats MDM
(macOS plist domain `com.anthropic.claudecode`, Windows `HKLM\SOFTWARE\Policies\ClaudeCode`)
beats files beats `HKCU`; `managedSourcesBehavior: "merge"` combines them. π’ [managed-settings]
A managed file that exists but does not parse stops Claude Code from starting. π’ [managed-settings]
**Arrays merge, they do not override.** `permissions.allow` from user settings
is added to the project's list. π’ [settings] This is the single most common
team surprise: a strict shared file does not make a permissive user file stricter.
## 2. Permission evaluation
- Order: **deny, then ask, then allow; first match wins**; specificity does not
matter. An allow cannot carve an exception out of a deny, and an ask beats a
more specific allow. π’ [permissions]
- A deny at any level cannot be overridden by another level; a managed deny
cannot be overridden by `--allowedTools`. π’ [permissions]
- Project `permissions.allow` and `additionalDirectories` take effect only after
the workspace trust dialog is accepted; deny and ask apply immediately. π’ [permissions]
### Rule syntax that matters for linting
| Form | Meaning |
|---|---|
| `Bash(npm run test *)` | prefix match; legacy `Bash(npm run test:*)` is equivalent only at the end of the pattern π’ |
| `Read(./.env)` / `Read(//**/.env)` | gitignore syntax; `//` absolute, `~/` home, `/` relative to the settings file's source, `./` relative to cwd π’ |
| `WebFetch(domain:example.com)` | that host only; `domain:*.example.com` covers subdomains, not the apex; `domain:*` is every domain π’ |
| `mcp__server`, `mcp__server__*`, `mcp__server__tool` | valid MCP forms; an `mcp__` rule with parentheses is skipped π’ |
| `"*"` or `"mcp__*"` in **allow** | ignored; valid only in deny/ask π’ |
Rules that try to constrain shell arguments are documented as fragile. π’ [permissions]
Treat a `Bash(...)` allow as "this command family runs unprompted", not as a
sandbox, and put destructive families on `ask` or `deny`. π΄
## 3. Modes and the switches that disable them
`permissions.defaultMode`: `default` (alias `manual`), `acceptEdits`, `plan`,
`auto`, `dontAsk`, `bypassPermissions`. π’ [settings-reference]
`auto` and `bypassPermissions` are **ignored** when set in project or local
files. π’ [settings] `settings_linter.py` reports them there as dead config.
`permissions.disableBypassPermissionsMode` and `permissions.disableAutoMode`
take the string `"disable"`. They are valid in any file, but only enforced
fleet-wide from managed settings; with bypass disabled, Claude Code rejects
`--dangerously-skip-permissions`. π’ [settings-reference]
## 4. Managed-only keys
Meaningful only from managed sources (selection): `allowManagedPermissionRulesOnly`,
`allowManagedHooksOnly`, `allowManagedMcpServersOnly`, `managedMcpServers`,
`strictKnownMarketplaces`, `blockedMarketplaces`, `strictPluginOnlyCustomization`
(`true` or a list of `skills`, `agents`, `hooks`, `mcp`), `disableSideloadFlags`,
`forceRemoteSettingsRefresh`, `sandbox.network.allowManagedDomainsOnly`. π’ [managed-settings]
Three settings for a locked-down organization, in the order to adopt them: π΄
1. `allowManagedHooksOnly` β hooks run arbitrary commands on every tool call.
2. `allowManagedMcpServersOnly` with an `allowedMcpServers` list.
3. `allowManagedPermissionRulesOnly` β only once the managed allow list is good
enough that nobody needs a local rule to get work done.
## 5. Secrets and telemetry from repo files
- An `env` block in project or local settings **cannot** turn telemetry on
(`CLAUDE_CODE_ENABLE_TELEMETRY`, `OTEL_*` exporters and content flags) or set
`CLAUDE_CONFIG_DIR`, `HOME`, `TMPDIR`, `XDG_*`; only "off" values apply. π’ [settings-reference]
- Opt-outs: `DISABLE_TELEMETRY` (any non-empty value), `DISABLE_ERROR_REPORTING`,
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` (updates, telemetry, error reporting,
feedback, release notes, feature flags). π’ [env-vars]
- Credentials belong in `apiKeyHelper` or the platform's secret store, never in
a committed `env` block. π΄
## 6. Local-file hygiene
Claude Code adds `.claude/settings.local.json` to the global git excludes when
it writes it. π’ [settings] If one is tracked anyway, someone added it on
purpose or before that behaviour existed; `settings_linter.py` blocks on it.
## Sources
1. Claude Code docs β Settings. https://code.claude.com/docs/en/settings
2. Claude Code docs β Settings reference. https://code.claude.com/docs/en/settings-reference
3. Claude Code docs β Permissions. https://code.claude.com/docs/en/permissions
4. Claude Code docs β Managed settings. https://code.claude.com/docs/en/managed-settings
5. Claude Code docs β Environment variables. https://code.claude.com/docs/en/env-vars
6. Claude Code docs β Security. https://code.claude.com/docs/en/security
7. NIST SP 800-53 Rev. 5, AC-6 Least Privilege. https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why β repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" β or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself β your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |