Claude Architect WorkshopPDFEPUBlearnwithparam.comkaas.team

Foundations, lesson 8

Commands and skills

A repeated prompt becomes a skill with limits

The team pastes the same review prompt into Claude every day. When someone saves it as a skill, the skill reads the whole diff inside their session. A long diff fills the session before the real work starts. This is the agent at Lumen Supply, an online electronics shop. You will watch a plain skill flood a session, then fix it with three lines of frontmatter.

I doWatch the failure and its fix.

A skill is a prompt the project keeps

A skill is a SKILL.md file. The file holds a name, a description that tells Claude when to use it, and the prompt itself.

It lives in the project, so a clone brings it to the whole team. A personal skill lives in the home folder and follows one person.

A skill suits work a person starts by name, such as a review. A rule every edit must follow belongs in project memory, and a rule for some files belongs in a path rule. Those two load by themselves, so nobody has to remember to call them, and a missed call would drop the rule.

A forked skill reads the diff on its own. Only its summary comes back.You/review a diffYour sessionstays smallForked skillreads with Read onlythe skill file lives in the project, so the team shares itA forked skill reads the diff on its own. Only its summary comes back.You/review a diffYour sessionstays smallForked skillreads with Read onlythe skill file lives in the project, so the team shares it

The review runs and the session stays small

A colleague types /review with a 1,000-line diff file. The skill reads it and finds the rounding bug. Your session made no model calls of its own.

The skill ran in a fork, a separate context that returns only its result. The fork read the diff with tokens of its own, about as many as the starting skill spends in your session, and only its review came back.

Open the reply card to read the whole review.

  1. Colleague/review diffs/big.diff
    Show the result
    /review diffs/big.diff
  2. Your session0 turns; the fork used 27,552
    Show the result
    Your session took 0 tokens in 0 model turns. Tokens used by a fork, outside your session: 27,552.
  3. Claude- average calls reduce without an initial value, so average([]) throws a TypeError. - average returns a float in cents…
    Show the result
    - average calls reduce without an initial value, so average([]) throws a TypeError.
- average returns a float in cents (the trailing comment flags this as a rounding bug) and is not rounded or converted to an integer like the PRICE_* constants.
- The hunk header @@ -1,3 +1,1000 @@ says three original lines were replaced, but the hunk has no - lines, so the diff is malformed or drops the original three lines.
- The constants jump from PRICE_0999 to the average function with no PRICE_1000, so the numbering is capped at 999 and any later price entry would need a different scheme.

Your session made 0 model calls. The fork used 27,552 tokens of its own, and only its review came back.

The skill file as written

The description tells Claude when the skill applies. The body is the prompt, and it reads the diff named in $ARGUMENTS. The starting file has nothing else, so it runs in your session and pre-approves no tools.

starter/SKILL.md
1---2name: review3description: Review a diff file for bugs.4---56TODO(workshop): this skill runs in your main session and pre-approves no tools.7Give it a hint for its argument, fork it and pre-approve only Read.89Read the diff file named in $ARGUMENTS and list the bugs you find, one short10line each. Do not edit anything.

Where does the diff get read?

Take a review of a 1,000-line diff with the starting skill. The skill has no context line and no allowed-tools line.

Predict: Where does Claude read the diff?

  1. AIn your own session, so the diff sits there with everything else.
  2. BIn a separate context, so your session stays small.
Show the answer

A. Without context: fork, a skill is a prompt added to your session. Every read it makes lands there too.

The starting skill fills the session

This is the same review with the starting skill. The review is fine, but your session pays for every token of the reading, and the whole diff stays in your context. The result card is red.

The session card shows the count. The small diff costs about a quarter as much.

This is a real Claude Haiku 5.5 run through claude -p, recorded once and replayed here.

  1. Colleague/review diffs/big.diff
    Show the result
    /review diffs/big.diff
  2. Your sessiontook 29,570 tokens in 2 turns
    Show the result
    Your session took 29,570 tokens in 2 model turns. Tokens used by a fork, outside your session: 0.
  3. Claude- src/prices.ts:1004: average calls reduce with no initial value, so an empty array throws a TypeError instead of returning…
    Show the result
    - src/prices.ts:1004: average calls reduce with no initial value, so an empty array throws a TypeError instead of returning a value.
- src/prices.ts:1004: the comment says "rounding bug: float cents", but the function never rounds. Integer-cent inputs can return fractional cents.
- src/prices.ts:1: the hunk header says the old file has 3 lines (-1,3), but the diff has no - lines, so the patch can't apply cleanly to a file that has those 3 lines.

I read the diff only and didn't edit anything. The repo isn't a git repository, so I couldn't check these against the source tree.

The review ran in your session, which took 29,570 tokens in all.

Fork it, limit it, hint its argument

With context: fork, the skill runs apart and returns only its result. With allowed-tools: Read, the fork reads without asking. argument-hint tells a person what to type after the name. The solution file also pins the model to Claude Haiku 5.5 and ends the description with the trigger phrase "Use when asked to review a diff."

The line only names what the skill may use without asking. A tool that settings deny stays denied.

What happens when a colleague runs the review.ColleagueClaudeSkill/reviewrun the skillsummaryreview
SKILL.mdgreen lines are what the fix adds
1---2name: review3description: Review a diff file for bugs. Use when asked to review a diff.4argument-hint: <diff file>5context: fork6allowed-tools: Read7model: claude-haiku-5-58---910Read the diff file named in $ARGUMENTS and list the bugs you find, one short11line each. Do not edit anything.
We doChange one setting at a time and predict.

The same diff ends differently

Run the big diff with the starting skill, then with the forked skill. The card marked "This is where the runs split" shows what your session took: tens of thousands of tokens against no model calls at all. The fork spent about as many of its own, outside your session.

The review itself is as good in both. The difference is where the reading happened.

This part is interactive in the lab: run ./workshop watch commands-skills.

Commands and skills side by side

A command is one markdown file named for what it runs. A skill is a directory with a SKILL.md, optional frontmatter and support files. A file in .claude/commands/ and a skill both give you /name.

Where it lives Who gets it
.claude/skills/ in the repository everyone who clones it
~/.claude/skills/ in a home folder only that person

A personal variant of a team skill gets a different name. The argument arrives as $ARGUMENTS, or as $0 and $1 by position, counting from zero.

This part is interactive in the lab: run ./workshop watch commands-skills.

Try it: skill and diff

Change one setting at a time. Pick the small diff or the big one, then switch between the starting skill and the fix.

Every combination is a recorded run, so this works with no internet. The small diff hides the problem, because a session of several thousand tokens looks like any other review.

This part is interactive in the lab: run ./workshop watch commands-skills.

The same skill runs in Claude Code

The harness copies your SKILL.md into a sandbox project and runs claude -p "/review diffs/small.diff". It reads the skill's settings back and reads two numbers from the CLI's usage report: the tokens your session used and the tokens the fork used. Replay needs nothing installed. A live run (LIVE=1) needs the claude command-line tool installed and signed in.

This is a real Claude Haiku 5.5 run.

app/agent.pyfile: 110 lines
···17 lines not shown18from .tickets import BUG, FLOOD, Ticket1920type Run = Callable[..., Json]2122FIXTURE = Path(__file__).parent / "fixture"232425def frontmatter(text: str) -> dict[str, str]:26 """The keys between the two `---` lines of a SKILL.md, key to value."""27 head = text.split("---")[1] if text.startswith("---") else ""28 pairs = (line.split(":", 1) for line in head.splitlines() if ":" in line)2930 return {k.strip(): v.strip() for k, v in pairs}313233def fingerprint(code: Path) -> str:34 """A short hash of the skill file, so a recording names its content."""35 return hashlib.sha256((code / "SKILL.md").read_bytes()).hexdigest()[:10]363738def build_sandbox(code: Path, into: Path) -> Path:39 """Copy the diffs, then the learner's skill, into `into`."""40 project = into / "lumen-shop"41 shutil.copytree(FIXTURE, project)4243 skill = project / ".claude" / "skills" / "review"44 skill.mkdir(parents=True)45 shutil.copy(code / "SKILL.md", skill / "SKILL.md")4647 return project484950@dataclass51class Handled:52 """One review: the reply and how much of your session it used."""53···32 lines not shown86 request = cli.build_request(87 ticket.text,88 f"lumen-shop:{fingerprint(code)}",89 allowed_tools=["Read", "Skill"],90 )91 with tempfile.TemporaryDirectory() as tmp:92 result = llm(request, sandbox=build_sandbox(code, Path(tmp)))9394 skill = frontmatter((code / "SKILL.md").read_text())95 tokens = int(result["session_tokens"])96 apart = int(result["skill_tokens"])9798 return Handled(99 ticket,100 result["result"],101 int(result["num_turns"]),102 tokens,···8 lines not shown
  1. Colleague/review diffs/small.diff
    Show the result
    /review diffs/small.diff
  2. Your session0 turns; the fork used 11,896
    Show the result
    Your session took 0 tokens in 0 model turns. Tokens used by a fork, outside your session: 11,896.
  3. ClaudeOnly one change in the diff, in src/cart.ts: - total now divides the cent sum by 100, so it returns dollars as a float while…
    Show the result
    Only one change in the diff, in src/cart.ts:

- total now divides the cent sum by 100, so it returns dollars as a float while its signature and name still say cents. Any caller expecting integer cents will get wrong amounts.
- The result is a non-integer float (e.g. 0.07), so further money arithmetic or equality checks on it can pick up floating-point error.
- The function's return type is still number, so TypeScript won't flag callers that treat the value as cents.

I made no edits.

Your session made 0 model calls. The fork used 11,896 tokens of its own, and only its review came back.

You doFix the starting code, then test yourself.

You do: fix the review skill

Copy the starting file and open work/commands-skills/SKILL.md. The review skill runs in your main session, pre-approves no tools and gives no hint for its argument. Its description never says when to use it.

Terminal
./workshop start commands-skills
./workshop check commands-skills
./workshop watch commands-skills

The checks want a description with "Use when", an argument-hint, context: fork, allowed-tools: Read and nothing more, and the workshop model.

Check your understanding

Answer each question, then read why every option is right or wrong. The wrong options are the mistakes engineers make on the job.

1. A team pastes the same review prompt into each session, and five teammates now hold five different versions. What is the best fix?

  1. AKeep the prompt on a wiki page and ask each teammate to copy the latest version.
  2. BSave it as a project skill that is committed, so every clone runs the same review.
  3. CSave it as a skill in one teammate's home folder, which the others pick up automatically.
  4. DPaste the prompt into the project memory so that it loads on all 200 requests a day.
Show the answer

Answer: B

  • A Each copy drifts the first time someone edits it, which is how you got five versions.
  • B Correct. A committed skill is one file that travels with the repository.
  • C A home folder skill follows one person. A teammate's clone does not include it.
  • D Memory loads on every request. A skill loads only when the review runs.

2. A review skill reads a 4,000-line diff, about 48,000 tokens, and fills the main session. Which frontmatter line keeps that reading out of the session?

  1. Aallowed-tools set to Read, which stops the reading from landing in the session.
  2. Bargument-hint set to a diff path, which makes the skill check its input first.
  3. Ccontext set to fork, so the skill runs apart and returns a summary.
  4. DA longer description, so Claude reads the diff more carefully.
Show the answer

Answer: C

  • A The list names what may run without asking. Reads by Read still land in the session.
  • B A hint labels the argument for the person typing. Nothing checks it.
  • C Correct. A fork gives the skill its own context, and only its summary comes back.
  • D The description helps Claude choose the skill. It does not move where the work is done.

3. A review skill edited two files while it was reviewing, and a review must only read. What is the best fix?

  1. ATreat allowed-tools as a note for readers and rely on a sentence in the body instead.
  2. BTurn the skill into a command, because commands cannot edit files.
  3. CFork the skill, because a fork hides its edits from the main session.
  4. DList only Read in allowed-tools, so no write tool is pre-approved for the skill.
Show the answer

Answer: D

  • A The list is a real setting. A sentence in the body is the weaker control.
  • B A command file is a skill without extras. It has the same tools available.
  • C A fork moves where the work runs. It does not change what the skill may use.
  • D Correct. With only Read listed, an edit is not pre-approved and has to ask first.

4. Which two statements about skill frontmatter are true? Select two.

  1. AAn argument-hint is checked, and a call with the wrong argument is refused.
  2. Bcontext set to fork runs the skill apart and returns a summary.
  3. CA skill's full body loads in every session, so a long one costs tokens on each of 200 requests.
  4. DAn allowed-tools list names the tools the skill may use without asking.
Show the answer

Answer: B, D

  • A The hint is a label shown while typing. No check refuses a call.
  • B Correct. The fork gives the skill its own context.
  • C The description is what loads up front. The body loads when the skill runs.
  • D Correct. The list pre-approves those tools for the skill.

5. A colleague runs the review but forgets the diff path on 3 of 10 runs. What is the best fix?

  1. ASet argument-hint to show that a diff file goes after the name.
  2. BLoad the skill in every session so Claude remembers the path.
  3. CWrite the path into the skill body, so the skill reviews one diff only.
  4. DFork the skill so the missing path is filled in from the summary.
Show the answer

Answer: A

  • A Correct. The hint shows the expected argument while they type the name.
  • B Loading more does not tell the person what to type.
  • C A fixed path stops the skill from reviewing any other diff.
  • D A fork changes where the work runs, and it does not supply a missing argument.

6. A developer keeps a personal review shortcut that calls their own scripts. It should not reach the other 30 people on the team. Where should it live?

  1. AIn the project's skills folder, since a skill there stays personal.
  2. BIn the project's commands folder, since commands stay personal.
  3. CIn the skills folder of their own home directory.
  4. DIn a forked project skill, because a fork hides it from the team.
Show the answer

Answer: C

  • A Everything in the project's skills folder is cloned by all 30 people.
  • B A command in the project is cloned too. Where the file lives decides who gets it.
  • C Correct. A user-level skill stays on that machine.
  • D A fork decides where the work runs, not who can see the file.

7. A teammate wants a personal variant of the team's review skill with 2 extra checks, and keeps the team one too. What is the best way?

  1. AEdit the team's file in place, since a user skill is shared anyway.
  2. BAdd the 2 checks to the description of the team skill.
  3. CSave the variant under the same name in the project, since commands and skills merge.
  4. DSave the variant in the home skills folder under a different name.
Show the answer

Answer: D

  • A An edit in the project changes the review for all 30 people.
  • B The description says when to use the skill. The checks belong in the body.
  • C A project file is shared, and two files with one name compete for the same command.
  • D Correct. A different name at user level keeps both skills available.

8. Which two statements compare a command file with a skill folder? Select two.

  1. AA skill folder can hold support files next to its SKILL.md.
  2. BA command and a skill are different features that cannot share a name.
  3. CA skill can set frontmatter such as a fork and a tool list.
  4. DA skill loads its full body into every session, and a command does not.
Show the answer

Answer: A, C

  • A Correct. A skill is a directory, so it can carry extra files.
  • B A command file and a skill both create the same slash name and work alike.
  • C Correct. Frontmatter is where a skill sets its fork and its tools.
  • D Only the description loads up front. The body loads when the skill runs.

9. A terraform convention must apply every time Claude edits a .tf file, with nobody typing a command. Which choice fits?

  1. AA skill that each developer runs by name before editing a .tf file.
  2. BA rule file with a paths glob that matches .tf files, so it loads by itself.
  3. CA shorter version of the rule, kept in project memory for every request.
  4. DA skill that Claude loads into every session whether or not a .tf file is open.
Show the answer

Answer: B

  • A A skill waits to be called, so a developer who forgets drops the rule.
  • B Correct. A path rule loads by itself when Claude works with a matching file, and costs nothing otherwise.
  • C A shorter rule still loads on every request, and it may lose detail terraform needs.
  • D A skill is not loaded by default into every session, and this would not limit the cost to .tf files.

10. A review reads a 1,000-line diff and should run only when a person asks for it. Which choice fits?

  1. AA skill with context fork, which a person starts by name.
  2. BA rule file whose paths glob matches diff files, so it runs on its own.
  3. CA paragraph in project memory that tells Claude to review each diff it sees.
  4. DA rule file plus a hook that starts the review when a diff file opens.
Show the answer

Answer: A

  • A Correct. A skill runs when called, and the fork keeps the reading out of the session.
  • B A path rule adds guidance when a file matches. It does not run a task on demand.
  • C Memory loads on every session and costs tokens whether or not a diff is open.
  • D A rule only supplies text, and a hook adds code to do what calling a skill already does.

11. Which two statements compare a skill with a path rule? Select two.

  1. AA skill must list a glob in its frontmatter, or Claude can never pick it.
  2. BA path rule loads by itself when Claude touches a file matching its glob.
  3. CA path rule runs only when a person types its name, the way a command does.
  4. DA skill runs when a person types its name, as in /review with a diff file.
Show the answer

Answer: B, D

  • A A glob is optional. A person starts a skill by name, or Claude picks it from its description.
  • B Correct. The path match switches the rule on, with no command from anyone.
  • C Nobody calls a path rule. It loads when a matching file is in play.
  • D Correct. A skill is a prompt that someone can start by name.

12. A money rule of 200 tokens must apply to all 500 files in the repository. Where should it live?

  1. AIn a skill that developers call before each edit.
  2. BIn a path rule with a glob that lists every folder, plus a hook for the rest.
  3. CIn a forked skill, so the rule stays out of the session.
  4. DIn project memory, which loads for every file with no command.
Show the answer

Answer: D

  • A A skill must be called each time, and a missed call drops the rule.
  • B A long glob list still misses files, and the hook adds a moving part.
  • C A fork hides the work from the session, and a rule the model must follow has to be in its context.
  • D Correct. A rule all files need loads by itself from project memory.

Play: predict the output

This skill body never says where the argument goes.

markdown
Review the diff for bugs and list each one in a short line.
Do not edit anything.

Predict: You type /review changes.diff. Does Claude see the file name?

  1. AYes. Claude Code adds it to the end of the skill as a line that starts with ARGUMENTS.
  2. BNo. The skill has no placeholder, so the argument is dropped.
Show the answer

A. An argument with no placeholder is appended, not lost. Put $ARGUMENTS where the file name belongs, and add an argument-hint so people know what to type.

References

  • Skills: every front matter field, including context and allowed-tools.
  • Slash commands: how a skill becomes a command you type.
  • Settings: how permission rules decide which tools ask first.
  • Claude Code memory: why a rule you always want is memory, not a skill.
  • Agent skills: how skills load only what a task needs.

Conclusions

  • A repeated prompt becomes a skill file that the project keeps and the team shares.
  • context: fork keeps a skill's reading out of your session.
  • allowed-tools pre-approves only the tools a skill's job needs.

You can now turn a pasted prompt into a shared skill that stays small and safe.

Skill

A SKILL.md prompt that Claude loads when the task fits

Fork

Running the skill in its own context, so only its result returns

Allowed tools

The tools a skill may use without asking; settings can still deny them

Argument hint

A short label that shows what to type after the skill's name