Claude Code team skills and conventions

Claude Code skills are on-demand homes for repeatable workflows, loaded only when needed, while CLAUDE.md stays always-on context. The team gate that keeps them trustworthy: approve a skill only if its description is specific, its trigger is clear, and its output is reviewable by a teammate. Teams usually do not get stuck on model quality first. They get stuck when one person’s prompt works in a demo, then breaks in a shared repo, a review, or a handoff. Claude Code 2.1.150 brings that problem back into focus: if you want reliable AI coding work, you need team conventions, not just a better chat.

The situation

Counter-thesis: the hard part is not getting Claude to write code; it is getting the team to trust what it wrote.

The wrong path: we thought more prompting would fix drift. We tried longer chats, copied instructions into messages, and let each engineer improvise their own setup. What happened on the floor was familiar: context got lost, review notes got vague, and the same repo rule was rediscovered in every pull request.

Diagnosis: this is the local optimization trap. Each session looks productive, but the system gets less predictable.

Thesis: Claude Code team conventions are the product. The model is useful when the repo, the memory file, the skill, and the hook all point the same way.

That is the point of this workshop read. It is also why the real question is not “what can Claude do?” but “what should our team make durable?”

What to change in the workflow

1) Treat CLAUDE.md as memory, not a dumping ground. If you have shipped AI code, you have seen the file turn into a junk drawer. The fix is a Memory Split: keep global repo rules in CLAUDE.md, then move repeatable procedures into a skill or a nested repo file. Claude Code docs already frame skills as on-demand and CLAUDE.md as always-on context, which is the right split for shared repos. The result is less noise and fewer “why did it ignore that?” moments. Keep durable facts in memory; keep procedures in skills.

2) Use skills when the team keeps pasting the same steps. A skill is the right home for a repeatable workflow, especially when the team wants one shared way to run checks, review output, or prepare a change. That is where Claude Code skills stops being a phrase and becomes a control surface. The fix is a Skill Acceptance Rubric: approve a skill only if its description is specific, its trigger is clear, and its output is reviewable by a teammate. That is the practical answer to the Claude Code skills documentation question teams keep asking. If the skill cannot be explained in one paragraph, it is too broad.

3) Put hard boundaries in hooks, not in hopes. Hooks run outside the model loop, so they are the right place for deterministic checks: formatting, permission gates, logging, or a stop rule before a risky tool call. The fix is a Hook Boundary: every repo should name which events can block work and which only notify. That keeps the team from arguing with the model about policy. It also makes failures visible earlier, which is what review pressure needs. Use hooks for rules that must not drift.

4) Review MCP like a connector, not a convenience. MCP expands what Claude can touch, which means the review question changes from “does it work?” to “what can it reach?” The fix is an MCP Permission Note: list the connector, the data it can access, and the smallest scope that still lets the job finish. This is where least privilege matters in plain English. If a connector can reach GitHub, Slack, or a private store, the team should know that before the first run. Review the boundary before you celebrate the integration.

5) Make review expectations part of the artifact. Teams often ask reviewers to infer whether agent-authored code is safe. That is too much guesswork. The fix is a Claude Review Checklist attached to the repo: did the change follow CLAUDE.md, use the right skill, respect hook output, and stay inside approved MCP scope? This is the habit that turns Claude Code for teams from a solo productivity boost into a shared operating model. Reviewers should not have to reconstruct the session from memory.

Synthesis: the same rule keeps showing up in different clothes — make the team’s intent explicit, then make the tool obey it.

Copyable skill acceptance rubric

# 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.

Use this as a gate, not a ceremony.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.

Practical starter checklist

• Name the Claude Code artifact first: a CLAUDE.md fragment, a Claude skill outline, a hook boundary, an MCP permission note, or a review checklist.
• Write the review checklist before generation starts: scope, owner, tests, rollback.
• Keep the first step small enough that a reviewer can inspect the receipt without replaying the whole chat.

Failure modes to watch

• Named fix: Scope Receipt. Keep one short note that names the Claude Code artifact, the owner, and the files the agent may touch.
• Named fix: Review Gate. Require the reviewer to see the changed rule, checklist, or verification output before approving the work.
• Named fix: Rollback Note. Add the fastest safe undo path next to the change so the team can recover without reconstructing the session.

Synthesis

Synthesis: Treat the agent as a fast implementer behind a receipt gate: it can move quickly only when scope, checks, and ownership are visible.

Best ways to use this research

• Best for: Claude Code teams deciding which CLAUDE.md convention, hook, skill, or MCP boundary to standardize next around “Claude Code team skills and conventions.”
• Best first artifact: turn the named fix into a CLAUDE.md convention, hook checklist, skill note, or review receipt before the next automated run.
• Best comparison angle: compare the workflow against the current Claude Code handoff, hook behavior, and MCP scope; keep the path that leaves the shortest auditable trail.

Common questions

• When should teams use Claude Code skills instead of pasted instructions?

  Promote work into a skill when the team keeps pasting the same steps into chat: skills are the home for repeatable workflows like running checks, reviewing output, or preparing a change. Skills load on demand while CLAUDE.md stays always-on context, which means less noise and fewer why-did-it-ignore-that moments.

• What is a skill acceptance rubric?

  A skill acceptance rubric is a gate that approves a Claude Code 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 requires one owner, one review path, and a teammate who can explain it in under 60 seconds.

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

  Hard boundaries belong in hooks, not in hopes: hooks run outside the model loop, which makes them right for formatting, permission gates, logging, and a stop rule before a risky tool call. Name which events can block work and which only notify, so nobody argues policy with the model.

• 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.

Further reading

• Claude Code docs: en getting started
• Claude Code docs: en skills
• Claude Code docs: en hooks
• Claude Code docs: en permissions
• MCP docs: specification latest
• anthropic.com: claude code
• github.com: anthropics skills

What to do next

Take this into the related training topic and test whether a new reviewer can defend the merge without replaying the chat.