Claude Code team skills and conventions

Most teams using Claude Code, Anthropic's coding agent, don't get stuck on model quality. They get stuck when one person's prompt works in a demo, then breaks in a shared repo, a review, or a handoff. A team convention is a written agreement about where your repo's rules, procedures, and boundaries live so the agent and the next reviewer both read the same thing. Claude Code 2.1.150 makes this easier with four places to put that intent: CLAUDE.md, skills, hooks, and MCP. The trick is knowing which one to reach for.

Decide what goes in CLAUDE.md and what becomes a skill

CLAUDE.md is your always-on context. Claude reads it on every session, so it should hold durable facts about the repo: the test command, the branch rules, the things that are true no matter what you're working on.

A skill is different. It loads on demand, only when the job calls for it, and it holds a repeatable procedure. Think "run our release checks" or "prepare a migration," not "everything about this project."

The failure mode is putting procedures in CLAUDE.md. The file turns into a junk drawer, the agent skims it, and you get the dreaded "why did it ignore that?" moment. Keep facts in memory. Keep steps in skills. The Claude Code docs frame skills as on-demand for exactly this reason.

Gate every skill with a rubric your team trusts

Reach for a skill when your team keeps pasting the same steps into chat. That repetition is the signal: it wants one shared home instead of five slightly different copies in five engineers' heads.

Before you merge a skill, run it past a short rubric. If it cannot pass these, it is too broad or too vague to be shared. Paste this into your repo:

# Skill acceptance rubric

Approve a Claude Code skill only if all of these are true:

- The skill solves one repeated job, not a whole project.
- The description says when to use it in plain words.
- The skill output can be checked by a reviewer.
- Any tools it needs are listed or pre-approved.
- The skill does not duplicate durable repo rules in CLAUDE.md.
- A teammate can explain the skill in under 60 seconds.
- The skill has one owner and one review path.

The "explain it in 60 seconds" line is the one that catches the most trouble. If nobody can say what the skill does in a sentence, the agent will not use it cleanly either.

Put hard rules in hooks, not in the prompt

Hooks run outside the model loop, which makes them the right place for anything that must not drift. Formatting, permission gates, logging, a stop rule before a risky tool call: these are decisions you want enforced, not negotiated.

The mistake is asking the model to remember a policy in plain English. It mostly will, until the one session where it doesn't. A hook just blocks the action, every time.

Give each repo a clear split: name which hook events can block work and which only notify. That way nobody is arguing policy with the agent mid-task. The hooks docs cover the available events.

Review MCP connectors for reach, not just function

MCP expands what Claude can touch, so the review question shifts from "does it work?" to "what can it reach?" That is the whole game with connectors.

For every MCP server you add, write a one-line permission note: name the connector, the data it can access, and the smallest scope that still finishes the job. If a connector can reach GitHub, Slack, or a private store, the team should know that before the first run, not after.

This is least privilege in plain language. The MCP specification and the permissions docs are worth a read before you wire anything to production data.

Common questions

• When should teams use a skill instead of pasted instructions?

  Promote work into a skill the moment your team keeps pasting the same steps into chat. Skills are the home for repeatable workflows like running checks, reviewing output, or preparing a change. They load on demand while CLAUDE.md stays always-on, which means less noise in context and fewer moments where the agent skips a rule it should have followed.

• What is a skill acceptance rubric?

  A skill acceptance rubric is a short gate you run before merging a skill. It approves a skill only if it solves one repeated job, says when to use it in plain words, produces output a reviewer can check, and avoids duplicating CLAUDE.md rules. It also asks for one owner, one review path, and a teammate who can explain the skill in under 60 seconds.

• Where do hard boundaries belong in a Claude Code setup?

  Hard boundaries belong in hooks, not in the prompt. Hooks run outside the model loop, so they are the right place for formatting, permission gates, logging, and a stop rule before a risky tool call. Name which hook events can block work and which only notify, so nobody ends up arguing policy with the model in the middle of a task.

• How does Claude Code 2.1.150 change team conventions?

  Claude Code 2.1.150 brings the conventions problem back into focus: reliable AI coding work comes from team conventions, not just a better chat. The durable artifacts are the repo, the memory file, the skill, and the hook, all pointing the same way. When those four agree, the agent moves fast and the reviewer can trust what it shipped.

Where to go next

Pick the one artifact your team argues about most, a CLAUDE.md rule, a skill, a hook, or an MCP scope, and make it explicit this week. Take it into the team conventions topic and check whether a fresh reviewer can defend the merge without replaying the chat.