Share workflows without shadowing team skills

Learning objective

Place team commands and skills in .claude/commands/ and .claude/skills/ and personal variants under ~/.claude/commands/ and ~/.claude/skills/.

Core idea

A saved workflow’s location determines who receives it. A project file becomes a team asset when you commit it with the repository. A file beneath your home directory belongs to your local setup and does not arrive in a teammate’s clone. Choose the scope before choosing the wording of the workflow.

A personal variant also needs a distinct name. For skills with the same directory or file name, personal scope takes precedence over project scope. Copying the team’s skill into your home directory with the same name leaves the repository untouched but changes which version you run. That can make two developers believe they are following the same review procedure when they are not.

The directory determines who receives the workflow, and its name determines which copy an invocation selects. Frontmatter authoring belongs to 3.2.2; this lesson decides where that authored workflow belongs and how people can select it predictably.

How it works

Match location to audience

The exam guide distinguishes project commands from user commands, and Claude Code documents the equivalent project and personal skill locations. Use these paths for a team review workflow and a personal stricter variant:

The project-relative .claude/ directory is part of the repository. Sharing requires version control: a file that exists only in your uncommitted checkout does not become available to every developer because Claude Code can find it locally. Commit the workflow that the team is expected to use, just as you commit the code it reviews.

The ~ prefix identifies your home directory. A personal skill there is available across your projects on that machine. It is not a repository asset and is not a promise of availability in Cowork or cloud sessions. Anthropic’s skills documentation explicitly separates those sessions from skills stored only on your local machine. Do not diagnose a missing cloud skill by repeatedly editing its local home-directory copy.

Commands use a Markdown file; skills use a directory containing SKILL.md. Both represent an invocable saved workflow. Choosing the skill directory gives you a place for supporting files, but it does not change the project-versus-personal distribution decision. See 3.2.2 for the format comparison.

Give a personal variant its own identity

Suppose the team commits .claude/skills/team-review/SKILL.md. Keep your deeper review in ~/.claude/skills/team-review-strict/SKILL.md, with the name team-review-strict if you explicitly set the frontmatter name. You can then choose /team-review for the shared procedure or /team-review-strict for your extension.

If you instead create ~/.claude/skills/team-review/SKILL.md, /team-review selects your personal skill over the project’s skill. This is a local override, not an additional selectable version of the team command. The same visible invocation can therefore have different instructions on different machines.

A distinct personal name adds an explicit choice, while the same name replaces the project’s choice on your machine.

Enterprise skills can take precedence over both personal and project skills. Within the scopes this objective compares, however, the important rule is personal over project for a shared directory or file name. A project skill does not automatically win because the session starts in its repository.

Claude Code also resolves a skill and a command file sharing a name in favor of the skill. Avoid leaving .claude/commands/team-review.md and .claude/skills/team-review/SKILL.md as independently maintained procedures. See 3.2.2 for what that collision means during format migration.

Separate team intent from bundled names

Pick a name that makes the team’s purpose visible. Claude Code includes /review as an alias of its bundled /code-review skill. A name such as /team-review avoids making a team-specific checklist look like that bundled operation.

The commands reference documents the bundled alias; it does not distribute your team’s custom procedure. A developer who can type /review has not thereby proved that the repository’s review skill loaded. Confirm the intended custom invocation and the corresponding file, rather than treating any review-shaped command as interchangeable.

Key distinctions and trade-offs

Project location versus committed distribution: Claude Code can load a project file locally before you commit it. Version control is what gives teammates the same content. The directory answers where it is found; the commit answers how it is shared.

Personal variant versus personal override: A distinct personal name adds an explicit choice. The same name replaces the project’s choice on your machine through precedence. Use an override only when that replacement is intentional.

Local availability versus remote availability: A home-directory skill follows your local projects, not every execution environment. A repository skill provides a reviewable shared artifact rather than a dependency on each developer’s machine setup.

A shared workflow improves consistency but makes edits consequential for the whole team. A personal variant lets you experiment without changing that shared procedure. Naming both clearly preserves the ability to reproduce the team result before assessing your extra findings.

Architecture / decision scenario

A developer productivity team maintains a code-review checklist for service changes. The lead saves it in ~/.claude/commands/team-review.md, then tells a new engineer to clone the repository and invoke /team-review. The engineer cannot find it. The missing artifact is in the lead’s personal setup, so cloning the project cannot supply it.

The team moves the shared procedure into .claude/commands/team-review.md and commits it. For a workflow that also needs reference checklists, it can instead use .claude/skills/team-review/SKILL.md and commit the supporting files. These are alternative representations of the shared workflow, not two competing copies to maintain.

One engineer wants a deeper security pass. She keeps the command variant at ~/.claude/commands/team-review-strict.md, or the skill variant at ~/.claude/skills/team-review-strict/SKILL.md. The distinct name leaves /team-review available as the shared baseline. Saving a personal skill under team-review would shadow that baseline for her even though no teammate’s files changed.

The team’s acceptance criterion is therefore concrete: a repository clone contains the shared artifact, and the documented shared invocation selects that workflow without relying on an undisclosed personal override.

Common exam traps

• Saving a team command under ~/.claude/commands/ and expecting a clone to include it.
• Treating an uncommitted project file as an already distributed team standard.
• Editing a shared skill to satisfy one developer’s personal preference.
• Giving a personal skill the team’s name and assuming both remain separate choices.
• Assuming /review proves that a team-specific review workflow is installed.
• Declaring a team command in settings.json instead of a command file or skill; settings configure permissions and hooks rather than define the saved prompt.

Where the exam guide differs

What to remember

Use .claude/commands/ or .claude/skills/ for repository workflows and commit what the team must share. Use the corresponding home-directory paths for personal variants. Give those variants different names so personal precedence does not silently replace the team’s skill.

Knowledge check

References

• Anthropic, Extend Claude with skills
• Anthropic, Commands reference
• Anthropic, Explore the .claude directory
• Anthropic, Claude Certified Architect – Foundations Exam Guide