Rewrite Unit 2 around a Claude Code workflow

[burtenshaw]

Summary

• restructure Unit 2 into a single Claude Code-focused learning path with a new intro, publish step, quiz, and conclusion
• align the course outline and navigation to match the new Unit 2 scope and certification path
• replace the old starter scaffold with a canonical app.py flow and add a runnable agent/ mini-project for the load/select/compose exercise
• add Unit 2 quiz data and new content covering activation debugging, mid-session iteration, skill-creator, and current hf CLI publishing

Testing

• python3 -m compileall course/units/en/unit2/starter/app.py course/units/en/unit2/starter/agent
• python3 -m json.tool course/quiz/data/unit_2.json >/dev/null
• git diff --check

[mnielan-ant]

[deleted]

[mnielan-ant]

"This exact prompt comes from the Unit 2 draft logs" reads like a leftover authoring note.

Suggested change

This exact prompt comes from the Unit 2 draft logs.

[burtenshaw]

Removed.

[mnielan-ant]

Suggest dropping the rm -rf and keeping both style skills mounted — then the prompt names the one you want. Shows that multiple skills can coexist and that explicit prompting (or /brutalist) picks between them.

Suggested change

	The starter also includes `skills/brutalist/`. Swap it in:
	```bash
	rm -rf .claude/skills/hf-brand
	cp -r skills/brutalist .claude/skills/
	```
	Then ask Claude to restyle `app.py` again. Same app, different personality:
	The starter also includes `skills/brutalist/`. Add it alongside `hf-brand`:
	```bash
	cp -r skills/brutalist .claude/skills/
	```
	Then ask Claude to restyle `app.py` using the brutalist skill specifically. Same app, different personality:

[burtenshaw]

Took this in 1d4c943. The setup now mounts both hf-brand and brutalist, and the second exercise explicitly asks Claude to use brutalist rather than removing hf-brand.

[mnielan-ant]

Suggest shifting the weight from exercise-recall toward concepts that transfer. Q1/2/10 are great as-is; a few others test specific function/file names from one starter (Q4/5/7) or CLI flags (Q9), and Q8's "correct" answer will change if the skill-creator page is retargeted. Draft below keeps the strongest originals (incl. select_skills for the inside-the-box exercise), generalizes Q3, and adds skill-vs-MCP, explicit-vs-auto, and where-should-a-project-skill-live. Answer key is heavy on B's — worth shuffling letters before publish.

Proposed quiz.mdx

# Quiz: Using Skills with Claude Code

Test your understanding of the ideas and workflows from Unit 2. Passing this quiz is part of the **Claude Code Specialization** track described in Unit 0.

The same questions are stored in `course/quiz/data/unit_2.json`.

## Questions

1. Where should a project-local skill live if you want it versioned with the repository?
   A. `~/.claude/skills/<name>/SKILL.md`
   B. `.claude/skills/<name>/SKILL.md`
   C. `skills/<name>/README.md`
   D. `.mcp/<name>/SKILL.md`

2. What is the main signal Claude uses to decide whether to auto-activate a skill?
   A. The skill directory name
   B. The longest heading inside `SKILL.md`
   C. The `description` field in frontmatter
   D. The file modification time

3. A skill's body is correct, but it never auto-activates on natural prompts. What's the most likely fix?
   A. Move it from `.claude/skills/` to `~/.claude/skills/`
   B. Rewrite the `description` to include the language a user would actually type
   C. Add more headings to `SKILL.md`
   D. Convert it to an MCP server

4. Why does an agent read skill *descriptions* before loading full skill *bodies*?
   A. Descriptions are cached and bodies are not
   B. Selecting on short descriptions is cheap; injecting full bodies costs context, so you only want the relevant ones
   C. Claude Code requires two passes for every skill
   D. Skill bodies cannot be read at runtime

5. What's the difference between a skill and an MCP server?
   A. Skills run in the browser; MCP servers run locally
   B. A skill tells Claude *how* to use tools it has; an MCP server gives Claude a *new* tool
   C. Skills are YAML; MCP servers are JSON
   D. There is no difference — they're interchangeable

6. When would you type `/skill-name` instead of relying on auto-activation?
   A. Auto-activation only works for plugin skills
   B. When you want that specific skill's workflow now, regardless of whether your prompt wording matches its description
   C. Slash invocation is required the first time you use any skill
   D. Auto-activation is deprecated

7. In the `agent/` starter, what is `select_skills(...)` responsible for?
   A. Building the Gradio UI
   B. Choosing which skill names are relevant to the current user message
   C. Writing new skill files
   D. Packaging plugin metadata

8. You're writing a style skill for one specific app. Where should it live?
   A. In the project's `.claude/skills/` — it's specific to this codebase and you'll edit it as the app changes
   B. Installed via `/plugin install` from a marketplace
   C. In `~/.claude/skills/` so every project gets it
   D. Inside `SKILL.md` in the repo root

9. What is `skill-creator` primarily for?
   A. Converting MCP servers into skills
   B. Scaffolding a new skill from scratch — directory, `SKILL.md`, and an eval loop to tune activation
   C. Publishing Spaces to the Hub
   D. Translating skills between agent runtimes

10. Why are small focused skills often better than one giant catch-all skill?
    A. Claude Code ignores large skills entirely
    B. Small skills are easier to trigger, debug, and keep behavior-specific
    C. The Agent Skills specification forbids multi-section skills
    D. Only small skills can contain scripts

<details>
<summary>Answer key</summary>

1. B
2. C
3. B
4. B
5. B
6. B
7. B
8. A
9. B
10. B

</details>

Proposed unit_2.json

[
  {
    "question": "Where should a project-local skill live if you want it versioned with the repository?",
    "answer_a": "~/.claude/skills/<name>/SKILL.md",
    "answer_b": ".claude/skills/<name>/SKILL.md",
    "answer_c": "skills/<name>/README.md",
    "answer_d": ".mcp/<name>/SKILL.md",
    "correct_answer": "B"
  },
  {
    "question": "What is the main signal Claude uses to decide whether to auto-activate a skill?",
    "answer_a": "The skill directory name",
    "answer_b": "The longest heading inside SKILL.md",
    "answer_c": "The description field in frontmatter",
    "answer_d": "The file modification time",
    "correct_answer": "C"
  },
  {
    "question": "A skill's body is correct, but it never auto-activates on natural prompts. What's the most likely fix?",
    "answer_a": "Move it from .claude/skills/ to ~/.claude/skills/",
    "answer_b": "Rewrite the description to include the language a user would actually type",
    "answer_c": "Add more headings to SKILL.md",
    "answer_d": "Convert it to an MCP server",
    "correct_answer": "B"
  },
  {
    "question": "Why does an agent read skill descriptions before loading full skill bodies?",
    "answer_a": "Descriptions are cached and bodies are not",
    "answer_b": "Selecting on short descriptions is cheap; injecting full bodies costs context, so you only want the relevant ones",
    "answer_c": "Claude Code requires two passes for every skill",
    "answer_d": "Skill bodies cannot be read at runtime",
    "correct_answer": "B"
  },
  {
    "question": "What's the difference between a skill and an MCP server?",
    "answer_a": "Skills run in the browser; MCP servers run locally",
    "answer_b": "A skill tells Claude how to use tools it has; an MCP server gives Claude a new tool",
    "answer_c": "Skills are YAML; MCP servers are JSON",
    "answer_d": "There is no difference",
    "correct_answer": "B"
  },
  {
    "question": "When would you type /skill-name instead of relying on auto-activation?",
    "answer_a": "Auto-activation only works for plugin skills",
    "answer_b": "When you want that specific skill's workflow now, regardless of whether your prompt wording matches its description",
    "answer_c": "Slash invocation is required the first time you use any skill",
    "answer_d": "Auto-activation is deprecated",
    "correct_answer": "B"
  },
  {
    "question": "In the agent/ starter, what is select_skills(...) responsible for?",
    "answer_a": "Building the Gradio UI",
    "answer_b": "Choosing which skill names are relevant to the current user message",
    "answer_c": "Writing new skill files",
    "answer_d": "Packaging plugin metadata",
    "correct_answer": "B"
  },
  {
    "question": "You're writing a style skill for one specific app. Where should it live?",
    "answer_a": "In the project's .claude/skills/ — it's specific to this codebase and you'll edit it as the app changes",
    "answer_b": "Installed via /plugin install from a marketplace",
    "answer_c": "In ~/.claude/skills/ so every project gets it",
    "answer_d": "Inside SKILL.md in the repo root",
    "correct_answer": "A"
  },
  {
    "question": "What is skill-creator primarily for?",
    "answer_a": "Converting MCP servers into skills",
    "answer_b": "Scaffolding a new skill from scratch, including directory, SKILL.md, and an eval loop to tune activation",
    "answer_c": "Publishing Spaces to the Hub",
    "answer_d": "Translating skills between agent runtimes",
    "correct_answer": "B"
  },
  {
    "question": "Why are small focused skills often better than one giant catch-all skill?",
    "answer_a": "Claude Code ignores large skills entirely",
    "answer_b": "Small skills are easier to trigger, debug, and keep behavior-specific",
    "answer_c": "The Agent Skills specification forbids multi-section skills",
    "answer_d": "Only small skills can contain scripts",
    "correct_answer": "B"
  }
]

[burtenshaw]

Took most of this. I rewrote the quiz toward transferable concepts: activation language, description-vs-body selection, skill vs MCP, explicit invocation, and where app-specific skills should live.

I kept select_skills(...) because it is the concrete anchor for the inside-the-box exercise, and I broadened the skill-creator question to “skill authoring loop” so it no longer depends on one exact unit output.

[mnielan-ant]

Ran the whole unit end-to-end as a student (fresh Claude Code, fresh starter dir) — line comments cover everything I hit. Most are small mechanical fixes (/plugin names/suffix, a missing /reload-plugins, a couple of clarity tweaks).

Two bigger proposals are in the threads on skill-creator.mdx and quiz.mdx — both have full draft replacements inline, take or leave.

One thing I couldn't verify from my side: the hf repos create … --space-sdk gradio / hf upload . . syntax in hands-on-publish-space.mdx — your CLI, just flagging for a double-check.

[burtenshaw]

Thanks. I pushed 1d4c943, which takes the mechanical fixes from the review and the parts of the bigger suggestions that improved durability without breaking the unit's arc.

What changed:

• corrected the HF marketplace suffixes to @huggingface-skills in Unit 0 / 1 / 2 and the repo README
• added /reload-plugins where students would otherwise hit stale slash-menu state
• clarified scope selection, reordered the activation page, linked the Claude Code skills reference, and made the skills-vs-MCP explanation concrete
• removed the leftover authoring note and simplified the dataset-publisher activation exercise around the already-installed personal skill
• kept both style skills mounted in the starter flow and made the brutalist pass explicit instead of destructive
• switched skill-creator to the Anthropic marketplace install flow and rewrote that page so it starts from the student's already-fixed description rather than the stale pre-fix one
• rewrote the quiz to be more concept-heavy and less tied to one exact starter implementation / CLI flag
• updated the starter skill snippets to the launch(theme=..., css=...) style

On the two bigger proposals: I took most of the quiz generalization, but I kept the skill-creator page on the dataset-publisher activation thread rather than retargeting it to a separate personal-brand build.

I also double-checked the HF CLI locally before leaving the publish page alone: current help output accepts both hf repos create ... --repo-type space --space-sdk gradio and hf upload ... . . --repo-type space, so the publish commands in the unit are valid as written.