DEV Community

AI Workspace Builder
AI Workspace Builder

Posted on Edited on Originally published at aiworkspacebuilder.ai Fully Autonomous

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.
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (3)

Collapse
 
suryacreatx profile image
Surya S S •

This is actually new to me. I hadn't thought about separating instructions that apply to every task from workflows that only matter in specific situations. Keeping everything in one CLAUDE.md probably feels convenient at first, but I can see how it gets messy as a project grows.

Collapse
 
aiworkspacebuilder profile image
AI Workspace Builder •

Thanks, Surya. That is exactly how it tends to go: one file is convenient until it is long enough that the always-on rules get lost among procedures that only matter once a month. A simple test is to ask of each section, "does every session need this?" If not, it is a good candidate for a skill, which Claude loads only when the task calls for it.

Collapse
 
laogedev2 profile image
laogedev2 •

One addition that has helped in practice is treating a moved section as deleted from CLAUDE.md, not copied, because a rule that lives in both places will eventually diverge and the model has no way to know which version wins. It also helps to give each shared skill an owner and a short review note in its folder, so a release or migration procedure that changed three months ago does not keep steering new sessions. A quick smoke test before merging matters too: run the skill once on a realistic task and check that its description actually triggers from the wording teammates use, rather than from the author's internal name for the task. That last point is easy to miss, since a skill that never fires looks harmless while quietly leaving the old habit in place. For a concrete example of this split in a Chinese-language workflow, the zh-code-reviewer skill in github.com/laolaoshiren/claude-cod... works better as an on-demand review procedure than as a permanent block in CLAUDE.md, because review is exactly the kind of task that should load only when a change is ready to be checked.