I Refactored My AI's Toolbox

I was building a 404 page for this blog and wanted a small illustration. So I asked Claude for an image prompt. It gave me one, and it was generic. It looked nothing like the covers on this blog, the ones with the palette and framing that make them feel like mine.

I knew why. That recipe lived inside exactly one of my commands: the one I run to interview myself into a new post. Outside of writing a post, the knowledge may as well not have existed. My AI had the skill. It was locked in a room it only enters on Sundays.

That is when it clicked. My AI's toolbox is a codebase, and I had never refactored it.

What's actually in the toolbox

If you use Claude Code (or any serious agent) for real, you accumulate three things without noticing:

• A CLAUDE.md with your project's rules and gotchas.
• A pile of slash commands, one Markdown file each, under .claude/commands/.
• The prompts and instructions living inside those files.

That is your toolbox. Mine had grown to a dozen commands over a few months, and I had treated every one as write-once. That is also how every codebase rots. You add one more file, copy one more block, and never go back to tidy up.

The smell

My image style guide was hardcoded inside interview.md. The full house style: aspect ratio, palette, the rules. And two other places needed it.

One was asking for a quick illustration with no post involved. The other was new-post.md, my faster publishing path where I start from a topic and skip the interview entirely. Both needed that style guide. Neither could see it. One piece of knowledge, trapped in the wrong file, silently unavailable everywhere else.

🗒️ The sticky note on one monitor

This is tribal knowledge: the deploy steps scrawled on a sticky note on one engineer's screen. Fine until that person is on vacation and prod is down and nobody can find the note. Knowledge that lives in exactly one place is not knowledge. It is a single point of failure.

The refactor, step by step

I did the same thing I would do to any service carrying duplicated logic.

1. Find the trapped knowledge. Anything one command knows that another command needs, or that you have pasted more than once.

2. Pull it into a single source of truth. I made a new file, .claude/shared/image-prompt.md, and moved the whole style guide there. One file now owns it.

3. Replace the copies with a pointer. Inside interview.md, the embedded block became one line:

Compose the scene, then format it using the Cover preset in
.claude/shared/image-prompt.md.

new-post.md got the same pointer. Now they cannot drift, because there is only one copy to change.

4. Give it a front door. Since I wanted this on demand, I added a thin command, /illustration, that also just reads the shared file. The layout ended up clean:

.claude/
  shared/
    image-prompt.md      single source of truth
  commands/
    interview.md         points at shared/image-prompt.md
    new-post.md          points at shared/image-prompt.md
    illustration.md      points at shared/image-prompt.md

How to tell yours needs it

Three smells, all of them familiar:

• You have explained the same convention to your AI more than once. It belongs in CLAUDE.md or a shared file.
• A capability only works inside one command. Pull it out so the rest can reach it.
• You find yourself saying "go check that other command for how to do this." That is duplication asking to be extracted.

When a tool outgrows the repo

Sometimes the refactor does not stop at a shared file. Sometimes a tool is good enough that it should leave the project entirely.

That happened with a command I call /handoff. It saves a portable snapshot of a conversation, so I can stop mid-task, close the laptop, and pick the thread back up the next morning without re-explaining anything. It started as a local command in this repo. Then I wanted it in every project, not just this one.

That is the same signal as extracting a shared library: when something is useful well beyond the place it was born, you pull it out and give it its own home. So I moved /handoff and its companion /pickup out into a small public plugin, session-continuity.

It is public. If you want it:

/plugin marketplace add cwakim/claude-plugins
/plugin install session-continuity@cwakim-plugins

The source lives at github.com/cwakim/claude-plugins. That is the whole graduation path: a prompt becomes a command, and a command that proves useful everywhere becomes a plugin. I will be adding more skills to that marketplace as the rest of my toolbox earns its way out of this repo.

It happened again while I was writing this. I had a /cleanup command that deleted merged branches, but it was hardcoded to this repo. It knew only my development branch and my handful of protected ones. To let it leave, I had to generalize it: detect the base branch, take it as an argument, drop the baked-in names. Only then did it become branch-cleanup, a second plugin in that same marketplace. That is the tax of graduation. A tool earns its way out by giving up the shortcuts it took when it only had to work in one place.

Your prompts are infrastructure now

We still treat the text we feed these tools as disposable. A prompt here, a command there, a config we never reread. But if you lean on it daily, it is load-bearing. It duplicates, drifts, and rots on the same timeline as code, because it is code now. It just does not compile, so nothing yells when it goes stale.

The discipline that keeps a codebase alive keeps your AI sharp: single source of truth, do not repeat yourself, refactor the moment it hurts. And when a piece earns it, let it graduate out into the open.