Claude Code skills for teams: what to move out of CLAUDE.md

A team's CLAUDE.md tends to grow. Someone adds the release checklist, someone else adds the steps for a database migration, then the rules for writing API endpoints. Each addition makes sense. Together they push the file past the point where the agent follows it well.

The Claude Code docs suggest keeping each CLAUDE.md under 200 lines, because the whole file loads into every session and longer files get followed less reliably. Most of what makes a file long isn't needed in every session. A release checklist matters on release day.

That is what skills are for. A skill is a set of instructions that loads when it's needed instead of all the time. This post covers how a team should split the two and which skills are worth committing to a shared repository.

What a skill is

A skill is a folder with a SKILL.md file in it. The file has two parts: frontmatter that says what the skill does and when to use it, and the instructions Claude follows when it runs.

---
name: add-migration
description: Creates a database migration for this repo. Use when a change needs a new table, column or index.
---

1. Generate the migration file with `npm run db:new -- <name>`.
2. Write the up and down steps. Every up needs a working down.
3. Run `npm run db:migrate` and then `npm run db:rollback` to prove both directions.
4. Add the schema change to docs/schema.md.

The folder name, or the name field, becomes a command: anyone on the team can type /add-migration. Claude can also load it on its own when a request matches the description. Until then, only the description sits in context, not the instructions.

If your team already has files in .claude/commands/, they keep working. Custom commands have been merged into skills, and a skill adds a folder for supporting files and more control over who can run it.

CLAUDE.md or a skill?

A simple test: does the agent need this in every session, or only for one kind of task?

Put it in CLAUDE.md	Put it in a skill
Build and test commands	The release checklist
Conventions that apply to every change	Steps for a database migration
What the product is and who it's for	How to write a new API endpoint
Things you'd reject in any review	How to debug the payment integration

CLAUDE.md is what everyone needs every day. A skill is a procedure someone needs on a particular day.

Commit them where the team gets them

Where a skill is saved decides who has it:

• Project: .claude/skills/<name>/SKILL.md in the repository. Commit it and everyone who works there gets it. This is the one teams want.
• Personal: ~/.claude/skills/<name>/SKILL.md on your own machine, for every project you work on.
• Enterprise: deployed through managed settings to everyone in the organization.

One thing to know: when two skills share a name, enterprise beats personal and personal beats project. If a developer has an old personal deploy skill, typing /deploy runs theirs, not the one the team committed. Use names specific to the repository, such as deploy-web, for the shared ones.

In a monorepo, a package can have its own .claude/skills/ folder. Claude Code loads those skills the first time it reads or edits a file in that package. If the root and apps/web both have a deploy skill, both stay available, and /apps/web:deploy runs the package's one.

Decide who can run each skill

Two frontmatter fields control this, and for a team they matter more than anything else in the file.

Frontmatter	You can run it	Claude can run it on its own
(default)	Yes	Yes
disable-model-invocation: true	Yes	No
user-invocable: false	No	Yes

Anything with side effects, such as a deploy, a release or a message to a channel, should have disable-model-invocation: true. The docs put it plainly: you don't want Claude deciding to deploy because your code looks ready. With that field set, the description isn't loaded into context either, so the skill costs nothing until someone types its name.

user-invocable: false is for background knowledge, such as how a legacy system works. Claude should know it when relevant, but it isn't a command anyone would type.

Three skills worth committing

1. The release. The steps your team runs to ship, in order, with the checks between them. Set disable-model-invocation: true so it only runs when a person asks.

---
name: release-web
description: Releases the web app to production.
disable-model-invocation: true
---

1. Confirm the branch is main and the working tree is clean.
2. Run the full test suite and stop if anything fails.
3. Bump the version in package.json and update CHANGELOG.md.
4. Tag the release and push the tag.
5. Report the tag and the CI run link. Do not mark the release done until CI is green.

2. The task everyone gets slightly wrong. Every team has one: the migration, the new API endpoint, the feature flag. Write the steps once, including the one people forget. Leave it invocable by Claude so it loads when someone asks for that kind of change.

3. Your conventions for one area. API design rules, the error format, how to name events. These are reference content: Claude applies them alongside the work instead of running them as steps. They only matter when someone works in that area, so they don't need to be in CLAUDE.md.

Two details that save trouble

Review allowed-tools in shared skills. A skill can list tools that Claude may use without asking during the turn that runs it. That is useful for a release script, but the docs warn that a skill checked into a repository can grant itself broad access, and the field applies even in a non-interactive run in a folder you've never trusted. Review it in pull requests like any other permission change.

Keep the description sharp and the file short. Claude decides when to load a skill from its description, and the skill listing cuts the description off at 1,536 characters, so put the main use case first. The docs suggest keeping SKILL.md under 500 lines and moving long reference material into separate files in the skill's folder, which load only when needed.

Where to start

Read your CLAUDE.md and mark every section that only matters for one kind of task. Each of those is a skill. Move one, commit it, and check that the file the agent reads every session got shorter.

If you're starting from nothing, the shared part comes first: a CLAUDE.md the whole team agrees on. AI Workspace Builder generates one from the docs your team already has, along with a profile for each role and an install script, using your own Anthropic API key. No docs yet? Answer a short questionnaire and download a starter CLAUDE.md, no signup needed.