Workshop · 6 chapters · ~100 minutes · free, self-paced
Encode the rule once. A prompt to write it down. A hook to block the diff. A subagent to audit the rest of the repo. A skill to name the workflow. By the end you've shipped all four against a planted bug — and ported the pattern to a rule you actually repeat.
The pattern this fixes
You've corrected your agent the same way three times this week. The barrel import that breaks tree-shaking. The test file that uses `any`. The migration that ships without a backfill. The rule lives in your head — until you encode it. A prompt writes it down. A hook blocks it at the lifecycle. A subagent audits the rest of the repo. A skill gives the workflow a name you can call.
What you'll build
Each lab ends with a working snippet you can paste into your own repo. These are the four you'll ship.
01 · Prompt
A definitive instruction document in `.claude/prompts/` — what counts as a violation, what doesn't, and the suggested fix. The source of truth the next three layers reference.
# .claude/prompts/no-barrel-imports.md
## Rule
A barrel import is any import whose specifier
ends in /index or resolves to a re-exporting
directory. Rewrite to the leaf path. Do not
rename symbols.02 · Hook
A PreToolUse hook fires on every Write/Edit and blocks the diff before the agent finishes the turn.
# .claude/hooks/no-barrel-imports.sh
grep -nE "from ['\"]\..*/index['\"]" "$CLAUDE_FILE_PATH" \
&& { echo "Barrel import. Import the leaf instead." >&2; exit 2; }03 · Subagent
An audit subagent sweeps the rest of the repo for siblings of the bug the hook just caught, and reports them grouped by file.
# .claude/agents/barrel-auditor.md
---
name: barrel-auditor
description: Sweep for barrel-import siblings.
tools: [Grep, Read]
---
Find every `from '.../index'` outside tests.
Group by file. Suggest the leaf path.04 · Skill
/fix-barrels invokes the auditor, applies the codemod, and re-runs the hook to verify. One name, the whole workflow.
# .claude/skills/fix-barrels.md
---
name: fix-barrels
description: Audit barrels, rewrite to leaves, verify.
---
1. Run barrel-auditor.
2. For each finding, rewrite the import.
3. Trigger the hook to confirm green.Syllabus
Each chapter is a written lab with a working snippet at the end. Your progress is stored in this browser — resume any time.
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.
Twelve minutes. One markdown file. A definitive instruction document that says — once, in writing — what counts as a barrel import and what the agent should do about it. The source of truth the next three labs all reference.
Fifteen minutes. One shell script. Exit code 2. By the end of this lab, Claude Code physically cannot write a barrel import into the starter repo.
Twenty minutes. One markdown file. A read-only subagent that scans for remaining barrel imports and returns a pinned table with concrete fix suggestions — the judgement call the hook can't make.
Fifteen minutes. One slash command. /de-barrel calls the auditor, walks each row, and lets the hook guard every edit. The team-facing surface that makes the workflow invocable in eight keystrokes.
Ten minutes. No code. Pick one rule you've left in PR comments three times this month and design its hook, its subagent, and its skill. A worksheet, an example, and the heuristic for when each layer earns its keep.
Audience check
Yes if
Probably not if
Before you start
Questions
Yes. Every chapter is a public blog post. No login, no email gate, no upsell at the end.
A free Claude account is enough to run the hook and skill. The auditor subagent benefits from a higher quota — labs note where you can stub responses if you hit a limit.
After lab 1, yes. The starter exists so the planted bug is identical for everyone; once you've shipped one hook, point it at your own codebase.
~100 minutes cold. ~75 if you've already read the agent-ready trilogy. The capstone is a 10-minute worksheet — don't skip it.
Each lab ends with a 'reset and re-run' block — drop the changes, copy the working snippet, then read the diff. Stuck for real? Ping me; the link is in the site footer.
Concept reading
The trilogy that explains each layer in depth — read whichever you want to ground first. They live on the blog; the workshop turns them into reps.
Task-specific agent prompts that work
The structure of a definitive instruction document — purpose, references, rules, checklist.
Read the essay →
The Claude hooks lifecycle
Why hooks fire when they do, and which events you can intercept.
Read the essay →
From audit to hook enforcement
Promoting a repeated correction into a deterministic guardrail.
Read the essay →
Subagents that catch what hooks can't
Where subagents fit between hooks and skills, and what they're best at.
Read the essay →
Skills: the user-facing workflow layer
Skills give a workflow a name you can call from the prompt.
Read the essay →
Your turn
~90 minutes from clone to capstone. Bring a terminal and the rule you keep repeating.