How to Sync Claude Code Skills Hooks and Subagents

The practical answer: sync Claude Code skills hooks and subagents by treating Claude Code configuration as governed project infrastructure, not as personal dotfiles. Commit repo-owned behavior in .claude/ and .mcp.json, keep personal exceptions in local or user settings, use managed settings for non-negotiable policy, and use plugins when the same harness must run across several repositories.

For a platform engineering lead, the decision is not "where do we copy the files?" It is "which layer has authority for each behavior?" That distinction controls drift, security, onboarding, and whether cloud or headless sessions behave like local terminal sessions.

Related reading: Claude Code hooks for permissions.

How to sync Claude Code skills hooks and subagents

Use four layers, each with a different job:

That model follows Anthropic's current configuration split. Shared project settings live in .claude/settings.json. Project skills live under .claude/skills/<skill-name>/SKILL.md. Project subagents live under .claude/agents/. Project MCP servers can be shared through a root .mcp.json. Hooks are configured through settings, managed policy, or skill and agent frontmatter, depending on the surface.

The priority order matters. Claude Code settings resolve from managed settings first, then command-line settings, then project local settings, then shared project settings, then user settings. List fields such as permission allowlists can merge, which means a platform team should test effective config rather than assume replacement semantics.

Start with the authority boundary

You have three categories of Claude Code behavior. Mixing them is where drift starts.

The key distinction is that CLAUDE.md and rules are instructions. They are useful for context, but they are not hard controls. If the rule is "run this linter before editing generated API clients," a hook is a better fit. If the rule is "no one may allow a dangerous tool pattern," managed settings are the stronger boundary.

This is where the governance conversation becomes concrete. A repo can ask Claude to follow a norm. A hook can block an operation with exit code 2. Managed settings can prevent local override. Those are different levels of assurance.

A baseline repo layout that scales

For one repository, a reasonable starting layout is:

.
|-- CLAUDE.md
|-- .mcp.json
`-- .claude/
    |-- settings.json
    |-- rules/
    |   `-- api-clients.md
    |-- skills/
    |   `-- release-checklist/
    |       `-- SKILL.md
    |-- agents/
    |   `-- security-reviewer.md
    `-- hooks/
        `-- pre-tool-check.sh

Commit this only if each file describes shared project behavior. Do not commit credentials, personal paths, tokens, one engineer's preferred tools, or the contents of ~/.claude. The brief's security sources point to the standard rule: once a secret lands in Git, treat it as exposed and rotate it.

Use .claude/settings.local.json for individual exceptions. For example, one engineer may need a local path, a temporary hook disablement during debugging, or a personal workflow setting. That file should not become the team contract.

For monorepos, avoid one giant root instruction file unless the conventions truly apply everywhere. Claude Code can use nested memory, rules, skills, and agents. The operational point is simple: billing code, mobile clients, infra modules, and generated clients rarely need identical context. Path-scoped rules can reduce noise and surprise.

Related reading: Claude Code monorepo setup.

When to move from repo config to a plugin

A committed .claude/ directory is the lowest-friction answer for one codebase. It becomes weak when you copy the same files into five repositories and then patch them by hand.

Use a plugin when you need one versioned unit for skills, agents, hooks, MCP servers, and output styles across projects. Anthropic's plugin model is explicitly aimed at sharing a setup with teammates, installing it in many projects, or publishing versioned releases. That maps well to platform-owned Claude Code harnesses.

The trade-off: plugins reduce file-copy drift, but they are not free. Names and descriptions for plugin-enabled skills and agents can affect context. Large harnesses can slow sessions and make behavior harder to reason about. A platform plugin should be curated like an internal SDK, not treated as a dumping ground.

Hooks need stricter review than prompts

Hooks are the right tool for deterministic checks, but they carry a different risk profile from memory files or skills. Claude Code hook docs state that command hooks run shell commands with the user's permissions. A hook can read, change, or delete anything the account can access.

That changes the review bar. A hook script should have an owner, a purpose, a timeout expectation, and a rollback path. It should use ${CLAUDE_PROJECT_DIR} to anchor project paths. It should avoid hidden background processes unless there is a clear watchdog. It should avoid network calls unless those calls are part of an approved control.

Operational details matter:

• Hook JSON arrives on stdin with session and event data.
• Exit code 2 blocks the relevant action.
• Multiple matching hooks run in parallel.
• The default timeout is 60 seconds.
• Interactive trust rules differ from claude -p and SDK sessions.

The headless case deserves special attention. According to the brief, -p and SDK sessions treat folders as trusted and can run repository hooks unless started with --bare or with settings that disable all hooks. If your team uses Claude Code in CI, automation, or self-hosted runners, test that path separately from local terminal use.

MCP is part of the sync problem

MCP servers make team setups reproducible, but they also expand the blast radius. A project-scoped .mcp.json can standardize access to issue trackers, internal APIs, databases, or documentation. That is useful. It also means connector approval, authentication, tool allowlists, and prompt-injection review become platform responsibilities.

One detail from the MCP docs is easy to miss: a cloned repository cannot approve its own committed MCP servers from .claude/settings.json before workspace trust. Initial MCP status can remain pending. Build onboarding around that fact instead of treating it as a developer mistake.

A practical MCP governance rule:

Related reading: MCP permission gateway for Claude Code.

Cloud, Cowork, and local sessions are not identical

A standardization plan fails if it assumes every Claude Code surface reads the same files.

Cloud sessions start from a fresh repository clone. They can load committed project skills, but they do not read local ~/.claude/skills/. Account-enabled skills may sync from claude.ai, with version and environment limits. Multiple-repository cloud sessions read only selected plugin or marketplace keys from each repo settings file, not the full local behavior you may expect from terminal usage.

That means your rollout should include a compatibility table. At minimum, test these surfaces:

• Local terminal Claude Code
• VS Code or Desktop local use, if your team uses it
• claude -p
• Cloud sessions
• Cowork sessions
• CI or self-hosted runner images
• SDK-driven automation

For each surface, record whether it loads project settings, project-local settings, user settings, project skills, account-synced skills, plugins, hooks, MCP servers, and managed settings. This is tedious once. Drift caused by wrong assumptions is tedious every week.

Subagents: share them, but test inheritance

Project subagents under .claude/agents/ are the right default for codebase-specific team agents. The docs describe them as suitable for version control, and discovery walks upward from the current working directory. If the same agent name appears in nested directories, the closest definition wins.

For cross-project team agents, prefer a plugin, managed settings, or explicit additional directories over uncontrolled copies. User subagents are personal by design.

The risk area is inheritance. The brief cites community and GitHub issue reports about subagents and team-spawned agents not behaving as expected around hooks, permissions, memory, and skills. Treat those as version-specific field evidence, not permanent product truth. The practical response is still clear: regression-test the exact behavior your policy depends on before rollout.

A minimal subagent regression suite should answer five questions:

• Does the subagent see the expected project memory and rules?
• Do hook rules fire when the subagent uses tools?
• Are permissions inherited, merged, or isolated in the way your team expects?
• Does the behavior change when the agent is invoked directly versus spawned by another agent?
• Does the behavior match across terminal, -p, cloud, and CI?

Control drift with release discipline

Configuration drift is not only file drift. It is also model drift, Claude Code version drift, hook behavior drift, plugin drift, and connector permission drift.

For a platform team, the operating model should look closer to library ownership than wiki ownership:

• Put CODEOWNERS on .claude/, .mcp.json, plugin manifests, and hook scripts.
• Require review from platform or security owners for hook, MCP, permission, and managed-settings changes.
• Version internal plugins and publish release notes for behavior changes.
• Pin or record the Claude Code versions used in validated workflows.
• Run smoke tests after Claude Code or model changes.
• Keep a small eval set for critical skills, agents, and hooks.

The eval set does not need to be elaborate at the start. Use cases can be concrete: "generated client files are not edited without the required command," "security-reviewer agent flags a hardcoded token in a fixture," "release-checklist skill asks for changelog and migration status," and "production MCP server is not available in a repo that should not load it."

Community examples in the brief point in the same direction: teams are starting to treat Claude Code setup as code, with CI checks for CLAUDE.md, skills, hooks, and baseline behavior after model or CLI changes. That is not an official standard, but it is a rational response to silent drift.

A rollout plan for platform teams

Use a staged rollout. The first objective is not maximum automation. It is predictable authority.

Phase 1: Inventory

List every current Claude Code surface in use: CLAUDE.md, rules, project settings, local settings, skills, agents, hooks, plugins, MCP servers, and account-synced skills. Mark each item as shared, personal, experimental, or policy.

Phase 2: Baseline one repository

Pick one active repository and commit the minimum project-owned setup. Avoid moving every personal helper into the repo. Start with the shared instructions, one or two high-value skills, the agents the team actually uses, and only the hooks that enforce clear rules.

Phase 3: Separate policy from convention

Move non-negotiable rules to managed settings. Leave codebase conventions in CLAUDE.md or rules. Keep reusable procedures in skills. Keep deterministic local checks in hooks.

Phase 4: Package cross-repo behavior

If two or more repositories now need the same harness, create an internal plugin. Version it. Keep the plugin smaller than your ambition. Shared agents and skills should earn their place by reducing repeated work or risk.

Phase 5: Test the session matrix

Run the same scenarios locally, with claude -p, in cloud sessions, and in any runner image. Record differences. Decide whether to support each surface or restrict it for sensitive workflows.

What not to standardize

Do not standardize by committing a personal ~/.claude directory. It mixes shared behavior with user preferences, local paths, private experiments, and potentially credentials.

Do not put hard safety rules only in prose. Use prose for context and judgment. Use hooks, permissions, and managed settings for enforcement.

Do not copy hooks from another team without treating them like executable code. They are executable code.

Do not assume cloud sessions, Cowork sessions, terminal sessions, and SDK automation load the same surfaces. The brief shows several differences, especially around local skills, settings keys, hooks, and account sync.

Do not let the platform harness grow without a budget. One field report in the brief described large numbers of hooks, skills, and subagents creating slowdowns and failed verification attempts. Treat that as anecdotal, but the underlying mechanism is plausible: every always-visible description and every hook has operational cost.

The decision rule

If you manage Claude Code across teams, your source of truth should not be a folder. It should be an authority map.

Commit repo-specific behavior. Keep personal overrides personal. Use managed settings for controls that must hold everywhere. Use plugins for cross-repo packages. Put MCP behind explicit approval and credential boundaries. Test subagent and hook behavior on the exact Claude Code surfaces your engineers use.

That is the stable way to sync Claude Code skills hooks and subagents without turning configuration into an unreviewed second codebase.