Slash Commands and Skills: Project vs Personal Scope

1.Two file formats, one mechanism

Claude Code gives you two ways to write a prompt you can invoke as /name. The older way is a single Markdown file in a commands/ directory. Its file name, minus the extension, becomes the command, so .claude/commands/deploy.md is invoked as /deploy. Subdirectories turn into colon-separated prefixes, so .claude/commands/frontend/component.md becomes /frontend:component. The documentation says this format still works and describes it as the same mechanism as skills, packaged as a single-file prompt.

The newer way is a skill: a directory containing a SKILL.md file. Its command name comes from the frontmatter name field, or from the directory name if there is no name field. A command file accepts the same frontmatter as a skill except name and paths. The real difference is what else you can include. A skill directory can hold supporting files next to SKILL.md, and that is why the docs tell you to use skills for new work.

Sources12

2.Project scope travels with the repo; personal scope stays on your machine

Commands and skills both come in two main scopes. The project scope is the repository's own .claude/ directory: .claude/commands/ for command files and .claude/skills/ for skills. The personal scope is the same layout under your home directory: ~/.claude/commands/ and ~/.claude/skills/. The .claude directory reference lists both commands/*.md and skills/<name>/SKILL.md as available at project and global level, and both are marked as files you commit.

Creating a project-scoped slash command takes two steps. First, write the prompt as a Markdown file in the repository's .claude/commands/ directory. The file name becomes the command, so .claude/commands/deploy.md is invoked as /deploy, and a file in a subfolder such as .claude/commands/frontend/component.md becomes /frontend:component. Second, commit the file. Version control is what gives the command team-wide availability: once deploy.md is committed and pushed, anyone who clones or pulls the repository gets /deploy in their sessions in that repository, without setting anything up themselves. A skill works the same way: create .claude/skills/deploy/SKILL.md and commit it. For new work the docs prefer the skill form, but the commands/ file is still a valid team-wide slash command.

A file in ~/.claude/ is never in the repository, so it follows you across your projects and nobody else sees it. If a teammate should have a command, it has to be in the project's .claude/ directory and committed. Putting it in your personal directory and telling people about it doesn't share it.

mkdir -p ~/.claude/skills/summarize-changes

Sources13

3.Name collisions and personal variants

CLAUDE.md files at different levels all add to Claude's context at once. Skills don't work that way: they override by name. When the same name exists at more than one level, one definition wins. Enterprise beats personal, and personal beats project. Plugin skills are the exception, because they are namespaced as /plugin-name:skill-name and so load alongside a local skill with the same short name.

This matters when you want to change a team skill to suit yourself. You have two bad options. If you edit the committed project file, you change it for everyone once that change is committed. If you copy it to ~/.claude/skills/ under the same name, your copy silently replaces the team version in your own sessions. From then on, your /deploy is no longer the /deploy your teammates run, and nothing warns you. The clean approach is a personal variant with a different name, for example ~/.claude/skills/deploy-verbose/. The team skill stays as it is, and you can still invoke it, and your variant exists only on your machine.

Sources41

4.Skill or CLAUDE.md?

The scoping rules above decide who gets a skill. A different question is whether the instruction should be a skill at all, or whether it belongs in CLAUDE.md. The deciding factor is when it loads. CLAUDE.md is persistent context loaded in every conversation, which suits rules that always apply, such as which package manager to use or running tests before committing. A skill loads on demand. Only its description sits in context each session, and the full content loads when you type /name or when Claude matches the description to your task.

So universal standards go in CLAUDE.md, and task-specific workflows go in skills. The features overview gives practical triggers. If you keep typing the same prompt to start a task, save it as a user-invocable skill. If you paste the same playbook into chat for the third time, capture it as a skill. The two can also work together: CLAUDE.md says to follow the API conventions, and a skill holds the full style guide.

Sources4

5.Configuring a skill with SKILL.md frontmatter: context: fork, allowed-tools, argument-hint

A skill in .claude/skills/<name>/ is configured by the YAML frontmatter at the top of its SKILL.md file, between the two --- lines. Every field is optional, and description is the recommended one. Three fields come up often when you build team skills.

context: fork runs the skill in an isolated subagent context. Set it to fork and the skill no longer runs in your main conversation. Claude Code creates a new isolated context, the subagent receives the skill content as its prompt, and the optional agent field chooses which subagent type runs it (for example Explore), which sets the model, tools and permissions. When the subagent finishes, it summarizes its results and returns them to your main conversation. The files it read and the intermediate tool output stay in the subagent's own context window. This makes fork the right choice for skills that produce a lot of output or exploratory context you won't refer to again, such as a codebase analysis or brainstorming alternatives, because only the summary reaches your main session. By default a forked skill runs in the background. Set background: false to wait for its result in the same turn.

allowed-tools lists the tools Claude can use without asking permission during the turn that invokes the skill. It takes a space- or comma-separated string or a YAML list, and accepts permission-rule patterns such as Bash(gh *). The grant clears when you send your next message. allowed-tools is a pre-approval, not an allowlist: tools that aren't listed are still available and go through the normal permission flow. To actually take tools away while a skill runs, for example so an autonomous skill can never call a destructive tool, use disallowed-tools, which removes the listed tools from Claude's available pool while the skill is active.

argument-hint is the hint shown during autocomplete to indicate the arguments the skill expects, for example [issue-number] or [filename] [format]. It tells a developer who types /name what parameters to supply, and the skill body reads them through $ARGUMENTS, $0, $1 and so on. argument-hint is a Claude Code field. A claude.ai upload or the Skills API accepts only name, description, license, compatibility, metadata and allowed-tools, and rejects argument-hint as an unexpected key.

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

---
name: deep-research
description: Research a topic thoroughly
context:  ? 
agent: Explore
---

Sources14

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.When a skill name exists in both the project and ~/.claude/skills/, the project's committed version wins.Why is that wrong?

   For skills, personal beats project, and enterprise beats both. A same-named personal copy replaces the team skill in your sessions without any warning.

   Covered in Name collisions and personal variants

2. 2.Putting a long, task-specific procedure in CLAUDE.md is fine because Claude only reads it when relevant.Why is that wrong?

   CLAUDE.md loads in every session. Only a skill defers its full content until it is invoked or matched to the task.

   Covered in Skill or CLAUDE.md?

3. 3.Listing tools in a skill's allowed-tools restricts Claude to only those tools while the skill runs.Why is that wrong?

   allowed-tools only pre-approves the listed tools for the invoking turn. Unlisted tools stay available. To remove tools while a skill is active, use disallowed-tools.

   Covered in Configuring a skill with SKILL.md frontmatter: context: fork, allowed-tools, argument-hint