Rubric
Contents — domains, guide and mocks

Custom slash commands and skills

CCAR-F 3.211 min read · checked 21 September 2026

Task statementCreate and configure custom slash commands and skills

How a skill loads: progressive disclosure

  1. Descriptionalways in context, so Claude knows it exists
  2. Invokedby you (/name) or by Claude when relevant
  3. SKILL.md bodyfull instructions load and stay for the session
  4. Supporting filesreference.md, scripts — read only if needed
Only the description sits in context all the time. The body loads when the skill is invoked, and supporting files load only if Claude opens them — so a skill can hold far more than you’d ever put in CLAUDE.md.

Commands and skills are now one mechanism

Claude Code used to have two ideas: custom slash commands (a Markdown file in .claude/commands/) and skills (a folder with a SKILL.md). The current documentation says custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way. Existing command files keep working; if both exist with the same name, the skill wins.

Command file versus skill folder

.claude/commands/review.md

  • A single Markdown file
  • Creates /review
  • Still supported — existing files keep working
  • No room for bundled reference files or scripts

.claude/skills/review/SKILL.md

  • A folder: SKILL.md plus any supporting files
  • Creates /review — and wins if both exist
  • Frontmatter controls who invokes it and how it runs
  • The recommended format for new workflows

Where a skill lives decides who gets it

The same scoping logic as CLAUDE.md applies (see 3.1). A skill in the repository is shared through version control; a skill in your home directory follows you across projects but no one else sees it.

LocationPathWho can use it
Project.claude/skills/<name>/SKILL.md (or .claude/commands/<name>.md)Everyone who clones the repo
Personal~/.claude/skills/<name>/SKILL.md (or ~/.claude/commands/)You, in every project
EnterpriseDeployed through managed settingsEveryone in the organisation
Plugin<plugin>/skills/<name>/Whoever installs the plugin; invoked as /plugin-name:skill-name
Nestedpackages/api/.claude/skills/<name>/Discovered when Claude works in that part of the tree

When two skills share a name, enterprise beats personal and personal beats project. Plugin skills never collide because they are namespaced. A team workflow that everyone must run the same way therefore belongs in the project’s .claude/skills/ and is reviewed like code; a personal shortcut belongs in ~/.claude/skills/.

Anatomy of a SKILL.md

A skill is YAML frontmatter followed by Markdown instructions. The frontmatter must start on the very first line, or the whole file is treated as content. The body is the prompt Claude follows when the skill runs.

.claude/skills/fix-issue/SKILL.mdmarkdown
---
name: fix-issue
description: Fix a GitHub issue end to end. Use when asked to fix issue #N.
argument-hint: [issue-number]
disable-model-invocation: true      # only a person can start this
allowed-tools: Bash(gh issue view *) Bash(npm test *)
---
Fix GitHub issue $ARGUMENTS.

## Recent commits (injected before Claude reads this)
!`git log --oneline -5`

1. Run `gh issue view $ARGUMENTS` to read the issue
2. Find the relevant code and existing patterns
3. Write a failing test that reproduces the issue
4. Fix it and run `npm test` until it passes
5. Summarise the change and the test you added
FieldWhat it does
descriptionWhat the skill does and when to use it. Claude reads this to decide whether to invoke the skill. Combined with when_to_use, it is truncated at 1,536 characters in the listing — put the key use case first.
argument-hintAutocomplete hint such as [issue-number].
disable-model-invocationtrue means only a person can run it; Claude can’t trigger it and its description is not loaded.
user-invocablefalse hides it from the / menu; Claude can still load it as background knowledge.
allowed-toolsPre-approves the listed tools for the turn that invokes the skill, so they run without a permission prompt.
disallowed-toolsRemoves tools from Claude’s pool while the skill is active.
context: fork + agentRuns the skill in an isolated subagent; agent picks which one (for example Explore).
model / effortOverride the model or effort level for this skill.
pathsGlob patterns; Claude loads the skill automatically only when working with matching files.

In the body, $ARGUMENTS expands to everything typed after the command, and $0, $1 (short for $ARGUMENTS[0], $ARGUMENTS[1]) pick out positional arguments. An exclamation mark followed by a backticked command, like the git log line above, runs that command before Claude sees the skill and pastes its output in — useful for feeding live state into the prompt. Supporting files in the skill folder (a reference.md, a script) are linked from SKILL.md and read only when needed.

Who may invoke it

By default both you and Claude can invoke a skill: you by typing /name, Claude by matching your request against the description. That default is right for knowledge (“our API conventions”) but wrong for anything with side effects. You don’t want Claude deciding to deploy because your code looks ready.

Choosing the invocation setting

Who should trigger this skill?
  • Has side effects (deploy, send)
    Person onlytyped as /name; Claude can’t start it
  • Background knowledge only
    Claude onlyloaded when relevant; hidden from menu
  • Useful either way
    Eitherthe default setting
“Person only” is disable-model-invocation: true. “Claude only” is user-invocable: false. Leave both unset for the default.

Running a skill in isolation with context: fork

A normal skill runs inline: its instructions join the main conversation and everything it reads fills your context. With context: fork, the skill runs in a subagent with its own fresh context; the skill body becomes the subagent’s task, and only its result comes back. This suits skills that read a lot (codebase research, log analysis) or that you want kept away from the main session’s history. The subagent does not see your conversation, so the skill must carry everything it needs.

A forked skill, message by message

Developer
Main session
Forked subagent
Step 1: Developer to Main session: /trace-auth token refresh
Step 2: Main session to Forked subagent: Skill body + arguments as task
Step 3: Forked subagent : Grep, read 40 files
Step 4: Forked subagent to Main session: Short findings summary
Step 5: Main session to Developer: Answer, main context still lean
The main session sends one task and gets one summary back. The dozens of file reads stay in the subagent’s context.

Traps the wrong answers are built from

Tempting but wrongDo this instead
Leaving a deploy or “send” workflow with default invocationSet disable-model-invocation: true so only a person can trigger side effects.
Using allowed-tools to lock a skill downIt only pre-approves tools; use disallowed-tools, a restricted agent via context: fork, or permission rules to restrict.
Putting a team workflow in ~/.claude/skills/Commit it to the project’s .claude/skills/ so everyone gets the same version.
A vague description such as “helper for stuff”State what it does and when to use it, key use case first, so Claude can match requests to it.
Running a file-heavy research skill inlineAdd context: fork so the reading stays in a subagent and only the summary returns.

You should now be able to

  • Create a skill (or legacy command file) at project or personal scope according to who should use it.
  • Write frontmatter that sets the description, argument hint and invocation control.
  • Use $ARGUMENTS, positional arguments and ! command injection in a skill body.
  • Explain what allowed-tools does and does not do, and how to restrict tools instead.
  • Decide when a skill should run in a forked subagent with context: fork.
  • Choose between CLAUDE.md and a skill for a given piece of guidance.

Practice questions

Original questions written for this lesson, in the exam’s style. Answer first, then open the reasoning — every option is explained, including why the wrong ones are tempting.

  1. Question 1

    A payments team creates .claude/skills/release/SKILL.md, which tags a version and publishes it to the package registry. A week later, during an unrelated refactor, Claude runs the release skill on its own after tests pass.

    Which change prevents this while keeping /release available to engineers?

    1. ASet user-invocable: false in the skill’s frontmatter.
    2. BAdd a CLAUDE.md line telling Claude never to release on its own.
    3. CSet disable-model-invocation: true in the skill’s frontmatter.
    4. DMove the file to ~/.claude/skills/release/SKILL.md.
    Show answer and reasoning
    1. AIncorrect. That does the opposite: it hides the skill from people while Claude can still invoke it.
    2. BIncorrect. Advisory text can be overlooked; frontmatter gives a direct control over who may invoke the skill.
    3. CCorrect. With this set, only a person can invoke the skill, and its description is not loaded for Claude to match against.
    4. DIncorrect. Changing scope changes who has the skill, not whether Claude may trigger it — and it removes it from teammates.

  2. Question 2

    A developer writes a skill with allowed-tools: Read Grep Glob, expecting it to be read-only. During a run, Claude edits a file after the user approves an Edit permission prompt.

    What explains this behaviour?

    1. Aallowed-tools pre-approves the listed tools but does not remove other tools.
    2. Ballowed-tools only applies to skills stored in .claude/commands/.
    3. CThe skill needed context: fork for allowed-tools to be enforced.
    4. DTool names in allowed-tools must be written in lowercase to take effect.
    Show answer and reasoning
    1. ACorrect. The documentation states every tool remains callable; unlisted tools fall back to normal permission settings, which is why the prompt appeared.
    2. BIncorrect. Command files and skills share the same mechanism; the field behaves the same way in either.
    3. CIncorrect. Forking changes where the skill runs; it doesn’t turn allowed-tools into a restriction.
    4. DIncorrect. Tool names are written as they appear (Read, Grep); casing isn’t the issue.

  3. Question 3

    A hospital software team has a /audit-phi-logging skill that scans hundreds of service files for places where patient identifiers might be logged. After it runs, developers find their session slow and cluttered.

    What is the most appropriate change?

    1. AMove the skill’s instructions into the project CLAUDE.md.
    2. BAdd context: fork so the scan runs in its own subagent.
    3. CShorten the skill’s description so it takes less context.
    4. DRun /clear before every use of the skill.
    Show answer and reasoning
    1. AIncorrect. That loads the instructions into every session and does nothing about the file reads filling context.
    2. BCorrect. A forked skill runs in its own context; the file contents stay there and the main session receives a summary.
    3. CIncorrect. The description is small; the cost comes from the files the skill reads while running inline.
    4. DIncorrect. This wipes useful context each time and doesn’t stop the scan’s output from filling the new session.

  4. Question 4

    A repository has both .claude/commands/lint.md and .claude/skills/lint/SKILL.md. What happens when an engineer types /lint?

    1. AThe command file runs, because commands take priority over skills.
    2. BClaude Code reports a conflict and runs neither until one is removed.
    3. CThe skill runs; the command file is ignored for that name.
    4. DBoth run, one after the other, in alphabetical order.
    Show answer and reasoning
    1. AIncorrect. It’s the other way round: the documentation says the skill wins when both share a name.
    2. BIncorrect. There’s no conflict error; a defined precedence decides.
    3. CCorrect. Commands and skills are one mechanism, and when a skill and a command file share a name, the skill is used.
    4. DIncorrect. Only one handler runs for a given name.

Practise every question in Domain 3 →

Sources

Drafted with AI assistance and checked against the sources above; expert review is in progress. Spotted an error? Tell us and it gets fixed, dated and listed on how this is written.