Home › Study guides › CCAR-F › Domain 3 › Lesson 3.2

CCAR-F · Domain 3 · 20% of the exam · Lesson 3.2 · 22 min read

Custom slash commands and skills

Where a shared /review command lives, what the SKILL.md front matter keys context: fork, allowed-tools and argument-hint do, and when a skill beats CLAUDE.md.

Written against task statement 3.2 of the official CCAR-F exam guide (Version 1.0, effective July 2026). An independent resource, not affiliated with Anthropic; the practice questions are written from scratch.

3.2.1 Why a team keeps pasting the same checklist

Picture a development team that has adopted Claude Code. Every time someone wants a code review, they paste the same twelve-line checklist into the prompt: check error handling, look for missing tests, flag hard-coded passwords, confirm the naming convention. Some people paste last month's version. One developer has quietly added three checks of her own. Nobody is sure which checklist the new hire is using, because he copied it from a chat message.

The first instinct is to put the checklist into CLAUDE.md, the file of standing instructions Claude Code reads at the start of every session. That works, but it is the wrong tool. CLAUDE.md is for things Claude should know all the time, and a review checklist is a procedure you run on demand. Put it there and every line would sit in Claude's context, the text Claude holds in view during a session. It would take up room on every request, including the many that have nothing to do with reviews.

What the team wants is a saved prompt with a name. A developer types /review, Claude Code loads the full checklist, and Claude works through it. Claude Code offers two forms of that. A custom slash command is one Markdown file (plain text with light formatting) per command. A skill is a folder holding a SKILL.md file, which starts with a short block of settings, the front matter. Where you put the file decides who gets it, and a handful of front matter settings decide how it behaves. Those two facts are most of this lesson.

3.2.2 Where the file lives decides who gets it

Start with a puzzle the exam likes to pose. The team lead writes /review, and it works perfectly on her machine. The next developer who downloads the project does not have it. Nothing is broken. The command was saved in the wrong place.

A word on vocabulary first. The team's code lives in a repository, a shared project folder tracked by version control (usually Git). Developers clone the repository to get their own copy and pull to fetch the latest changes. So anything committed (saved into the repository's history) reaches every developer.

Claude Code looks for your custom commands in two main places. A file at .claude/commands/review.md inside the project creates /review for anyone working in that repository. Because .claude/ sits inside the repository, committing the file carries it to every clone and every pull. That is project scope, and it is what "every developer on the team gets it" means in practice. A file at ~/.claude/commands/review.md also creates /review, in every project on that one machine. The ~ stands for your home directory, your personal folder on your own computer, which is not part of any repository. That is user scope: personal, and invisible to teammates.

Think of a shared kitchen. A recipe pinned to the kitchen wall is read by everyone who walks in. A recipe card in your own pocket travels with you between kitchens, but nobody else ever sees it. The exam checks that you can tell which one a situation calls for. "Available to every developer when they clone or pull" is the wall, .claude/commands/. "A personal tweak nobody else should get" is the pocket, ~/.claude/commands/. Skills follow exactly the same split with a different folder: .claude/skills/<name>/SKILL.md in the project, ~/.claude/skills/<name>/SKILL.md for one person.

So the team commits .claude/commands/review.md. The developer who likes a stricter review keeps ~/.claude/commands/review-strict.md in her home directory, and the rest of the team never knows it exists. Both commands work on her machine; only one of them ships with the code.

3.2.3 Anatomy of a skill: a folder, a SKILL.md and its front matter

Now the second half of the team's problem. A code review is short, but some workflows read half the codebase, all the code in the project. The team wants an /analyze-codebase skill for that. Point it at one part of the system, a subsystem such as the login code. It lists the pieces (modules), traces which pieces rely on which (dependencies), and writes up how they fit together. Let's look at what a skill like that is made of.

A skill is a directory named after the skill, containing a file called SKILL.md. The directory name becomes the command: .claude/skills/analyze-codebase/SKILL.md gives you /analyze-codebase. The file has two parts. At the top, between two --- lines, sits the front matter: a few key: value settings, written in a simple format called YAML, that tell Claude Code how to run the skill. Below it is ordinary Markdown: the instructions Claude follows when the skill runs. When someone types /analyze-codebase auth, the text after the name ("auth") appears inside the instructions wherever they say $ARGUMENTS.

Here is the team's skill. Look at the three front matter lines after description; each does one job, and the next two sections take them one at a time.

---
name: analyze-codebase
description: Map the modules, dependencies and entry points of one subsystem. Use when asked how part of the codebase fits together.
context: fork                 # run in an isolated subagent, not the main conversation
allowed-tools: Read Grep Glob # the tools this skill is cleared to use
argument-hint: <subsystem>    # what a developer should type after the name
---

Analyze the `$ARGUMENTS` subsystem:

1. List its modules and their public entry points.
2. Trace which other subsystems it imports and which import it.
3. Write a one-page summary with file references.

Read, Grep and Glob are Claude Code's tools for reading a file, searching inside files and finding files by name; none of them changes anything. The spelling of each key has to be exact, hyphens included, because Claude Code ignores a key it does not recognise without reporting an error. The table shows the three keys this task statement is built around, plus the others you should recognise.

Memorise context, allowed-tools and argument-hint, and know name and description. Recognise the last two rows.

3.2.4 context: fork keeps the noise out of the main conversation

Run /analyze-codebase auth without any front matter and watch what happens to the session. The skill reads forty files, runs a dozen searches, and thinks out loud about each one. All of that lands in the main conversation. By the time the summary appears, the context window (the fixed amount of text a session can hold) is full of files the developer will never read again. Every later request in that session drags all of it along, so Claude's attention is spread thinner. That is what it means for a skill's output to pollute the main conversation.

context: fork is the fix. With that line in the front matter, Claude Code does not run the skill in your conversation. It starts a subagent, a separate Claude Code agent with its own fresh context window, and hands it the skill's instructions as its task. The subagent does the reading and searching in its own space. When it finishes, only its result comes back into your conversation. The forty files stay behind.

Think of asking a colleague to go and survey the archive. They come back with a one-page report; they do not empty forty boxes of files onto your desk. The precise statement: with context: fork, the skill's working context is isolated in a subagent, and only the result is returned to the main session.

Two consequences follow. First, the use cases: verbose output, like a codebase analysis, and exploratory context, like brainstorming five alternative designs when four will be thrown away. Anything you want done but not living in the session forever is a candidate. Second, because the subagent starts fresh, it does not see your conversation history. The skill's instructions have to stand on their own: a forked skill that says "fix the bug we just discussed" has no idea which bug you mean. An optional agent key names which subagent type runs it (the read-only Explore agent suits analysis); leave it out and Claude Code uses its general-purpose subagent.

3.2.5 allowed-tools and argument-hint: a guard rail and a nudge

Isolation solves the noise problem. Two smaller problems remain, and each has its own front matter key.

The first is safety. The team's third workflow generates code: /scaffold-endpoint creates the files for a new API endpoint (an address other programs call to use one feature), plus its tests. It needs to read and write files. It has no business running shell commands, the raw commands typed into a terminal, one of which can delete a whole folder. The key for this job is allowed-tools, the list of tools the skill is cleared to use. A setting here beats a sentence in the instructions saying "please do not delete anything": the sentence is a request, and the setting is configuration that Claude Code applies. Look at the allowed-tools line below: file tools only, and no shell.

---
name: scaffold-endpoint
description: Generate the files and tests for a new API endpoint. Use when asked to add an endpoint.
allowed-tools: Read Write Edit      # file tools only; the shell is not on the list
argument-hint: <resource-name>      # shown as a developer types /scaffold-endpoint
---
Create the `$ARGUMENTS` endpoint following the project layout, with tests.

Here is precisely what the key does in current Claude Code. The listed tools are pre-approved: they run without a permission prompt during the turn that invoked the skill. Tools not on the list are not switched off. Your normal permission settings decide about them, and in the default mode those ask you before a file changes or a shell command runs (a few read-only commands excepted). For an outright ban there is a separate key, disallowed-tools. The exam keeps it simple: when a question asks how to limit the tools a skill uses, it expects allowed-tools. The list can be as narrow as Bash(git status *), one command rather than the whole shell.

The second problem is human. Developers keep typing /analyze-codebase and pressing Enter with no subsystem named, and the skill either asks what to analyze or guesses. argument-hint fixes this at the moment it matters. Set argument-hint: <subsystem> and the hint appears beside the command in the autocomplete menu as the developer types it. The person about to run it bare is told what to supply. It is the answer whenever a question says developers invoke a skill without the parameter it needs. It does not change what the skill does; it changes what the developer is prompted to type.

Notice how the three keys divide the work. context: fork decides WHERE the skill runs. allowed-tools decides WHICH tools it is cleared to use. argument-hint decides what the developer is asked for.

3.2.6 Personal variants, and skill versus CLAUDE.md

One developer wants /analyze-codebase to go deeper: trace every call chain, not only imports. It is tempting to edit .claude/skills/analyze-codebase/SKILL.md in place. Don't. That file is in the repository, so her next commit changes the workflow for everyone, and the team's summary suddenly takes three times as long.

The right move is a personal variant: a copy in ~/.claude/skills/ under a different name, say ~/.claude/skills/analyze-codebase-deep/SKILL.md. It lives in her home directory, so teammates never see it. It has its own name, so the team's /analyze-codebase still runs unchanged on her machine and she chooses which one to use each time. The different name matters. When a personal skill and a project skill share a name, the personal one wins on that machine, and the team's version stops running for her.

The last judgment in this task statement is the one the opener raised: skill or CLAUDE.md? Both hold instructions in Markdown, so people conflate them. They differ in when they load. The project's CLAUDE.md loads at the start of every session and stays in context for every request. That is exactly right for universal standards: the build command, the naming convention, "never commit passwords". A skill's instructions load only when it is invoked, either by a developer typing its name or by Claude matching the task to its description. Until then only that short description costs anything. That is exactly right for task-specific workflows: the review checklist, the codebase analysis, the endpoint scaffold.

The documentation's own rule of thumb: keep CLAUDE.md under 200 lines, and when a section of it has grown into a procedure rather than a fact, move it into a skill. A checklist used once a week, or a workflow that produces a lot of output, is a skill. Rules every edit must follow belong in CLAUDE.md.

3.2.7 The exam traps

Every trap here is a mix-up between two things that look alike: two directories, two files, or two front matter keys. Once you can say which problem each one solves, the distractors stop being tempting.

• ✗ Saving the team's /review in ~/.claude/commands/, or declaring it in a settings file. ✓ A Markdown file in .claude/commands/ in the project, committed. The home directory is not in the repository, so a clone or pull never brings it along, and settings files hold permissions, not commands.
• ✗ Reaching for allowed-tools or a shorter prompt when a skill floods the session. ✓ context: fork. Pollution of the main conversation is an isolation problem, and only the fork keeps the working context out of the session.
• ✗ Writing "do not delete files" in the skill's instructions. ✓ allowed-tools in the front matter, scoped to the tools the skill needs. A sentence is a request; a front matter setting is configuration.
• ✗ Documenting the required argument in the README. ✓ argument-hint, which shows the expected argument at the moment the developer invokes the skill.
• ✗ Editing the shared skill, or copying it to ~/.claude/skills/ under the same name. ✓ A personal variant under a different name in ~/.claude/skills/. Editing changes it for everyone; a same-named copy shadows the team's skill on your machine.
• ✗ Putting a weekly checklist in CLAUDE.md because "it is important". ✓ A skill. Importance is not the test; always needed versus needed on demand is.

3.2.8 Put it together: build a skill and break it

You now have every piece: two scopes, the anatomy of a skill, three front matter keys, personal variants and the skill-versus-CLAUDE.md decision. The fastest way to make the details stick is to build the team's toolkit yourself and watch each setting fail when it is removed.

The rest of this domain applies the same habit to other files. The CLAUDE.md hierarchy (3.1) is the always-loaded half of the decision you just made, and path-specific rules (3.3) make part of that standing content load only for matching files. Claude Code in CI (3.6) is where committed project commands earn their keep. A pipeline that clones the repository gets the team's commands along with the code and can invoke them by name.

Key takeaways

• ✓ A slash command or skill is a saved workflow that loads only when invoked; .claude/commands/ and .claude/skills/ in the project are shared through version control, ~/.claude/commands/ and ~/.claude/skills/ are personal.
• ✓ A skill is a folder with a SKILL.md: YAML front matter that configures how it runs, then Markdown instructions that can use $ARGUMENTS.
• ✓ context: fork runs the skill in an isolated subagent context so verbose or exploratory output does not pollute the main conversation; only the result returns.
• ✓ allowed-tools scopes a skill to the tools it needs, and argument-hint tells developers what argument the skill expects when they invoke it.
• ✓ A personal variant of a shared skill goes in ~/.claude/skills/ under a different name, so teammates are unaffected and the team's copy still runs.
• ✓ CLAUDE.md is for always-loaded universal standards; a skill is for on-demand, task-specific workflows.

Check your understanding

4 questions written for this lesson, then one from the CCAR-F question bank on the same topic. Every answer option is explained, including the ones you did not pick. Nothing is stored.

Sources

• Extend Claude with skills
• Explore the .claude directory
• Extend Claude Code
• How Claude remembers your project
• Configure permissions
• Commands reference
• The CCAR-F exam guide, summarised