Last time I wrote about the portable half of a Claude Code setup — the process discipline
that transfers to any codebase, packaged as a plugin. Explore before building, prove the
helper doesn't already exist, never claim "done" without pasting the output.
That half is genuinely reusable. It's also not where most of the damage happens.
Watch a capable agent work on an unfamiliar project and the failures aren't reasoning
failures. It opens the PR against main when the project ships from a different branch. It
writes a PR body missing the three headings your CI requires, and the check fails for reasons
the error message doesn't explain. It puts the migration in the plausible-looking directory
rather than the real one. It calls the API endpoint that was deprecated in March, because the
old one is still in the tree.
None of that is a thinking problem. It's that the information doesn't exist in any form the
agent can find. Your conventions live in your team's heads, in a wiki nobody's opened since
onboarding, and in the reflex of the one person who's been there three years.
The information isn't in the codebase
This is the part I got wrong for a while. I assumed that a sufficiently good agent reading a
sufficiently well-organised repo would infer the conventions. Sometimes it does. But
inference from code gives you what the code does, not what the team has agreed, and those
differ constantly:
- Both
mainand a development branch exist and look active. Which one do PRs target? The code cannot tell you. Both have recent commits. - Two service-layer patterns exist because one is being migrated to the other. Which is correct for new work? The tree shows both, in roughly equal numbers.
- A directory holds twelve files, eleven of which are deprecated. Nothing marks them.
An agent reading that repo will make a defensible choice and be wrong half the time. So will
a new human contributor — they just ask in Slack instead, which is why the problem stays
invisible until you try to scale it.
Why this doesn't go in CLAUDE.md either
Same argument as last time, sharper. Project instructions are resident in context permanently,
so everything you add competes with the actual task for attention.
Conventions are unusually bad at justifying that cost, because almost all of them are
situational. The rules about PR body structure matter during PR creation and nowhere else.
The deploy path matters when deploying. The full-stack debugging map — which layer owns
which symptom — is critical when something breaks and pure noise the rest of the time.
Push all of it into one always-on file and you get a document nobody can keep current, where
the two rules that would have prevented today's incident are buried among forty that wouldn't.
Skills load on trigger. That's the whole argument, and it applies harder to project
conventions than to general discipline, because there are far more of them.
The boundary that turned out to matter
I ended up splitting my skills into two marketplaces, and the dividing line is simpler than I
expected:
If a skill names a branch, a path, a service, or a table — it's project-specific.
If it names a discipline — it's portable.
canonical-coding ("one implementation per concept, prove the thing doesn't exist before you
write it") names a discipline. It's true everywhere. pr ("target this branch, these headings
are required, run these checks first") names a branch. It's true in exactly one repo and
actively harmful anywhere else.
The test is useful because it's mechanical. You don't have to reason about whether something
feels general — you look at whether it can be written without naming a proper noun from your
infrastructure.
What the project-specific half looks like
For AutoBot-AI that came to twelve skills, in
their own marketplace:
Issue → merge — implement (the full loop: umbrella gate, worktree, design, code, verify,
PR, CI, closure check), batch-implement (the same across a list of issues, with per-issue
verification), pr (pre-flight branch checks, correct base branch), pre-merge-validate
(syntax, imports, call-site impact, tests, types, lint), drain (pick up the backlog items
that need no human decision).
Review — review (CI diagnosis, three-angle finder pass, merge decision) and
review-fleet (ten parallel review angles with separate verifier agents, posting only
confirmed, deduplicated findings as a single comment).
Audit — api-wiring-audit (frontend calls an endpoint that exists, backend route is
actually mounted) and dead-code-audit (unregistered routers, uninvoked hooks, orphaned
components).
Debug — debug-autobot, which dispatches an investigator per layer (Vue, FastAPI, Redis,
ChromaDB, NPU, browser, AI stack) and synthesises one root cause. This one is the clearest
example of why the split exists: its entire value is knowing which layers exist and what each
one owns. There is no general version of that.
Platform and session — github-cli and session-lifecycle, the start-of-session and
end-of-session protocol.
None of that is useful to you. That's the point — it's not meant to be, and trying to make it
general would strip out exactly what makes it work.
The payoff is onboarding, human and otherwise
One install, and every developer on the project has the same workflow — and so does every
fresh agent session. That second part is easy to undervalue. Agent sessions start from nothing
every time; whatever conventions you established yesterday are gone unless something reloads
them. A plugin is how you make "how we do things here" survive a new context window.
It also makes conventions reviewable. When the rule lives in a skill file in a repo, changing
it is a pull request someone can argue with — rather than a habit that drifts silently until
two people are doing it differently and neither knows.
Where this fails
Skills encoding conventions are only worth it if the conventions are stable. If your branch
strategy is genuinely in flux, a skill that confidently states the wrong base branch is worse
than nothing — a human hesitates and asks, an agent complies immediately and at scale.
So they need the same maintenance as any other checked-in artefact: when the convention
changes, the skill changes in the same PR. A skill that lies is more expensive than a
convention nobody wrote down.
The portable half is at
Claude-Dev-Skills, the project-specific half
at AutoBot-AI-Claude-dev-skills.
Both Apache-2.0.
I'd like to know whether the boundary rule holds up against your setup — is there a skill in
your workflow that names a proper noun but still feels like it should be portable? That's the
case I haven't figured out yet.
Top comments (2)
"Inference from code gives you what the code does, not what the team has agreed" is the sharpest one-line case for project skills we have read, and the proper-noun test is mechanical enough to become a lint rule.
Two things from running a skill directory. First, the split has a third bucket: skills that name a discipline but carry a project number. "Review PRs from three angles" is portable; "reject any PR over 400 lines" is a discipline with a local threshold baked in. Those get copied across repos, and then the agent argues with people. We would move the number into the project marketplace and keep the discipline portable.
Second, trigger-loading is not free at the listing level. The skills docs say every skill name plus description sits in context inside a budget of about 1% of the context window, and on overflow Claude Code drops descriptions starting with the least-invoked skills. Twelve project skills with long descriptions can silently strip the keywords off a portable skill you rarely call. Have you measured the listing after installing both marketplaces?
Those skills are my daily drivers for AutoBot project, measurement - without them hardcodes and forks start sneaking in to your codebase.