The animated scenes show on a laptop or desktop screen.

Skills

Slash commands and skills

Razorpay's payments platform team wants every payment change checked against the same list, and a new joiner doing useful work in the first week. This chapter follows the team's commands and skills from one engineer's laptop to all 40 and shows five problems the team meets in that time: a command only one laptop has, an analysis that fills an engineer's session, a command run without its event name, a skill that runs a migration on the shared database, and one engineer's change that reaches everyone.

What this chapter shows you

  1. The team's commands and skills go in the repository. A command saved in one home folder never reaches the new joiner. A skill is a command kept as a folder, with its instructions in a file called SKILL.md and room for other files beside it.
  2. A skill's text loads only when someone uses it. Rules every task needs go in CLAUDE.md, and procedures that some tasks need go in skills.
  3. context: fork runs a skill in its own subagent. A subagent is a separate Claude worker with its own context. It reads about 40 files, and only one summary reaches the engineer's session.
  4. A skill's settings and its name decide what it can do and whom it reaches. A hint in the menu tells the developer to type the event name, and in the exam guide's reading a list of allowed tools keeps the handler skill away from the shared database. A personal copy of the team's checklist needs its own name, or it replaces the team's command on its owner's laptop.
  5. Check yourself. Pick which of the tech lead's notes belong in a skill, then answer one question in the exam's style.

Part 1: The team's commands and skills go in the repository

Razorpay's payments platform team is about 40 engineers in Bengaluru. They work in one , payments-platform, and use every day. Chapter 2 set up the team's . The tech lead now wants two more things: every payment change checked against the same list before anyone reviews it, and new joiners doing useful work in their first week.

For months she has typed the same review request into Claude Code: check that every amount is an integer in , that every request that creates a payment, refund or payout carries a , an ID that lets Razorpay recognise a repeated request and carry it out only once, that every handler checks the signature Razorpay attaches to each message, X-Razorpay-Signature, before it parses or acts on the message's body, and that logs show only the last four digits of a card. Claude Code lets her save that request once.

A slash command is a saved prompt that runs when someone types its name.

A is a saved prompt that a developer runs by typing / and its name at the Claude Code prompt. The prompt is a file, and the file's name becomes the command's name, so a file called payments-review.md makes /payments-review. The file can start with a few settings between two --- lines, such as a one-line description of the command. When she types /payments-review, Claude Code reads the file and gives the text below those settings to Claude as instructions.

---
description: Team checklist for any payment change
---

Settings between two --- lines, which Claude Code uses. description is a one-line summary of the command, and Claude Code also copies it into the list of commands and skills it gives Claude at the start of every session.

Review the changes I have made against the
payments checklist.

The task Claude receives every time someone types /payments-review. Everything below the settings is English that Claude reads.

1. Every amount is an integer in paise: ₹499 is 49900.
2. Every create call for a payment, refund or payout
   sends a retry key.

The first two checks: amounts are stored in paise, and a repeated create call can be recognised and not carried out twice.

3. Every webhook handler verifies X-Razorpay-Signature
   before it parses or acts on the body.
4. Logs show only the last four digits of a card.

The other two checks: a handler checks the signature Razorpay attaches to each message before it parses or acts on the message's body, which confirms that the event really came from Razorpay, and no full card number reaches a log.

List each problem with its file and line.

What Claude should report back.

Who gets the command depends on where she saves the file. Two places matter for the team, and they work the same way as the two CLAUDE.md locations in chapter 2. .claude/commands/ inside the repository is shared through with everyone who or the repository. ~/.claude/commands/ is in her own on her laptop, where it works in every project she opens and reaches nobody else.

The tech lead's checklist sits in her home folder, so the new joiner does not have it.

The tech lead saved the file as ~/.claude/commands/payments-review.md, because that is where she keeps her own commands. It has worked on her laptop for months. On Monday a new joiner clones payments-platform, types /payments-review, and nothing in Claude Code's menu of commands matches.

Project and personal commands

The tech lead saved the checklist as ~/.claude/commands/payments-review.md in her home folder. When she types /payments-review, Claude Code looks for that file in her home folder and in the repository, and finds it in her home folder.

Claude Code gives the file's four checks to Claude as instructions. Claude works through them one by one against her changes.

On Monday a new joiner clones payments-platform and gets everything in the repository. He types /payments-review, and Claude Code finds no such file in his home folder or in the repository, because it exists only on the tech lead's laptop.

A command file in the repository reaches everyone who clones or pulls, and a file in a home folder stays on one laptop. When someone types a command, Claude Code looks in both places.

The command existed on one laptop. Git copies what is inside the repository and never copies a developer's home folder, so no clone or pull could bring the file to the new joiner. The fix is to move the file into the repository's .claude/commands/ and share it, which takes three steps. She the change, which records it in her copy of the repository. She it to the team's , the shared copy on a server that every laptop pulls from. Then she opens a , so that a teammate reviews the file before it is into the team's copy.

Project commands in .claude/commands/

On the new joiner's laptop, Claude Code builds the / menu from two folders: ~/.claude/commands/ in his home folder and .claude/commands/ in his clone of the repository. Neither holds a command file, so /pay matches nothing.

The tech lead moves her file into the repository as .claude/commands/payments-review.md, commits it, pushes it and opens a pull request. A teammate reads the four checks, and the pull request is merged into the team's copy of the repository.

The new joiner runs git pull, and the file arrives in his clone's .claude/commands/. Each of the other engineers gets it with their next pull.

He starts a new session and types /pay. Claude Code finds the file in the repository's folder, and /payments-review is in his menu.

A file in .claude/commands/ is part of the repository, so every engineer who pulls has /payments-review in the next session they start, with no other step. This course prepares for the Claude Certified Architect: Foundations exam, and Anthropic's exam guide for it, version 1.0, asks about this case in its sample question 4. The question's answer is that a team's command that every developer should get on clone or pull goes in .claude/commands/ in the project repository, and that ~/.claude/commands/ is for personal commands. Its other options are CLAUDE.md, which holds instructions and context and cannot define a command, and a .claude/config.json with a list of commands, which Claude Code does not have.

The guide's question calls the command /review. This team named its command /payments-review because current Claude Code already uses /review as another name for its built-in /code-review. The answer is the same for any name.

A skill is a folder whose SKILL.md holds settings and instructions.

A is a folder in .claude/skills/, or in ~/.claude/skills/ for a personal one, that holds a file called SKILL.md. The folder's name becomes the command.

The tech lead's second request is for new joiners. Razorpay sends events such as refund.processed to the team's webhook handlers, and every new has the same shape: check the signature, read the event, update the , and put a beside it. She writes this recipe as a skill, .claude/skills/new-webhook-handler/, which makes /new-webhook-handler.

SKILL.md starts with , the settings at the front of the file. They sit between two --- lines and are written in , a plain format of name: value lines, like the description line in the command file above. Claude Code uses them. After the second --- come instructions in Markdown, which Claude follows. The folder can also hold supporting files, such as a reference.md that lists the fields each Razorpay event carries, which Claude reads only when the instructions send it there.

---
description: Create a handler and a test for one
  Razorpay webhook event
---

The frontmatter, between the two --- lines: settings that Claude Code uses. description says what the skill does. Claude Code also copies it into the list of skills it gives Claude at the start of every session, and Claude reads it there to decide when the skill fits a task.

Create a handler for the $ARGUMENTS webhook event in
services/<service>/src/webhooks/ and a matching test.
Verify X-Razorpay-Signature before parsing the body.

The instructions Claude follows. is a placeholder, and Claude Code replaces it with whatever the developer types after the command, such as refund.processed, as Part 4 shows. Claude Code leaves <service> as it is, and Claude reads it and picks the service folder, such as refunds, that the event belongs to.

For the event's fields, read reference.md.

The line that sends Claude to the supporting file. Without it, Claude does not open reference.md.

A skill folder can also hold scripts, small programs that Claude asks Claude Code to run only when an instruction names them. This skill has a scripts/ folder that none of its instructions names, so Claude never opens it, and it costs nothing in a session.

A skill and a command file both make a command, and a skill can do more: it can carry supporting files, and Claude can load it on its own when a task matches its description, which Part 2 shows.

Note, 22 October 2026. On the exam, .claude/commands/ and .claude/skills/ are two features, and .claude/commands/ is the answer to sample question 4. In current Claude Code, custom commands have been merged into skills: a file .claude/commands/deploy.md and a folder .claude/skills/deploy/ both create /deploy, the commands folder keeps working, and the documentation advises a skill for new work.

Skill folder

The team's command is one file with a one-line description at the top. When the tech lead types /payments-review, Claude Code loads the file, and Claude works through its four checks.

A skill is a folder, here new-webhook-handler. Its SKILL.md holds settings, such as the description, and then the instructions. The folder can also hold supporting files: a reference file and scripts.

Claude Code copies the skill's description into the list of commands and skills that Claude sees. The skill and the command file now appear in that list the same way, each with its name and description.

The tech lead types /new-webhook-handler, Claude Code loads its SKILL.md, and Claude follows the instructions in order. Claude opens the reference file only at the line that names reference.md, and it never opens the scripts.

A command file and a skill folder both make a /name command. A skill's settings sit at the top of SKILL.md with its instructions below them, and Claude opens its supporting files only when an instruction sends it to them.

SKILL.md

In the repository the team's command is the file .claude/commands/payments-review.md, and the skill is the folder .claude/skills/new-webhook-handler/, which holds SKILL.md, reference.md and a scripts/ folder. Each one makes a command.

SKILL.md opens with frontmatter between two --- lines, and this skill sets one field, description. Three more fields the exam names go in this block: context: fork, argument-hint and allowed-tools. Parts 3 and 4 add each one.

Below the second --- come the instructions: the English that Claude reads and follows when the skill runs.

SKILL.md has two parts: frontmatter between the --- lines, which Claude Code uses and which supplies the description Claude sees, and instructions below them, which Claude follows. Parts 3 and 4 add the three fields the exam names when the team needs them, and the end of Part 4 lists every field this chapter uses. A skill is always a folder, so Claude Code does not load a single file such as .claude/skills/review.md, or a folder spelt .claude/skill/, as a skill.

Part 2: A skill's text loads only when someone uses it

Over the month the team adds three more skills: one that traces a refund, one that compares designs for retrying failed , and the release guide for the transfers service, which moves money to businesses' bank accounts in daily batches. By the end of the month the holds the team's command and four skills, five entries in all. Every one of them could have gone into CLAUDE.md instead, which Claude Code reads at the start of every session. What differs is when their text reaches Claude.

Claude sees each skill's description at the start, and its full text only when it is used.

At the start of a , Claude Code puts only each skill's name and description into Claude's . The rest of SKILL.md loads in one of two ways: a developer types the skill's command, or Claude reads the descriptions, decides that a skill fits the task, and loads it with the . Once loaded, the text stays in the conversation for later turns, and Claude Code does not read the file again. Claude opens supporting files such as reference.md only when the instructions send it to them. Anthropic calls this .

These are the five descriptions Claude sees at the start of every session in payments-platform:

  • payments-review: Team checklist for any payment change
  • map-refund-flow: Trace a refund from the API to the transfer file
  • compare-retry-designs: Compare designs for retrying failed webhooks
  • new-webhook-handler: Create a handler and a test for one Razorpay webhook event
  • transfers-release: Release steps for a transfers deploy

Skills load on demand

A session starts on the checkout engineer's laptop. Claude Code gives Claude only the name and one-line description of the team's command and each of the four skills, and keeps their full text in the files.

The engineer types /payments-review. Claude Code loads the command file's full text into the session, and the tokens in use go up by its size.

The engineer types “Add a handler for refund.processed” and names no command. Claude matches the request to the description of new-webhook-handler and loads that skill itself.

The other three skills are still only a name and a description each. When the engineer sends her next message, the command's text and the loaded skill are still in the session.

Until someone uses a skill, it costs only one line of description. It loads when a developer types its command or when Claude matches a task to its description, and its text then stays in the session for later turns.

Progressive disclosure (illustrative token counts)

The session starts. The first API request carries a listing with one line for the command and each of the four skills, about 400 tokens in all. Their full text stays in the files.

The engineer types /payments-review. Claude Code reads payments-review.md and adds its text to the next request, and the command and skill text in context reaches 1,300 tokens.

The engineer types “Add a handler for refund.processed”. Claude reads the skill listing and finds new-webhook-handler.

Claude asks Claude Code to load new-webhook-handler for the event refund.processed, a request called the Skill tool. Claude Code reads that skill's SKILL.md from the repository.

Claude Code adds the skill's text to the conversation and sends it to Claude with the next request. The command and skill text in context is now 2,000 tokens.

The engineer's next message goes up with the command's text and the loaded skill still in the request, and the other three skills still one line each. Claude Code does not read the two files again.

The descriptions cost in every session, and each skill's full text cost tokens only in a session that used it. A loaded skill stays in context for later turns, so it keeps taking tokens in every later request and does not need loading again. Claude chose new-webhook-handler by matching the engineer's message, a request for a for refund.processed, against its description, so a skill that should run on its own needs a description that says what it does and when it fits.

Some skills should never start on their own. transfers-release deploys, which changes something outside the code, so the team adds disable-model-invocation: true to its frontmatter. Only a developer typing /transfers-release can then start it, and its description leaves the listing that Claude sees.

Rules every task needs go in CLAUDE.md, and procedures that some tasks need go in skills.

loads into every session automatically, so it is the place for rules that every task needs. A skill loads only when it is used, so it is the place for procedures and reference material that some tasks need. The team has two items to place: the rule that amounts are integers in paise, which every piece of payment code must follow, and a 300-line release guide for the transfers service, which an engineer needs about twice a month. The team keeps the release guide as a skill, /transfers-release. To shorten CLAUDE.md, an engineer then moves the paise rule into /payments-review, because the review already lists it.

CLAUDE.md or a skill

Three engineers each run a session that loads the same CLAUDE.md and can run /payments-review and /transfers-release. Only the transfers release engineer uses the release guide skill, /transfers-release, so its 300 lines load in that session alone.

The team moves the rule “amounts in paise” out of CLAUDE.md and keeps it only in /payments-review. The refund fix engineer runs the review, so Claude in that session has the rule.

The checkout bug engineer asks for code without running the review. CLAUDE.md no longer has the rule, so Claude writes the amount as 499.00.

The team puts the rule back in CLAUDE.md, so every session has it. Claude in the checkout bug session now writes amount: 49900.

CLAUDE.md loads in every session, so a rule every task needs belongs there. A procedure that only some tasks need belongs in a skill, which costs tokens only in a session that uses it.

Token cost of CLAUDE.md and skills (illustrative token counts)

With the release guide in CLAUDE.md, 4,500 tokens of release steps load into every session of all 40 engineers, including the refund fix and checkout bug sessions, which have nothing to do with a release.

As a skill, the release guide loads only in the transfers release session, and only when that session uses it.

With the paise rule only in /payments-review, the refund fix session has it because it ran that skill. The checkout bug session never loads it, and its code stores ₹499 as 499.00.

With the paise rule back in CLAUDE.md, every session has it, and the checkout bug session writes 49900.

In CLAUDE.md, the release guide was in every session, including the many that had nothing to do with a release. When the paise rule was kept only in a skill, it was missing from every session that did not load that skill. The exam guide's words are: skills for “task-specific workflows” that run when asked, and CLAUDE.md for “universal standards” that always load.

Neither file can force Claude to follow a rule. The team has three places for a rule, and they differ in when Claude sees it and whether anything enforces it:

  • CLAUDE.md loads into every session. Claude reads it as guidance, and nothing checks that Claude followed it.
  • A skill loads only in a session that uses it. Claude reads it as guidance too.
  • A or a is applied by Claude Code to every tool call in every session that uses the team's settings, and it can block the call, so the rule holds even when Claude does not follow the text.

A rule that must hold every time, such as never running a migration on the shared database without review, therefore needs a hook or a deny rule. A deny rule is one line in the team's settings, such as Bash(pnpm run migrate *), and chapter 8 builds hooks step by step. Conventions that must apply automatically to certain files, such as the test style for every .test.ts file, go in in .claude/rules/, which chapter 2 set up for this same team. Kept in a skill, they would apply only in sessions that loaded it.

The paise rule appears in both places for different jobs. CLAUDE.md makes Claude follow it while it writes code, and /payments-review checks finished code against it. Only CLAUDE.md is present in every session.

Part 3: context: fork runs a skill in its own subagent

An analysis run inside the engineer's session fills it with file contents.

The checkout engineer is adding a field, refund_reason, to the refund response. Before she edits anything, she runs /map-refund-flow, a skill that traces a refund from the refunds API to the bank's transfer file, the file that tells the bank how much money to send each business. To do that, Claude reads about 40 files and runs a dozen searches. The skill runs inside her session, so everything Claude reads stays in her conversation: about 60,000 of file contents, beside the one change she came to make. Every later request in her session carries those 60,000 tokens, so each turn costs more, the window fills sooner, and her actual task is a small part of what Claude reads.

Only the subagent's final result reaches the main conversation.

is a setting that runs a skill in a separate , a second Claude worker that Claude Code starts with its own . The subagent starts with its kind of agent's , which is the standing instructions Claude Code gives every subagent of that kind. It also gets the skill's text as its task, and most kinds of subagent load the files as well. The subagent does all its reading in its own context, and Claude Code passes only its final result back to the main conversation. The subagent does not see the conversation, so the skill's text has to contain the whole task.

The agent field chooses which kind of subagent runs the skill. map-refund-flow uses , a subagent built into Claude Code that can read files and search them with Grep, Claude Code's search tool, and cannot change them. Chapter 3 covered Explore together with plan mode, as the exam guide does. Claude Code starts Explore without any CLAUDE.md file, the team's or the engineer's own, so that its research stays fast and cheap. A skill run by Explore therefore receives only two things: Explore's system prompt and the skill's text. Explore's system prompt is the same for every Explore subagent and holds nothing from the team's files. The default general-purpose subagent does load CLAUDE.md. The trace reports where the amount changes, and Explore needs the paise rule to read 49900 as ₹499, so the skill repeats that rule.

---
description: Trace a refund from the API to the
  transfer file

The description Claude sees in the skill listing.

context: fork

Run this skill in a separate subagent. Only the subagent's final result comes back to the engineer's session.

agent: Explore
---

Use the built-in Explore subagent, which reads and searches files and cannot edit them.

Trace a refund from the refunds API to the bank
transfer file.
Amounts in this codebase are integers in paise.

The task, written in full, because the subagent sees only this text. The paise rule is repeated because Explore starts without the team's CLAUDE.md.

Return one summary: the files in order, the function
in each, and where the amount changes.

What the subagent sends back, which is all that the main conversation receives.

context: fork

The checkout engineer types /map-refund-flow. The skill runs inside her session, which already holds her conversation, her task “add refund_reason” and the team's CLAUDE.md. Claude starts reading files such as refund.ts.

Claude reads about 40 files, and all of them stay in her session. Her task is now a small part of what Claude holds, and the session is close to its limit.

The team adds context: fork and agent: Explore to the skill's settings and runs it again. The skill's text now repeats the rule that amounts are in paise.

Claude Code gives the new subagent the skill's text and nothing else from her session. Her conversation stays behind, and so does the team's CLAUDE.md, because a skill run by agent: Explore starts without it.

Because of context: fork, Claude Code starts the subagent, here Explore, in its own context with Explore's own system prompt. The subagent reads the skill's text as its task.

The subagent reads the same files, and they fill its own context. The main session does not grow, and her task stays in view.

The subagent sends back one summary, “refund path: 6 files”, and the main session grows only by that summary. The files the subagent read are only in its own context.

With context: fork, a skill's reading happens in the subagent's own context, and only its final result comes back. The subagent gets only the skill's text from the main session, and with agent: Explore it starts without CLAUDE.md.

context: fork with agent: Explore (illustrative token counts)

Without context: fork, the skill runs in the main conversation. Claude's many Read and Grep results take the main context from 18,000 tokens to 78,000, and the engineer's task is one line among about 60,000 tokens of file contents.

The run starts again, with context: fork and agent: Explore in the skill's frontmatter. The main context is back at 18,000 tokens, and Claude Code will now run the skill in a subagent with its own context.

The engineer types /map-refund-flow. Claude Code sends the subagent the Explore agent's system prompt and the skill's text, and the conversation and the team's CLAUDE.md stay behind.

Chapter 16's fork_session, a different feature with the same word, copies the whole 18,000-token session into a new one. The forked skill's subagent starts with about 1,500 tokens: its system prompt and the skill's text.

The subagent asks Claude Code for the same reads and searches. Its own context fills to 61,500 tokens, and the main context stays at 18,000.

Only the subagent's summary comes back: the six files in order and where the amount changes. The main context is 19,200 tokens. The reading stayed in the subagent's context and never entered her session.

Her session grew only by the size of the summary, where the inline run had added about 60,000 tokens of file contents.

The exam guide describes context: fork as running a skill “in an isolated sub-agent context, preventing skill outputs from polluting the main conversation”. It fits skills that produce a lot of intermediate output, such as this codebase analysis, and exploratory work, such as /compare-retry-designs, which asks for three designs for retrying failed webhooks and returns only the comparison table. Two common answers leave the problem in place. Asking Claude to keep its analysis short still puts every file it reads into the session, and running afterwards shrinks the session only after the reading has filled it, by replacing the whole conversation with a summary.

context: fork needs a skill that states a task. A skill that holds only guidelines, such as the team's API conventions, gives the subagent nothing to do, and the subagent returns without a useful result. The word fork also means something different in chapter 16, which covers sessions: a copies the whole conversation into a new session, while a forked skill's subagent starts with the skill's text alone.

Note, 22 October 2026. The exam guide does not cover this. In current Claude Code, since version 2.1.218, the engineer can keep typing while a forked skill runs, and its result arrives when it finishes. background: false in the frontmatter makes Claude Code wait for the result before it takes her next message. The isolation the exam describes is the same either way.

Part 4: A skill's settings and its name decide what it can do and whom it reaches

Typed without an event name, the handler skill writes a handler for the wrong event.

A refunds engineer needs a for the refund.processed event. She types /new-webhook-handler and presses Enter, meaning to give the event name in her next message. Claude Code sends the skill's instructions to Claude as soon as she presses Enter, and Claude starts the work in that same turn; it does not wait for another message. Nothing came after the command, so the skill's instruction asks Claude for a handler without naming an event. Claude picks a plausible event, payment.captured, and writes a handler and a test for it in services/checkout/src/webhooks/, an event and a folder that nobody asked for.

When Claude loads the skill itself, as in Part 2, it passes the event name from the engineer's message as the argument. Typed as a command with nothing after it, the skill gets no event name.

is a short text in the , such as [event-name], that Claude Code shows beside the command in the / menu while the developer types. Whatever the developer types after the command name replaces the placeholder in the skill's text, so /new-webhook-handler refund.processed turns “Create a handler for the $ARGUMENTS webhook event” into “Create a handler for the refund.processed webhook event”. The hint is how the skill asks the developer for the value it needs. Claude Code shows it in its , the list of matching commands that appears while the developer types, and it does not stop anyone from pressing Enter without the value. The skill's instructions therefore also carry a backup line for that case.

argument-hint: [event-name]

A new frontmatter line. Claude Code shows [event-name] beside /new-webhook-handler in the / menu.

If no event name was given, ask for one before
writing any file.

A backup line at the end of the instructions, for the case where the developer still types nothing after the command.

argument-hint

The refunds engineer types /new-webhook-handler and presses Enter without an event name. She means to give the event in her next message.

With no event named, Claude picks a likely one, payment.captured, and writes a handler and a test for it in the checkout service. The engineer wanted refund.processed.

The team adds two lines to the skill: a hint, [event-name], that the menu shows after the command, and an instruction to ask for the event if none is given. The engineer sees the hint, so she types refund.processed after the command.

Claude Code puts refund.processed in place of $ARGUMENTS, and Claude writes the handler and its test in the refunds service.

In a hurry, the engineer runs the command again with nothing after it. The hint cannot stop an empty command, so the backup instruction applies: Claude writes no file and asks which event she means.

The hint shows the developer what to type after the command, and that text replaces $ARGUMENTS in the skill. For a command sent empty anyway, the skill's last instruction is a backup that makes Claude ask.

argument-hint and $ARGUMENTS

The engineer types /new-web, and the menu shows /new-webhook-handler with nothing after it. She presses Enter without an event name.

$ARGUMENTS is empty, so the skill's instruction names no event. Claude writes payment-captured.ts and its test in the checkout service.

The skill gains argument-hint: [event-name] in its frontmatter and a backup line at the end of its instructions: “If no event name was given, ask for one before writing any file.”

She types /new-web again, and the menu now shows [event-name] in grey beside the command. The hint tells her the command needs an event name, so she types refund.processed after the command.

refund.processed replaces $ARGUMENTS, and Claude writes refund-processed.ts and its test in the refunds service.

She sends /new-webhook-handler once more with nothing after it. The hint cannot stop an empty command, so the backup line applies: Claude asks which event and writes no file.

The hint showed the engineer what to type, $ARGUMENTS carried refund.processed into the skill's instruction, and the backup line made Claude ask when she typed nothing. On the exam, argument-hint is the answer whenever a question asks how to prompt developers for a required parameter. A note in , or a line in the skill's instructions on its own, does not show the developer what to type.

The handler skill runs a migration on the shared database without asking anyone.

While creating the refund.processed handler, Claude decides that the handler needs a table, webhook_events, to record which events it has already processed. It writes a , a file of changes to the database's tables, and runs pnpm run migrate, the command that applies migration files to the database, with , Claude Code's tool for running the commands a developer would otherwise type in the terminal. The team's already allow Bash(pnpm run *), where the star matches anything, so any command that starts with pnpm run runs without a . Nobody is asked, and the table is created in the shared development that all 40 engineers use. The team's CLAUDE.md says that a migration is never edited or deleted once it has run, so removing the table needs a second migration.

in a skill's frontmatter lists tools. The exam guide reads the field as a limit on the tools Claude may use while the skill runs. In that reading, a skill that creates files from a pattern, limited to Read, Write, Edit, can read, create and change files and cannot run commands through Bash, which keeps it away from destructive actions. A line in the instructions such as “do not run shell commands” is the wrong answer on the exam, because it is text that Claude reads and can miss. The two drawings below follow the exam guide's reading, and the note after them gives current Claude Code's behaviour.

allowed-tools: Read, Write, Edit

In the exam guide's reading, the tools this skill may use: reading, creating and editing files. Bash is not in the list.

allowed-tools

The refunds engineer runs /new-webhook-handler refund.processed. Claude reads files and writes the handler and its test.

Claude also writes a migration for a webhook_events table and runs pnpm run migrate with Bash. The team's settings allow any pnpm run command without asking, so the table appears in the shared database all 40 engineers use.

The team adds allowed-tools: Read, Write, Edit to the skill and runs it again.

In the exam guide's reading, Claude can now read, write and edit files and cannot use Bash. It writes the same files and leaves the migration for a person to run after review, so the shared database does not change.

In the exam guide's reading, allowed-tools limits a skill to the tools it lists. A skill that only needs to write files then cannot run a command such as pnpm run migrate, even though the team's settings allow it.

allowed-tools: Read, Write, Edit, as the exam guide reads it

The engineer types /new-webhook-handler refund.processed. The request goes to Claude with its tools, among them Read, Write, Edit, Bash, Grep and Glob.

Claude asks Claude Code to write the handler and its test, and two new files appear in the repository.

Claude then asks for Bash(pnpm run migrate). The team's settings allow pnpm run commands without a prompt, so Claude Code runs it, and the webhook_events table lands in the shared database.

The run starts again with allowed-tools: Read, Write, Edit. In the exam guide's reading, Claude can use only those three tools while the skill runs, so Bash, Grep (search) and Glob (find files) are not available.

Claude writes the migration as a file and asks for no shell command. Its reply tells the engineer to run the migration after review, and the shared database does not change.

In the exam guide's reading, with Bash outside the skill's tools, Claude wrote the migration as a file and left running it to a person who can review it first.

Note, 22 October 2026. On the exam, allowed-tools limits a skill to the tools it lists, as the drawings show. Current Claude Code reads the field differently: the listed tools run without a permission prompt for that turn, and every other tool, Bash included, stays available. In current Claude Code, this line alone would not have kept the skill from running pnpm run migrate. The current field that removes a tool while a skill runs is disallowed-tools, as in disallowed-tools: Bash. To stop every session in the repository from running migrations, the team adds a , Bash(pnpm run migrate *), to its settings.

Here is the finished skill, with every line the team added:

---
description: Create a handler and a test for one
  Razorpay webhook event

What the skill does. Claude Code copies it into the skill listing, and Claude matches tasks against it.

argument-hint: [event-name]

The hint shown beside /new-webhook-handler in the / menu, which tells the developer to type an event name after the command.

allowed-tools: Read, Write, Edit
---

In the exam guide's reading, the tools the skill may use. Bash is not one of them.

Create a handler for the $ARGUMENTS webhook event in
services/<service>/src/webhooks/ and a matching test.
Verify X-Razorpay-Signature before parsing the body.
For the event's fields, read reference.md.

The task. $ARGUMENTS is the event name typed after the command, and <service> is a placeholder that Claude fills by choosing the service folder, such as refunds, that the event belongs to.

If no event name was given, ask for one before
writing any file.

The backup for a command sent with nothing after it: Claude asks before writing any file.

These are the frontmatter fields this chapter uses. The exam guide names three of them.

FieldWhat it doesOne of the three fields the exam names
descriptionSays what the skill does. Claude reads it in the skill listing to decide when the skill fits a task.No
context: forkRuns the skill in a separate subagent, and only its final result comes back to the session.Yes
agentChooses the kind of subagent for a forked skill, such as Explore.No
argument-hintText shown beside the command in the / menu, such as [event-name].Yes
allowed-toolsOn the exam, limits the skill to the tools it lists. In current Claude Code, lets those tools run without a permission prompt.Yes
disable-model-invocationWith true, only a developer typing the command can start the skill, and Claude cannot load it on its own.No
backgroundWith false, Claude Code waits for a forked skill's result before it takes the next message.No
nameSets the command the / menu shows. Without it, the folder's name is the command.No

One engineer's refund checks, merged into the team's command, reach every engineer.

The refunds engineer wants three more checks when she reviews refund code: a refund never exceeds the amount the customer paid, so a ₹2,499 payment can never be refunded ₹2,500; partial refunds keep a running total; and every refund status change is handled for both refund.processed and refund.failed. She adds them to the 's .claude/commands/payments-review.md, and her is , because the reviewers saw only three sensible checks. The next morning /payments-review runs her refund checks on checkout and transfers code for every engineer who . Checkout engineers now get three refund findings on code that has no refunds, and they have to read and dismiss them on every review.

She removes her three lines from the team file and tries a second way: a copy of the checklist in her own home folder, ~/.claude/skills/payments-review/, with her three checks added. The copy has the team command's name, so Claude Code now has two files for one name. Claude Code picks between them by two rules: a personal file comes before a project file, and a skill comes before a command file. Her copy is personal and a skill, so both rules pick it, and her /payments-review now runs only her copy.

The / menu shows one plain /payments-review row and does not say which file runs, so nothing tells her that the team's file is skipped. When the tech lead adds a fifth team check, it reaches every engineer's laptop, and her command skips it.

A is a personal skill in ~/.claude/skills/ under a different name, often started from a copy of the team's. A skill's command is its folder's name, unless a name: line in the frontmatter of its SKILL.md sets another, so a personal variant needs its own name in both places. With a different name, the two files no longer share a name, and neither rule comes into play. The variant loads only on the developer's own laptop, in all her projects, and leaves the team's command untouched.

Personal variants

The refunds engineer's personal skill payments-review is the team checklist plus three refund checks. The team's command file has the same name, and Claude Code prefers a personal file to a project file and a skill to a command file.

She types /payments-review, and Claude Code runs her personal copy. The team's file is skipped, and the / menu shows one plain row and does not say which file runs.

The team adds a fifth check, “use the ledger helper”, to its file, and her next pull brings it to her laptop. Her /payments-review still runs her copy, so the new check is missing from her reviews.

She renames her copy to refunds-review and keeps only her three refund checks in it. /payments-review runs the team's file again.

She runs /payments-review and /refunds-review. Claude applies the team's five checks and her three refund checks.

A personal skill with the team command's name runs in place of the team's file, so its owner stops getting the team's updates. A personal skill with its own name runs only when she asks for it.

A personal variant under its own name

The refunds engineer's three checks are merged into .claude/commands/payments-review.md. Every engineer gets them on the next pull, and a checkout review reports three refund findings on charge.ts.

She removes the lines and copies the checklist to ~/.claude/skills/payments-review/. Her personal skill now runs for /payments-review, and the team's file is skipped. Her menu shows one plain row, so nothing tells her which file runs.

The tech lead merges a new team check: every refund is saved through the ledger helper. It lands in the team's file, which her /payments-review skips, so her run does not include it.

She renames her folder to refunds-review and keeps only her three refund checks in it. The team's file runs for /payments-review again, and her menu shows two commands.

She runs both: the team's five checks and her three refund checks.

With the name refunds-review, her copy no longer runs in place of the team's checklist. She runs both commands, her teammates see no change, and every update the team makes to /payments-review reaches her on her next pull. The exam guide's wording for this is a personal variant in ~/.claude/skills/ with a different name, so that teammates are not affected.

Part 5: Check yourself

Pick the notes that belong in a skill.

The tech lead has written eight notes about how the team works with Claude Code. Select every note that belongs in a skill, then check.

Select at least one item first.

Exam question: a personal version of a team skill.

Your team has a project skill at .claude/skills/team-review/SKILL.md that runs the team's standard code review checklist when anyone types /team-review. A developer who works on refund code wants three extra checks for her own reviews, such as a check that a refund never exceeds the amount the customer paid, so a ₹2,499 payment is never refunded ₹2,500. She wants these checks every time she reviews her work. /team-review must keep working the same way for everyone else, and she must keep getting every change the team makes to it. What should she do?

Razorpay appears in this chapter only to explain how Claude Code and Claude work. Razorpay has no connection with these tutorials, and the code, systems, numbers and events in this chapter were written for the lesson. They do not describe how Razorpay works, and Razorpay does not use this code.