Lab 4 — Skill

Workshop chapter 5 of 6. Setup → Lab 1 → Lab 2 → Lab 3 → Lab 4 (you are here) → Capstone.

Recap in 30 seconds. A skill is a markdown file in .claude/commands/ that becomes a slash command. Users type /de-barrel and a multi-step prompt fires — loading docs, calling subagents, walking edits, running checks. The hook and subagent are infrastructure; the skill is the handle a teammate grabs without thinking. Deep dive: Skills: The User-Facing Workflow Layer.

Goal. Wire /de-barrel: invoke the auditor, iterate its rows, perform each edit while the hook guards correctness, end with a green typecheck.

Step 1 — Write the skill

Create .claude/commands/de-barrel.md:

---
name: de-barrel
description: Sweep barrel imports from this codebase, one symbol at a time.
---
 
# /de-barrel
 
Migrate the codebase off barrel imports of `@/components`, `@/lib`, and
`@/hooks`. Use the auditor for finding; use direct edits for fixing; trust
the hook to guard each edit.
 
## Procedure
 
1. **Audit.** Invoke `@barrel-import-auditor` against the whole repo. It
   returns a markdown table with one row per offending symbol.
 
2. **Plan.** If the table is empty, say "No barrel imports — already clean."
   and stop. Otherwise, list the affected file paths in a brief preamble so
   the user can ctrl-C if the surface is larger than they expected.
 
3. **Edit, row by row.** For each row in the auditor's table:
   - Open the file at the indicated line.
   - Replace the barrel import with the suggested rewrite.
   - Save. The `no-barrel-imports` hook will reject any edit that still
     contains a barrel pattern — **do not bypass it**. If the hook fires,
     re-read the edit and fix the actual problem (likely you missed a
     symbol). Never edit the hook to make this skill pass.
 
4. **Verify.** When the table is exhausted, run:
 
       pnpm typecheck
 
   If typecheck fails, the most common cause is a misspelled direct path.
   Read the error, fix, re-run. Do not declare success until typecheck is
   green.
 
5. **Report.** End with a one-line summary:
 
       Removed N barrel imports across M files. Typecheck: green.
 
## Constraints
 
- Do **not** edit `@barrel-import-auditor` to silence its findings.
- Do **not** add new barrel re-exports anywhere. The `index.ts` files
  inside component directories should not grow.
- Do **not** delete the existing `src/components/index.ts` in this pass —
  removal is a separate, manual step after every caller is migrated.
- One symbol per row. An import statement that pulls in three symbols
  expands to three lines after the rewrite. Let `prettier` collapse them
  on save if it wants to; the hook only cares about the *barrel pattern*,
  not the line count.

Save the file. That’s the whole skill.

Step 2 — Run it

In Claude Code:

/de-barrel

The slash command fires. The agent:

1. Calls @barrel-import-auditor. Table comes back.
2. Lists the affected files: src/App.tsx, src/legacy/OrdersList.tsx, src/legacy/Toolbar.tsx.
3. Opens src/App.tsx. Tries to write the new file. Tries — at first — import { Button, Card } from "@/components/Button"; (a real mistake the model sometimes makes). The hook fires: barrel pattern still present in the Button, Card shape against a single path. The agent reads the rejection, splits the import in two, retries. Edit lands.
4. Repeats for OrdersList.tsx and Toolbar.tsx.
5. Runs pnpm typecheck. Green.
6. Reports: “Removed 4 barrel imports across 3 files. Typecheck: green.”

You typed eight keystrokes (/de-barrel). Three layers cooperated to do the work.

Why this works

Each layer has one job — and refuses to do the others’:

• The skill drives. It knows the procedure, the order, the validation.
• The subagent finds. It does not edit, does not opine on order.
• The hook guards. It does not know what /de-barrel is; it just refuses bad patterns at every write.

Take any layer away and the workflow collapses:

• Drop the hook → the agent can make any of a dozen subtle mistakes and they all silently land.
• Drop the subagent → the skill has to do the finding itself, in the same context as the editing, and the prompt balloons.
• Drop the skill → a teammate has to remember the procedure, the validation, the order. They won’t.

That separation of concerns is what makes the stack teach itself. A new teammate doesn’t need to read settings.json or .claude/agents/; they read /help, see /de-barrel, run it, and the hook + subagent silently do their jobs.

What this skill can and cannot do

Can: orchestrate a known workflow without the user remembering its parts. Surface itself in /help. Be invoked by another skill (skills compose).

Cannot: decide whether to start the workflow. That’s still a human judgement — “is now a good time to de-barrel?” A skill is a verb the user wields; it isn’t autonomous.

What’s next

You have the full stack now. Hook, subagent, skill — all three running against one rule, in one repo. The Capstone is a 10-minute worksheet: pick a rule you keep repeating in PR review, and design its hook/subagent/skill triple. No code. Just the design.