coding-agent-rollout

# Claude Code Team Rollout

> **Portability:** 4 stdlib scripts, no network, no LLM calls. They read config and counts; they change nothing.

One engineer's Claude Code setup is a preference. A team's is a policy. Settings
merge from five scopes, `permissions.allow` arrays combine across files, and
deny beats ask beats allow wherever it is written, so nobody can read the
effective policy from a single file. This skill makes it readable, then checks it.

## Workflow

```bash
# 1 - Guardrails: lint shared, local and managed settings together.
python scripts/settings_linter.py --repo . --managed /etc/claude-code/managed-settings.json
# 2 - Inventory: every MCP server, plugin and marketplace, against your approved list.
python scripts/mcp_plugin_inventory.py --repo . --allowlist approved.json
# 3 - Instructions: what CLAUDE.md actually loads, layer by layer.
python scripts/claude_md_layering_audit.py --repo .
# 4 - Adoption: each member runs this locally and shares only the JSON counts.
python scripts/adoption_tracker.py --member alice --output json > alice.json
python scripts/adoption_tracker.py --merge *.json --seats 12 --weeks-since-launch 6
```

Start from [`assets/managed-settings.example.json`](assets/managed-settings.example.json):
bypass mode disabled, secrets denied, risky commands on `ask`, managed hooks
only, an MCP and marketplace allowlist. Ship it through MDM before the first
seat; policy added after habits form becomes a negotiation.

## What blocks (exit 4)

- Blanket shell allows (`Bash`, `Bash(*)`) and pre-approved destructive commands
  (force push, `rm -rf`, `sudo`, pipe-to-shell, publish, infra apply).
- A literal credential in a shared settings `env` block, a committed `.mcp.json`, or a committed CLAUDE.md.
- `.claude/settings.local.json` committed to git.
- An MCP server, plugin or marketplace missing from the approved list.

Warnings cover dead rules (an allow that a deny shadows, `mcp__*` in allow),
`enableAllProjectMcpServers`, unpinned `npx` servers, plain-http remotes,
network-calling hooks, broken or too-deep `@imports`, duplicated or
contradictory instructions, and resident CLAUDE.md size.

## Hard rules

1. **Policy lives in managed settings.** Project files cannot enable bypass mode
   or telemetry, and a team guardrail in a file anyone can edit is a suggestion.
2. **Approve MCP servers by name, URL or command, never by `enableAllProjectMcpServers`.**
3. **Pin what runs.** Unpinned `npx`/`uvx` servers and unpinned marketplaces change under you.
4. **Never collect transcripts.** Share the adoption JSON (counts only); transcripts are plaintext and can hold secrets.
5. **Report findings, not verdicts on people.** Adoption is a team metric; inactive seats are a rollout question, not a performance one.
6. **Settings keys change fast.** An unknown key is INFO; check the settings reference before calling it a typo.

## Scripts

| Script | Role | Exit codes |
|---|---|---|
| `scripts/settings_linter.py` | S1-S12 across shared, local, user and managed scopes | 0 · 2 warn · 3 bad input · 4 blocker |
| `scripts/mcp_plugin_inventory.py` | One table of servers, plugins, marketplaces; M1-M6 | 0 · 2 · 3 · 4 |
| `scripts/claude_md_layering_audit.py` | Resident vs on-demand layers, imports (4 hops), L1-L11 | 0 · 2 · 3 · 4 |
| `scripts/adoption_tracker.py` | Member counts; team stage PILOT / SPREADING / EMBEDDED / STALLED | 0 · 2 stalled · 3 |

All support `--sample` and `--output json`.

## References and assets

- [`references/settings_and_permissions.md`](references/settings_and_permissions.md) — scopes, precedence, rule syntax, managed-only keys (7 sources)
- [`references/mcp_and_plugin_governance.md`](references/mcp_and_plugin_governance.md) — MCP scopes, allowlists, marketplaces, pinning (6 sources)
- [`references/memory_and_adoption.md`](references/memory_and_adoption.md) — CLAUDE.md layering, transcripts, OpenTelemetry, adoption stages (6 sources)
- [`assets/managed-settings.example.json`](assets/managed-settings.example.json) — baseline team policy
- [`assets/approved-components.example.json`](assets/approved-components.example.json) — allowlist format for step 2
- [`assets/rollout_plan.md`](assets/rollout_plan.md) — four-phase plan with exit criteria per phase

[repo path | managed-settings.json | 'measure adoption']

{
  "format": "aiskill/v1",
  "skill": {
    "name": "coding-agent-rollout",
    "slug": "coding-agent-rollout",
    "version": "1.0.0",
    "description": "Use when rolling Claude Code out to a team or organization, or auditing a rollout already under way — writing or reviewing shared and managed settings.json permissions, deciding which MCP servers, plugins and marketplaces to approve, cleaning up layered CLAUDE.md files, or measuring whether the team actually uses it. Lints settings across scopes, inventories every MCP server and plugin against an approved list, resolves CLAUDE.md layers and imports, and turns local session data into privacy-safe adoption counts.",
    "category": "Development",
    "tags": [
      "ai-agents",
      "mcp",
      "agents",
      "content"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Claude Code Team Rollout\r\n\r\n> **Portability:** 4 stdlib scripts, no network, no LLM calls. They read config and counts; they change nothing.\r\n\r\nOne engineer's Claude Code setup is a preference. A team's is a policy. Settings\r\nmerge from five scopes, `permissions.allow` arrays combine across files, and\r\ndeny beats ask beats allow wherever it is written, so nobody can read the\r\neffective policy from a single file. This skill makes it readable, then checks it.\r\n\r\n## Workflow\r\n\r\n```bash\r\n# 1 - Guardrails: lint shared, local and managed settings together.\r\npython scripts/settings_linter.py --repo . --managed /etc/claude-code/managed-settings.json\r\n# 2 - Inventory: every MCP server, plugin and marketplace, against your approved list.\r\npython scripts/mcp_plugin_inventory.py --repo . --allowlist approved.json\r\n# 3 - Instructions: what CLAUDE.md actually loads, layer by layer.\r\npython scripts/claude_md_layering_audit.py --repo .\r\n# 4 - Adoption: each member runs this locally and shares only the JSON counts.\r\npython scripts/adoption_tracker.py --member alice --output json > alice.json\r\npython scripts/adoption_tracker.py --merge *.json --seats 12 --weeks-since-launch 6\r\n```\r\n\r\nStart from [`assets/managed-settings.example.json`](assets/managed-settings.example.json):\r\nbypass mode disabled, secrets denied, risky commands on `ask`, managed hooks\r\nonly, an MCP and marketplace allowlist. Ship it through MDM before the first\r\nseat; policy added after habits form becomes a negotiation.\r\n\r\n## What blocks (exit 4)\r\n\r\n- Blanket shell allows (`Bash`, `Bash(*)`) and pre-approved destructive commands\r\n  (force push, `rm -rf`, `sudo`, pipe-to-shell, publish, infra apply).\r\n- A literal credential in a shared settings `env` block, a committed `.mcp.json`, or a committed CLAUDE.md.\r\n- `.claude/settings.local.json` committed to git.\r\n- An MCP server, plugin or marketplace missing from the approved list.\r\n\r\nWarnings cover dead rules (an allow that a deny shadows, `mcp__*` in allow),\r\n`enableAllProjectMcpServers`, unpinned `npx` servers, plain-http remotes,\r\nnetwork-calling hooks, broken or too-deep `@imports`, duplicated or\r\ncontradictory instructions, and resident CLAUDE.md size.\r\n\r\n## Hard rules\r\n\r\n1. **Policy lives in managed settings.** Project files cannot enable bypass mode\r\n   or telemetry, and a team guardrail in a file anyone can edit is a suggestion.\r\n2. **Approve MCP servers by name, URL or command, never by `enableAllProjectMcpServers`.**\r\n3. **Pin what runs.** Unpinned `npx`/`uvx` servers and unpinned marketplaces change under you.\r\n4. **Never collect transcripts.** Share the adoption JSON (counts only); transcripts are plaintext and can hold secrets.\r\n5. **Report findings, not verdicts on people.** Adoption is a team metric; inactive seats are a rollout question, not a performance one.\r\n6. **Settings keys change fast.** An unknown key is INFO; check the settings reference before calling it a typo.\r\n\r\n## Scripts\r\n\r\n| Script | Role | Exit codes |\r\n|---|---|---|\r\n| `scripts/settings_linter.py` | S1-S12 across shared, local, user and managed scopes | 0 · 2 warn · 3 bad input · 4 blocker |\r\n| `scripts/mcp_plugin_inventory.py` | One table of servers, plugins, marketplaces; M1-M6 | 0 · 2 · 3 · 4 |\r\n| `scripts/claude_md_layering_audit.py` | Resident vs on-demand layers, imports (4 hops), L1-L11 | 0 · 2 · 3 · 4 |\r\n| `scripts/adoption_tracker.py` | Member counts; team stage PILOT / SPREADING / EMBEDDED / STALLED | 0 · 2 stalled · 3 |\r\n\r\nAll support `--sample` and `--output json`.\r\n\r\n## References and assets\r\n\r\n- [`references/settings_and_permissions.md`](references/settings_and_permissions.md) — scopes, precedence, rule syntax, managed-only keys (7 sources)\r\n- [`references/mcp_and_plugin_governance.md`](references/mcp_and_plugin_governance.md) — MCP scopes, allowlists, marketplaces, pinning (6 sources)\r\n- [`references/memory_and_adoption.md`](references/memory_and_adoption.md) — CLAUDE.md layering, transcripts, OpenTelemetry, adoption stages (6 sources)\r\n- [`assets/managed-settings.example.json`](assets/managed-settings.example.json) — baseline team policy\r\n- [`assets/approved-components.example.json`](assets/approved-components.example.json) — allowlist format for step 2\r\n- [`assets/rollout_plan.md`](assets/rollout_plan.md) — four-phase plan with exit criteria per phase",
    "user_template": "[repo path | managed-settings.json | 'measure adoption']"
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The coding-agent-rollout/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/coding-agent-rollout",
    "exported_at": "2026-11-03T07:41:02.490Z"
  }
}

format: aiskill/v1
skill:
  name: coding-agent-rollout
  slug: coding-agent-rollout
  version: 1.0.0
  description: >-
    Use when rolling Claude Code out to a team or organization, or auditing a rollout already under
    way — writing or reviewing shared and managed settings.json permissions, deciding which MCP
    servers, plugins and marketplaces to approve, cleaning up layered CLAUDE.md files, or measuring
    whether the team actually uses it. Lints settings across scopes, inventories every MCP server
    and plugin against an approved list, resolves CLAUDE.md layers and imports, and turns local
    session data into privacy-safe adoption counts.
  category: Development
  tags:
    - ai-agents
    - mcp
    - agents
    - content
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Claude Code Team Rollout\r\n\r\n> **Portability:** 4 stdlib scripts, no network, no LLM calls. They read config and counts; they change nothing.\r\n\r\nOne engineer's Claude Code setup is a preference. A team's is a policy. Settings\r\nmerge from five scopes, `permissions.allow` arrays combine across files, and\r\ndeny beats ask beats allow wherever it is written, so nobody can read the\r\neffective policy from a single file. This skill makes it readable, then checks it.\r\n\r\n## Workflow\r\n\r\n```bash\r\n# 1 - Guardrails: lint shared, local and managed settings together.\r\npython scripts/settings_linter.py --repo . --managed /etc/claude-code/managed-settings.json\r\n# 2 - Inventory: every MCP server, plugin and marketplace, against your approved list.\r\npython scripts/mcp_plugin_inventory.py --repo . --allowlist approved.json\r\n# 3 - Instructions: what CLAUDE.md actually loads, layer by layer.\r\npython scripts/claude_md_layering_audit.py --repo .\r\n# 4 - Adoption: each member runs this locally and shares only the JSON counts.\r\npython scripts/adoption_tracker.py --member alice --output json > alice.json\r\npython scripts/adoption_tracker.py --merge *.json --seats 12 --weeks-since-launch 6\r\n```\r\n\r\nStart from [`assets/managed-settings.example.json`](assets/managed-settings.example.json):\r\nbypass mode disabled, secrets denied, risky commands on `ask`, managed hooks\r\nonly, an MCP and marketplace allowlist. Ship it through MDM before the first\r\nseat; policy added after habits form becomes a negotiation.\r\n\r\n## What blocks (exit 4)\r\n\r\n- Blanket shell allows (`Bash`, `Bash(*)`) and pre-approved destructive commands\r\n  (force push, `rm -rf`, `sudo`, pipe-to-shell, publish, infra apply).\r\n- A literal credential in a shared settings `env` block, a committed `.mcp.json`, or a committed CLAUDE.md.\r\n- `.claude/settings.local.json` committed to git.\r\n- An MCP server, plugin or marketplace missing from the approved list.\r\n\r\nWarnings cover dead rules (an allow that a deny shadows, `mcp__*` in allow),\r\n`enableAllProjectMcpServers`, unpinned `npx` servers, plain-http remotes,\r\nnetwork-calling hooks, broken or too-deep `@imports`, duplicated or\r\ncontradictory instructions, and resident CLAUDE.md size.\r\n\r\n## Hard rules\r\n\r\n1. **Policy lives in managed settings.** Project files cannot enable bypass mode\r\n   or telemetry, and a team guardrail in a file anyone can edit is a suggestion.\r\n2. **Approve MCP servers by name, URL or command, never by `enableAllProjectMcpServers`.**\r\n3. **Pin what runs.** Unpinned `npx`/`uvx` servers and unpinned marketplaces change under you.\r\n4. **Never collect transcripts.** Share the adoption JSON (counts only); transcripts are plaintext and can hold secrets.\r\n5. **Report findings, not verdicts on people.** Adoption is a team metric; inactive seats are a rollout question, not a performance one.\r\n6. **Settings keys change fast.** An unknown key is INFO; check the settings reference before calling it a typo.\r\n\r\n## Scripts\r\n\r\n| Script | Role | Exit codes |\r\n|---|---|---|\r\n| `scripts/settings_linter.py` | S1-S12 across shared, local, user and managed scopes | 0 · 2 warn · 3 bad input · 4 blocker |\r\n| `scripts/mcp_plugin_inventory.py` | One table of servers, plugins, marketplaces; M1-M6 | 0 · 2 · 3 · 4 |\r\n| `scripts/claude_md_layering_audit.py` | Resident vs on-demand layers, imports (4 hops), L1-L11 | 0 · 2 · 3 · 4 |\r\n| `scripts/adoption_tracker.py` | Member counts; team stage PILOT / SPREADING / EMBEDDED / STALLED | 0 · 2 stalled · 3 |\r\n\r\nAll support `--sample` and `--output json`.\r\n\r\n## References and assets\r\n\r\n- [`references/settings_and_permissions.md`](references/settings_and_permissions.md) — scopes, precedence, rule syntax, managed-only keys (7 sources)\r\n- [`references/mcp_and_plugin_governance.md`](references/mcp_and_plugin_governance.md) — MCP scopes, allowlists, marketplaces, pinning (6 sources)\r\n- [`references/memory_and_adoption.md`](references/memory_and_adoption.md) — CLAUDE.md layering, transcripts, OpenTelemetry, adoption stages (6 sources)\r\n- [`assets/managed-settings.example.json`](assets/managed-settings.example.json) — baseline team policy\r\n- [`assets/approved-components.example.json`](assets/approved-components.example.json) — allowlist format for step 2\r\n- [`assets/rollout_plan.md`](assets/rollout_plan.md) — four-phase plan with exit criteria per phase"
  user_template: "[repo path | managed-settings.json | 'measure adoption']"
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The coding-agent-rollout/ folder
        contains SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/coding-agent-rollout
  exported_at: "2026-11-03T07:41:02.490Z"