alirezarezvani/claude-skills / engineering/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/memory_and_adoption.md
View on GitHub# CLAUDE.md layering and measuring adoption
What Claude Code loads as instructions at session start, and how to tell
whether a rollout is being used without reading anyone's sessions.
Confidence key: π’ verified on code.claude.com/docs Β· π‘ observed locally, not documented Β· π΄ recommendation or design choice.
## 1. The layers
Loaded at launch, in this order: π’ [memory]
1. Managed: `/Library/Application Support/ClaudeCode/CLAUDE.md`, `/etc/claude-code/CLAUDE.md`, `C:\Program Files\ClaudeCode\CLAUDE.md`
2. User: `~/.claude/CLAUDE.md` (and `~/.claude/rules/`)
3. Every `CLAUDE.md` from the filesystem root down to the working directory,
concatenated root β cwd; `./CLAUDE.md` or `./.claude/CLAUDE.md` for the project
4. `CLAUDE.local.md`, after `CLAUDE.md` in each folder (current, not deprecated; gitignore it)
5. `.claude/rules/**/*.md`; a rule with `paths:` frontmatter loads only for matching files
`CLAUDE.md` files in subdirectories load on demand when Claude works there.
`AGENTS.md` is read only when there is no `CLAUDE.md`. π’ [memory]
## 2. Imports
`@path/to/file` imports another file, resolved relative to the importing file,
up to **4 hops** deep. Imports inside code spans and fenced blocks are ignored;
imports outside the project ask for approval once. π’ [memory]
A broken import fails silently: the instruction is simply not there.
`claude_md_layering_audit.py` resolves every import and reports broken ones,
cycles and anything past the hop limit.
## 3. Size
Files up to 4 MiB load in full and larger ones are skipped; the docs recommend
keeping each file under 200 lines. π’ [memory] Everything resident is sent with
every request, so a 25k-token CLAUDE.md is paid for on every turn of every
session. The script's default budget of 6,000 resident tokens is a heuristic,
not a documented limit. π΄
Move instructions that apply to part of the repo into `.claude/rules/` with a
`paths:` scope; that is also the fix for most "always X" vs "never X"
contradictions, which are usually true in different directories. π΄
## 4. What a shared memory file must not hold
- Credentials. Memory files are plaintext context sent to the model.
- Machine-specific paths (`/Users/alice/...`): wrong for everyone else.
- Personal preferences: those go in `~/.claude/CLAUDE.md` or `CLAUDE.local.md`.
## 5. Transcripts and retention
Session transcripts are JSONL at `~/.claude/projects/<project>/<session>.jsonl`;
prompt history is `~/.claude/history.jsonl`. They are plaintext and can contain
secrets that tools read. π’ [claude-directory] `cleanupPeriodDays` controls
retention (default 30, minimum 1). π’ [settings-reference]
The `<project>` folder name is the absolute path with `/` replaced by `-`. π‘
`adoption_tracker.py` reads these files locally and outputs only counts:
sessions, active days, prompts, tool calls by kind (built-in / MCP / skill),
skill and slash-command **names**, CLI versions. It never emits prompt text,
file contents, or tool inputs other than a skill name.
## 6. OpenTelemetry, for organizations that want a dashboard
Set `CLAUDE_CODE_ENABLE_TELEMETRY=1` and the `OTEL_*` exporter variables from
**managed or user** settings (repo files cannot enable them). π’ [monitoring, settings-reference]
Metrics include `claude_code.session.count`, `claude_code.lines_of_code.count`,
`claude_code.pull_request.count`, `claude_code.commit.count`,
`claude_code.cost.usage`, `claude_code.token.usage`,
`claude_code.code_edit_tool.decision` and `claude_code.active_time.total`.
Prompt and tool-content logging are separate opt-ins (`OTEL_LOG_USER_PROMPTS`,
`OTEL_LOG_TOOL_DETAILS`, ...); leave them off unless a data-protection review
says otherwise. π’ [monitoring]
Use OpenTelemetry when you already run a collector. Use the adoption tracker
when you do not, or when you only need a monthly read-out. π΄
## 7. Adoption stages
The thresholds below are this skill's design choice, chosen to be easy to
explain, not taken from a study. π΄ They borrow the shape of Rogers' diffusion
curve: early adopters first, then a majority, then routine use. [Rogers]
| Stage | Rule |
|---|---|
| PILOT | under 25% of seats active in the window |
| SPREADING | 25-60% active |
| EMBEDDED | 60%+ active and the median active member uses it 3+ days a week |
| STALLED | under 25% active, 6+ weeks after launch |
A stall is a rollout problem (access, onboarding, missing MCP servers, a policy
that blocks real work), not a people problem. Ask the inactive seats what
stopped them before adding more policy. π΄
## Sources
1. Claude Code docs β Memory (CLAUDE.md). https://code.claude.com/docs/en/memory
2. Claude Code docs β The .claude directory. https://code.claude.com/docs/en/claude-directory
3. Claude Code docs β Monitoring usage (OpenTelemetry). https://code.claude.com/docs/en/monitoring-usage
4. Claude Code docs β Settings reference. https://code.claude.com/docs/en/settings-reference
5. Claude Code docs β Environment variables. https://code.claude.com/docs/en/env-vars
6. Rogers, E. M. (2003). *Diffusion of Innovations*, 5th ed. Free Press.
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: 472k | 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 |