handbooksRolling out to a team
A staged rollout. What to do this week for yourself, this month for your project, and this quarter for your organization, with the thresholds that tell you when to move to the next stage.
- Roll this out in three stages: yourself, then your project, then your organization. Do not start at stage three.
- Each stage has a benchmark that tells you when to move to the next one.
- Governance has real weight: skill scanning, managed settings, plugin-only lockdown. Turn it on when you need it, not by default.
- Do not reach for a plugin and a managed marketplace before a project even has a shared
settings.json. Start smaller.
Stage 1: this week, just you
Follow Set up in 20 minutes: a personal CLAUDE.md, a personal settings.json with a hard deny on .env, Memory turned on, and your default Style switched to Concise.
Move on once: you stop re-typing the same instructions every session.
Stage 2: this month, your project or team
Commit a project .claude/settings.json with shared permissions, hooks, and MCP servers. Write a thin CLAUDE.md. If your team already uses multiple AI tools, have it do @AGENTS.md and add only what is Claude-specific on top. Convert your three most-repeated prompts into project skills under .claude/skills/, and if a few of those turn out to share phases or steps, see the Skills Showcase for how to split one big skill into an orchestrator and its sub-skills instead. Add one PostToolUse hook that runs your formatter, and one code-reviewer subagent.
Move on once: a new teammate clones the repo and inherits identical behavior, with no setup document to follow.
Stage 3: this quarter, your organization
If more than roughly a dozen people need the same setup, package it as a plugin and host a marketplace repo. Below that, shared skills in a shared repo are simpler and do not need the extra packaging step. On Team or Enterprise plans, have an owner provision core skills organization-wide and turn on skill content scanning. Deploy a managed settings.json for policy that must never be overridden, and, only if you want full lockdown, strictPluginOnlyCustomization, which restricts customization to plugins alone.
Reconsider if: the governance overhead starts to exceed the value it protects. Pull back to shared skills instead of plugins if that happens.
Thresholds worth remembering
- A
CLAUDE.mdsection growing into numbered steps → move it to a skill. - A rule that keeps getting skipped → move it from
CLAUDE.mdto a hook. - A task filling your context with noise you do not need afterward → move it to a subagent.
- A workflow that needs to travel outside Claude Code entirely → build it as a portable skill using only the six spec-compliant frontmatter fields, not a Claude Code-only slash command.
Governance, when you actually need it
What Team and Enterprise plans add▾
- Skill provisioning. Owners (not admins or general members) can provision skills organization-wide from Organization Settings, then Skills. Provisioned skills appear for everyone, enabled by default, and individually toggleable.
- Managed settings and managed marketplaces.
managed-settings.jsonand a managed marketplace let IT enforce policy that individual projects cannot override, mirroring the deny-always-wins rule from settings.json at the organization level. - The three-tier admin model. Individual users, team leads, and org owners each have a different scope of control. Provisioning and scanning specifically require the owner tier.
None of this is worth setting up before Stage 2 is solid. Governance without an underlying shared configuration just adds process for its own sake.