After a few days on todo-api you'll notice yourself typing the same thing again and again: "add this endpoint, write the test first, return errors as { error: "..." }, run npm test until it passes". Every time you type it, and every time something gets left out. This lesson turns that paragraph into a command: /add-endpoint POST /todos/:id/restore, one line and you're done.
When a command of your own pays off
The clearest sign: you keep pasting the same instructions, checklist or multi-step procedure. Another sign: part of your CLAUDE.md has grown into a procedure rather than facts. CLAUDE.md loads in every session, while a procedure is only needed when you do that task.
In lesson 3.1 you saw that /code-review and /debug are skills: a prompt handed to Claude. Your own commands work the same way. Custom commands used to be Markdown files in .claude/commands/; they have now been merged into skills. Old files still work, but for new work prefer a skill, because a skill is a folder that can carry scripts and reference files (lesson 3.3). If a skill and a file in .claude/commands/ share a name, the skill wins.
Your first command: /add-endpoint
A skill is a folder containing a SKILL.md file. The folder name is the command you type. In todo-api, create:
.claude/skills/add-endpoint/SKILL.md---
description: Add an endpoint to todo-api with a test first
disable-model-invocation: true
argument-hint: "[METHOD] [path]"
---
Add the $0 $1 endpoint to src/routes/todos.js.
1. Write a failing test in test/todos.test.js first
2. Implement the route; return errors as { error: "..." }
3. Run npm test and keep going until it passesThe file has two parts. Between the two --- lines is the frontmatter (settings written in YAML): a description, who may run it, an argument hint. Below it is what Claude will follow, written the way you'd normally write a prompt.
Three frontmatter mistakes come up often:
- The
---must be the file's very first line. A single# Add endpointheading above it and Claude Code treats the whole file,---markers included, as content and ignores every setting. - If the YAML doesn't parse (a missing colon, uneven indentation), the skill still loads but with no fields set, and all you see is a command that doesn't behave as expected. Run
claude --debugto see the YAML error. - A value with square brackets, such as
[METHOD] [path], must be in double quotes. Without them YAML reads[...]as a list, and two lists side by side are invalid YAML. The skill then losesdisable-model-invocationtoo, and Claude can start the command you meant to keep for yourself.
Where to put it depends on who needs it:
.claude/skills/<name>/SKILL.mdin the repo: a project command. Commit the folder so the whole team gets the same commands, just likeCLAUDE.mdin level 2.~/.claude/skills/<name>/SKILL.mdin your home folder: a personal command, available in every project on your machine.
Type / in Claude Code and /add-endpoint appears in the list, with the [METHOD] [path] hint taken from argument-hint.
Arguments
Whatever you type after the command name is its arguments, and the skill receives them through placeholders:
$ARGUMENTSis all of that text.$0,$1,$2… (short for$ARGUMENTS[0],$ARGUMENTS[1]…) are the parts by position, counting from 0.
Type /add-endpoint POST /todos/:id/restore and $0 is POST, $1 is /todos/:id/restore, and Claude receives "Add the POST /todos/:id/restore endpoint to src/routes/todos.js."
Forgot to put a placeholder in the content? That's fine: Claude Code appends an ARGUMENTS: … line at the end so Claude still sees what you typed. But placeholders in the right spot make the instruction read properly.
Live data from the shell
Sometimes a command needs information that only exists when it runs: the current diff, the branch you're on, test results. Write !`command` in SKILL.md and Claude Code runs that shell command first, before sending the content to Claude, and puts the output in its place. Claude reads the data directly instead of going off to run the command itself.
For example, a /changes skill:
---
description: Summarise my uncommitted changes
---
Uncommitted changes:
!`git diff HEAD`
Summarise these changes in three bullets, then list any risks.For several commands, use a code block opened with ```!.
Two things to remember:
- One failing injected command cancels the whole skill invocation, not just its own placeholder; Claude receives nothing. In bash, any non-zero exit code counts as a failure. For a command that often exits non-zero when nothing is actually wrong, add
|| trueafter it. - Injected commands don't ask for permission while the skill runs; instead they're checked against your permission rules. A command matched by a deny rule cancels the invocation. Outside auto mode, a command that isn't already allowed cancels it too, unless you pre-approve it with
allowed-toolsin the frontmatter.
Who may run a command
When a session starts, Claude Code loads each skill's description so Claude knows what's available; the full content only loads when a skill is invoked. That's why, by default, both you and Claude can run it: you type /changes, or you ask "what did I just change?" and Claude recognises that the skill fits. How Claude chooses, and how to write a good description, is the subject of lesson 3.3.
For commands with real side effects, such as deploying, committing or sending messages, you don't want Claude deciding when they run. Add disable-model-invocation: true: Claude won't start it on its own, and it only runs when you type it. /add-endpoint above uses this flag because it changes code following a procedure you want to kick off yourself.
Where the name sits in your message matters too:
- At the start, as in
/deploy staging: the command runs straight away. - Later in the sentence, as a word on its own, as in "tests pass, go ahead and /deploy to staging": nothing runs directly. The name only gives permission for that message; Claude reads your wording and decides whether to run it.
- To mention a command without permitting a run, leave off the slash: "the deploy skill is broken".
And allowed-tools lets Claude use certain tools without asking, but only for the turn that invokes the skill: the grant ends when you send your next message. To allow something for the whole session, add a rule to your permission settings instead. A safe habit: before running Claude Code in someone else's repo, open .claude/skills/ and see what permissions those skills ask for.
Keep commands short
Once a skill is invoked, its content stays in the conversation for later turns; Claude Code doesn't re-read the file. Every line in SKILL.md is therefore a recurring cost for the rest of the session. Write like the /add-endpoint example: a few clear steps, no long explanations of things Claude already knows.
For todo-api, you leave this lesson with two commands: /add-endpoint to add routes the project's way, and /changes to summarise your work before /diff and /code-review. Commit .claude/skills/ and the whole team has them.
Next lesson: skills aren't only commands you type. Add scripts, reference files and a good description, and Claude will know on its own when to use them.