Chapter 01 · 3 min

Lab setup: clone and plant the bug

Five minutes to a working starter repo with one planted barrel-import bug. From this point onward, the labs build the hook, subagent, and skill that catch it.

Workshop chapter 1 of 6. Four labs (prompt → hook → subagent → skill) plus a capstone. Total time: ~80 minutes. Each chapter assumes you’ve finished the one before. The agent-ready trilogy is recommended pre-reading but not required — every lab opens with a short recap.

The workshop runs against a tiny throwaway repo with one planted bug. You’ll build, in order:

  1. A prompt that defines the rule in writing — the source of truth.
  2. A hook that refuses to let the bug be written.
  3. A subagent that audits the codebase for the bug’s siblings.
  4. A skill that wires the prompt, hook, and subagent into a single slash command.

The bug is a barrel import. It’s the right shape: deterministic enough for a hook to catch, but pervasive enough that a subagent earns its keep, and the rewrite is mechanical enough that a skill can drive it.

What you need

  • Node 20+ and pnpm on your PATH.
  • Claude Code installed and authenticated.
  • A terminal you don’t mind switching directories in. No IDE-specific setup.

Clone the starter

git clone https://github.com/poudelprakash/hooks-subagents-skills-workshop.git
cd hooks-subagents-skills-workshop
pnpm install
pnpm dev

You should see a Vite dev server at http://localhost:5173/ rendering a two-component page — a button and a card. That’s the whole app. The point isn’t the app; it’s the import in src/App.tsx.

The planted bug

Open src/App.tsx:

import { Button, Card } from "@/components";

That’s the barrel. @/components/index.ts re-exports Button and Card, and App.tsx consumes them through the barrel. In a real codebase, barrels balloon bundle size, break tree-shaking, and obscure the dependency graph at review time. The team’s rule is no barrels — but CLAUDE.md saying so isn’t enough.

For the rest of the workshop, this single line is the rule we’ll enforce three different ways.

Verify Claude Code sees the project

The starter repo ships with empty .claude/ directories:

.claude/
├── agents/       (empty — Lab 2 fills this)
├── commands/     (empty — Lab 3 fills this)
├── hooks/        (empty — Lab 1 fills this)
└── settings.json (minimal — Labs 1 and 3 extend it)

Launch Claude Code in the repo:

cd hooks-subagents-skills-workshop
claude

Then ask it: “What’s in src/App.tsx?” It should read the file and quote the barrel import back. If it can, you’re set.

A note on the solution branch

The repo has a solution branch with the finished hook, subagent, and skill. If you get stuck or want to peek ahead:

git switch solution -- .claude/
git switch -   # restore your working state

Don’t peek before each lab — the friction of writing each layer yourself is most of the learning.

What’s next

Lab 1 — Hook walks you through writing a PreToolUse shell hook that rejects the barrel import the moment Claude Code tries to write it. Fifteen minutes. Exit code 2.

—
0:00 0:00