Packaging a Claude Code workflow so someone else can install it

We packaged our Claude Code setup into a zip file a friend can install in half an hour: one script, one plan document, and the handful of files that make the difference between "I tried Claude Code once" and "this is how I build things now". The exercise turned out to be a useful audit of what in our workflow is actually transferable, and what only works because of our own machine.

What we did

A friend has just got a MacBook and wants to use Claude Code the way we do. The obvious move is to sit next to him and type for two hours. The better move is to hand over a folder he installs himself, so the setup survives the afternoon.

The kit is small: 30 files, 37 KB zipped. It contains:

• A master CLAUDE.md that loads in every project: the house rules (confirm before deleting, pushing or sending anything; simplest solution first; end every task with a files-changed report), plus the conventions those rules depend on.
• Four slash-command skills: /status to re-orient at the start of a session, /wrapup to sync docs, build, commit and gate the push, /code-simplifier for scoped refactors, and /update-email to draft a stakeholder note.
• Two cheap helper agents: a Haiku scout for read-only lookups and a Sonnet builder for well-specified implementation, so the expensive model stays on the judgement calls.
• new-project.sh, which stamps out the three documentation files every project keeps, plus a .gitignore and a git repo.
• safe-npm-install.sh, which refuses to install any npm package published in the last three days.
• A settings.json with a deny-list for force pushes, a session-start hook that prints today's date and day of the week, and a status line.
• An install.sh that copies all of that into place, backing up anything it would overwrite.
• A SETUP-PLAN.md that starts at "press Cmd + Space and type Terminal" and ends with a first project.

Why we did it

Most of the value in an AI coding workflow is not the model. It is the scaffolding around the model: the rules it reads before it acts, the rituals that keep project docs true, and the guardrails that stop a confident agent from doing something irreversible. That scaffolding accretes over months and lives in a dozen places (~/.claude/, a master rules file, a couple of shell scripts) that nobody remembers exist.

Which means the second person to use it starts from zero. They install the CLI, get a blank prompt, and have the "I tried Claude Code once" experience: impressive for ten minutes, then a tangle of undocumented projects and a session that has forgotten yesterday.

How it helps you

If you have a working setup, the useful question is: which parts would survive being copied to another machine unchanged? Sorting our own files into three piles was the real work.

Portable as-is. The behavioural rules. The doc model (an operating manual that loads every session, a plan file with one dated entry per working day, an archive). The start and end rituals. The delegation pattern. The npm age gate. None of these reference a hostname, an account, or a client.

Portable with edits. The master CLAUDE.md came in at 95 KB on our machine and 11 KB in the kit. Everything cut was either a port table, a cloud-account mapping, a brand-specific document skill, or a gotcha about a service the friend may never use. The default model setting went too: a beginner's account should use the plan's default, not our top-tier model at high effort.

Not portable. Skills wired to credentials in ~/.config, a status line that depends on a cost-tracking tool and a second runtime, and anything with a client name in it.

The exercise is worth doing even if you never send the zip to anyone. The 11 KB file is a better description of how we work than the 95 KB one, and it is loaded into context at every session start, so its size is a cost you pay every day.

Three things to lift for your own kit:

1. Make the install script non-destructive. Ours copies each file, and if the destination exists and differs it writes a .bak-<timestamp> first. That means the friend can re-run it after an update without losing local edits, and so can you.
2. Test the installer against a throwaway home directory, not your own. HOME=/tmp/fakehome bash install.sh exercised every path, and it caught one bug: the port hint in new-project.sh was reading a stale copy of the rules file, so the first project would have been told to use port 3010 with 3000 sitting empty.
3. Put the first project in the plan. The setup document is not done at "claude --version prints a number". It is done when the person has run new-project.sh, built something small, typed /wrapup, come back the next day and typed /status. That loop is the workflow; the rest is plumbing.

Technical notes

The installer is forty lines of bash. The interesting part is the copy helper:

copy() {  # copy <src> <dest>: back up dest if it exists and differs
  local src="$1" dest="$2"
  mkdir -p "$(dirname "$dest")"
  if [ -e "$dest" ] && ! cmp -s "$src" "$dest"; then
    cp "$dest" "$dest.bak-$STAMP"
  fi
  cp "$src" "$dest"
}

cmp -s is the detail that matters: an unchanged file is not backed up, so re-running the installer does not litter the machine with identical .bak files.

The status line was rewritten to drop its dependency on a cost tracker, leaving only jq:

model=$(echo "$input" | jq -r '.model.display_name')
remaining=$(echo "$input" | jq -r '.context_window.remaining_percentage // empty')

Everything else in the kit is a verbatim copy. We checked the four skills for machine-specific strings before including them (grep -i -E 'hostname|clientname|~/Sites/[a-z]'), and all four were clean, which was mildly surprising and a good sign that they were written as tools rather than as notes to self.

The takeaway: the transferable part of an AI coding workflow is the rules, the rituals and the guardrails, and it fits in 37 KB. If yours does not, the extra weight is probably history that belongs in an archive, not in the file the model reads every morning.