What You Need to Know
A skill is a named, reusable set of instructions that Claude Code loads on demand. It is a Markdown file that tells Claude how to perform one specific workflow. It can have supporting files and optional YAML frontmatter: a block of settings between --- lines at the top. You run a skill by typing its name as a slash command (/deploy). Claude also loads it itself when a request matches its description. CLAUDE.md is different: it loads in every session, while a skill's instructions enter the conversation only when the skill runs.
This lesson uses one made-up example throughout: a care home whose two developers maintain the app carers use to log medication rounds. They want a shared /meds-check skill for the checks before they release a medication change. One developer also runs long exploratory analyses of the rota code, for herself alone.
The Unified Skills System
Custom commands and skills have been merged into one unified system, the Skills system. Two locations create slash commands that behave the same way. Their file structures differ.
.claude/commands/deploy.mdcreates/deploy. It is a flat Markdown file, and the filename becomes the command name..claude/skills/deploy/SKILL.mdalso creates/deploy. It is one directory for each skill. The directory has the name of the command.SKILL.mdis the required entrypoint inside it.
Because SKILL.md is the required entrypoint, a flat file placed directly inside .claude/skills/ does not create a command. The .claude/skills/ path is the canonical location. .claude/commands/ still works for backward compatibility. Both paths produce the same /command, so existing .claude/commands/ files continue to work unchanged. A command file accepts the same YAML frontmatter as a skill except name and paths. The skills path is recommended because it adds three features the .claude/commands/ path lacks.
- a supporting-files directory alongside the
SKILL.md - automatic discovery, so Claude can load a skill when it matches your intent
- precedence when a skill and a command share the same name: the skill wins
So the care home puts /meds-check in .claude/skills/meds-check/SKILL.md. The skill's checklist sits beside that file as a supporting file. If a .claude/commands/meds-check.md remains, the skill wins.
Two Scoping Levels
Project scope means .claude/skills/ (canonical) or .claude/commands/ (alias) inside your repository. Both are version-controlled and shared via git. Every developer who clones or pulls the repository gets these commands automatically, so a committed skill is shared with everyone who works there. Use project scope for team-wide workflows.
User scope means ~/.claude/skills/ (canonical) or ~/.claude/commands/ (alias). These are personal, not version-controlled and not shared. A skill saved under the home directory loads in every project. Use user scope for individual productivity workflows that other team members do not need.
The care home puts /meds-check in the project path, so both developers have it. The rota analysis is personal, so its owner puts it under ~/.claude/skills/.
A project command can also be one flat file in .claude/commands/. This file gives the care home team a /review command:
<!-- .claude/commands/review.md — creates /review -->
Review the staged changes against our team checklist:
1. Check error handling patterns
2. Verify test coverage for new functions
3. Confirm API naming conventions
4. Flag any hardcoded credentials or secretsKey Concept
The scoping pattern is the same across Claude Code. Project-level (.claude/) is shared via git. User-level (~/.claude/) is personal. This pattern applies to CLAUDE.md, commands and skills, and rules. Memorise this pattern, because it appears throughout Domain 3. Also remember the two file shapes. Skills are directories with a SKILL.md inside. Commands are flat .md files.
Skills Frontmatter: Optional Configuration
The objective names three frontmatter options: context: fork, allowed-tools and argument-hint. .claude/skills/ is the canonical location for configured skills.
context: fork
context: fork runs the skill in an isolated sub-agent context. The verbose output stays contained in the fork, and the main conversation stays free of that output. Without it, skill output enters the main conversation and consumes context window tokens. For verbose skills, this extra output degrades the quality of later responses. This setting suits three kinds of task.
- codebase analysis, which produces extensive file listings and code excerpts
- brainstorming, which generates many alternatives and evaluations
- any task that produces noisy, exploratory output
The care home's rota analysis is codebase analysis, so its skill uses context: fork. If its owner names it /analyse-feature, the frontmatter is at the top of ~/.claude/skills/analyse-feature/SKILL.md:
---
description: "Analyse a feature area of the codebase and report structure, patterns and risks"
context: fork
allowed-tools:
- Read
- Grep
- Glob
argument-hint: "Provide a feature description or area of the codebase to analyse"
---The description line is not one of the three the objective names. Omit it from a real skill and Claude has nothing to match your request against. The skill then runs only when you type /analyse-feature yourself.
allowed-tools
allowed-tools pre-approves the listed tools, so Claude can use them without a permission prompt while the skill is active. It does not restrict which tools are available. Every other tool remains callable. Your normal permission settings still govern any tool that is not listed. Use allowed-tools to let a trusted workflow run without stopping to ask on each call. The rota analysis that reads code is such a workflow.
Current state
Current state (checked 6 October 2026): this pre-approval behaviour is what Claude Code does. Exam guide v1.0 describes the field differently. On the exam, answer with the guide's wording, given at the end of this section.
---
allowed-tools:
- Read
- Grep
- Glob
---To remove tools that Claude can use while a skill runs, list them in disallowed-tools or add deny rules in your permission settings. These two methods are the actual security boundary.
argument-hint
argument-hint is a hint shown during autocomplete to indicate the arguments the skill expects. It improves the developer experience: the inputs are explicit, so nobody has to remember them. It is a label, not an interactive prompt. When you invoke the skill with no arguments, it does not stop and ask for them. For /meds-check, the hint could name the module path.
Current state
Current state (checked 6 October 2026): the skills frontmatter reference defines it as a "Hint shown during autocomplete to indicate expected arguments". Exam guide v1.0 describes it differently, and the right answer at the end of this section follows that wording.
---
argument-hint: "Specify the module path to analyse (e.g., src/api/auth)"
---Current state: description is the most important field
Current state (checked 6 October 2026): the live field list is much longer, and the field that you will use first is description. Claude reads it to decide whether a skill applies to what you just asked. A skill without a useful description only ever runs when you type /name yourself. The docs mark it Recommended rather than required. Omit it and Claude Code uses the first non-empty line of the skill body instead. That line is usually a worse summary than one that you would write. The live list also has disallowed-tools, disable-model-invocation, model, effort and when_to_use. (Source: Claude Code skills docs.)
Skills vs CLAUDE.md
Skills are on-demand, task-specific workflows. Their descriptions are always in context, so Claude knows that they exist. But the full body of a skill loads only when the skill is invoked. A skill is invoked explicitly (/skill-name) or automatically. Claude automatically selects and loads skills whose description matches the user's intent, or skills with a paths field when you work on matching files. Skills with disable-model-invocation: true require explicit user invocation. CLAUDE.md holds always-loaded, universal standards. They apply to every session, with no invocation step.
So do not put task-specific procedures in CLAUDE.md, where they would load in every session. Do not put always-on reference material in skills, where it would be absent until the skill is invoked. API naming conventions for every code generation task belong in CLAUDE.md (or .claude/rules/). A multi-step workflow that analyses the codebase and that you run occasionally belongs in a skill. Conventions for one file type, such as test files, fit path-scoped .claude/rules/ best: they load as always-on context alongside matching files. So the care home's naming conventions belong in CLAUDE.md.
Personal Skill Customisation
Create personal variants in ~/.claude/skills/ (or ~/.claude/commands/) with different names, so teammates are not affected. A personal skill with its own name does not override or conflict with the team version. A care home developer who wants a more verbose /meds-check creates /deep-meds-check there.
Where to Place Custom Commands: Quick Reference
| Need | Canonical location | Also works | Scoping |
|---|---|---|---|
| Team-wide command | .claude/skills/<name>/SKILL.md | .claude/commands/<name>.md | Project (shared via git) |
| Team-wide command with frontmatter config | .claude/skills/<name>/SKILL.md | .claude/commands/<name>.md | Project (shared via git) |
| Personal command | ~/.claude/skills/<name>/SKILL.md | ~/.claude/commands/<name>.md | User (not shared) |
| Universal standards | .claude/CLAUDE.md or root CLAUDE.md | None | Project (always loaded) |
| Personal preferences | ~/.claude/CLAUDE.md | None | User (not shared) |
In the exam
The core distinction here is on-demand workflow versus persistent configuration. The exam tests the split between skills and CLAUDE.md directly. Conventions for every edit belong in CLAUDE.md or .claude/rules/. For verbose output that clutters the main conversation, the answer is context: fork.
The exam guide (v1.0) names three frontmatter options, and a question will test those three. description is not on the guide's list. For two of the three options, the right answer follows the guide, not the current product.
allowed-tools: the guide describes it as restricting the skill's tool access. If a question asks what the field does, answer "restricts".argument-hint: the guide describes it as prompting developers for required parameters when they invoke the skill without arguments. That is the expected exam answer.
On the exam, answer with the guide's wording for both fields. The build exercise below uses current Claude Code behaviour.
Exam Traps
Creating a flat Markdown file directly inside .claude/skills/ (e.g., .claude/skills/review.md) and expecting a /review command
The two paths create the same commands but have different file structures. A skill is a directory containing a SKILL.md entrypoint (.claude/skills/review/SKILL.md); a flat .md file only creates a command under .claude/commands/ (.claude/commands/review.md). A flat file placed directly inside .claude/skills/ does not create a command.
Placing a team-shared command in a user-scoped path (~/.claude/commands/ or ~/.claude/skills/)
User-scoped paths (~/.claude/commands/ and ~/.claude/skills/) are personal and not version-controlled. Team commands that should be available to everyone on clone must go in a project-scoped path (.claude/skills/ or .claude/commands/) inside the repository. Both project-scoped paths create the same commands; .claude/skills/ is the canonical, fuller-featured location.
Thinking skills behave like CLAUDE.md for always-on guidance
Skills load on demand as task-style workflows and do not shape every session by default. CLAUDE.md and .claude/rules/ load automatically into context. For conventions that apply to every edit, use CLAUDE.md or .claude/rules/.
Leaving a verbose codebase-analysis skill to run inline in the main conversation
An inline skill sends all its output into the main conversation, where it consumes context window tokens and degrades later responses. context: fork runs the skill in an isolated sub-agent, so the verbose output stays contained.
Putting task-specific workflows in CLAUDE.md
CLAUDE.md is for always-loaded universal standards. Task-specific procedures (code review workflows, analysis routines, brainstorming templates) belong in skills that are invoked on demand.
Practice Scenario
A team wants a /review command available to everyone who clones the repository. A developer also wants a personal /brainstorm skill that produces verbose codebase analysis output without cluttering the main conversation. Where should each be created and what configuration does the skill need?
Build Exercise
Create Custom Commands and Skills
What you'll learn
- Distinguish between project-scoped and user-scoped command locations
- Configure SKILL.md frontmatter with context: fork, allowed-tools, and argument-hint
- Understand when to use skills vs CLAUDE.md for conventions vs workflows
- Verify scoping boundaries between shared and personal configuration
- Apply the context: fork pattern to isolate verbose output from the main conversation
- Create a project-scoped /review command in .claude/commands/review.md containing a team code review checklist
Why: Project-scoped commands are shared via git so every developer gets them on clone. The exam tests whether you place team commands in .claude/commands/ (project) vs ~/.claude/commands/ (personal).
You should see: A file at .claude/commands/review.md in the repository. Running /review in Claude Code triggers the code review checklist. The command appears when any developer clones the repository.
- Create a personal /brainstorm skill in ~/.claude/skills/brainstorm/SKILL.md with context: fork in the frontmatter
Why: The context: fork frontmatter option isolates verbose skill output from the main conversation. Without it, codebase analysis output fills the context window and degrades subsequent responses. The exam directly tests this concept.
You should see: A SKILL.md file at ~/.claude/skills/brainstorm/SKILL.md with YAML frontmatter containing context: fork. The skill is available only in your sessions, not shared with teammates.
- Add allowed-tools to the brainstorm skill, restricting it to Read, Grep, and Glob (read-only operations)
Why: The exam guide describes allowed-tools as restricting which tools a skill can access, and that is the expected exam answer. Current state (checked 6 October 2026): Claude Code pre-approves the listed tools, so they run without a permission prompt. The actual boundary is disallowed-tools. But the intent is the same: a read-only analysis skill should never be using Write or Bash.
You should see: The SKILL.md frontmatter now includes an allowed-tools list with exactly Read, Grep, and Glob. Under the exam-guide model the skill cannot use Write or Bash. Current state (checked 6 October 2026): in Claude Code the list pre-approves those three tools for use without a permission prompt.
- Add argument-hint to the brainstorm skill: "Provide a feature description or codebase area to explore"
Why: The argument-hint is shown during autocomplete to indicate the arguments a skill expects. It improves developer experience and is one of the three SKILL.md frontmatter options tested on the exam.
You should see: The SKILL.md frontmatter now includes argument-hint. Typing /brainstorm at the prompt shows the hint text alongside the command in autocomplete, indicating what input it expects.
- Test that /review appears for all project users (shared via git) and /brainstorm only for you
Why: This verifies the scoping boundary that the exam repeatedly tests: .claude/ is project-scoped and shared via git, while ~/.claude/ is user-scoped and personal. Confirming this experimentally helps you remember the concept.
You should see: Running /review works in any clone of the repository. Running /brainstorm works only in your session. A colleague or fresh clone without your home directory config does not see /brainstorm as an available command.
- Invoke the brainstorm skill and verify that its verbose output does not appear in the main conversation context
Why: The context: fork option runs the skill in an isolated sub-agent. The main conversation receives only the summary, not the full verbose output. This is critical for preserving context window tokens during exploratory tasks.
You should see: After invoking /brainstorm with a codebase area, the main conversation shows a concise summary of findings. The verbose file listings, code excerpts, and analysis notes are not visible in the main conversation history. Subsequent responses remain high quality because the context window is not filled with exploration output.