Skill v1.0.1
Automated scan100/100+1 new
name: distributing-blocks description: "Use when someone outside this repo wants to install these blocks, or an existing user needs a newer version: the install and update mechanism, and the boundary that keeps their customisations alive." metadata: version: "1.0.1"
distributing-blocks
Cross-cutting (WORKFLOW.md §2). Rule B says nobody upstream may break our workflow. The moment this framework is installed by other people, we are that upstream for them. This block is how we hold our own rule from the other side.
The mechanism is deliberately boring: git. Not a package manager, not an auto-updater.
When
When a new team installs the blocks, when an existing user needs a newer version, or when deciding whether something we wrote should be shared at all.
Steps
1. Decide what is even shareable
Before distribution, per block:
- Share when it's generic, useful beyond one team, and its
Originis honest. - Keep private when it is: specific to one project or one organisation's internals, calibrated on
a named person's habits, experimental, or carrying anything sensitive.
That last case is not hypothetical: blocks have already been kept out of this repo for it. A block built around one colleague's review behaviour is useful locally and indefensible shared. When the mechanism is worth keeping, extract it generically and leave the calibration at home — that's how the triage step in review survived while the agent implementing it stayed private.
2. Install: a clone they own
- The consumer clones the repo (or forks it). They own that working copy: it's a git repo, with
their name on the commits.
- Blocks are copied into the target repo's
.claude/skills/and.claude/agents/, or symlinked from
the clone. Nothing is fetched at runtime — rule B applies to them too.
- Executable pieces (
hooks/) are wired per repo, deliberately, by a human reading what they do.
Install target for other clients: `.agents/skills/`. The open Agent Skills client guide names <project>/.agents/skills/ and ~/.agents/skills/ as a widely used cross-client convention, next to each client's own directory; the specification itself does not mandate any location, and the guide notes that some clients also read .claude/skills/. Installing the same blocks into .agents/skills/ is therefore a valid target for a client other than the one the rest of this block assumes (🟡: read in the guide, never tried against a second client). A client scanning those directories looks for subdirectories holding a file named SKILL.md and, per the guide, bounds the walk (for example a depth of 4 to 6 levels). Flagged risk, not a verified fact: a scanner that only looks one level down finds a block symlinked as skills/<name>/ directly under the target, but not the repo's whole-clone symlink that puts SKILL.md three levels deep, and the business/ layer is a second root; link block by block into the target if a client misses them. The same guide advises gating project-level skills on a folder-trust check, which is the consumer's setting to keep on.
Agents specifically: `bin/install_agents.py`. Skills can be symlinked from the clone and stay current for free. Agents usually cannot, because a local install wants the real names back where the repo says "the operator", <scratch> and "an org skill catalogue" (rule C). The script does that localisation from a {"from": "to"} JSON map kept outside the repo, since that map names real people, hosts and paths. It is --dry-run by default and prints, before writing anything: what is new, what would change, what is left alone, and any substitution that did not apply. --apply backs up every file it overwrites into <target>/.backup/ first.
The rule the script enforces mechanically: an agent that exists only in the target is never touched. Locally-calibrated agents — the ones rule C keeps out of the repo — survive an install by construction, they are not something the operator has to remember to protect.
The third shape, since 2026-09-07: one plugin instead of N symlinks. The repo root carries a .claude-plugin/plugin.json declaring skills (./skills, ./business) and agents (./agents), so a clone symlinked to ~/.claude/skills/mentis registers as a single mentis@skills-dir plugin on the next session rather than as eighty-odd loose directories. What that buys is not tidiness: it is one enable/disable switch, a claude plugin details reading of the projected token cost, and a target claude plugin eval can resolve with its no-plugin baseline arm. It does not replace the per-block symlinks — a consumer wanting four blocks should still take four — and the two forms must never be installed at once, because every block would then be loaded twice.
The manifest declares skills and deliberately not agents. An agent here is not installable by copy: bin/install_agents.py --localise substitutes the placeholders an agent carries for the consumer's own paths, names and catalogue, which is why the script exists at all. A plugin-shipped agent would arrive with the placeholders intact and read as a finished file, and on the machine that already ran the script it would arrive twice — once namespaced by the plugin, once localised — so the fleet's index doubles and two versions of the same agent answer to nearly the same name. Agents keep the script as their only path; the plugin form carries the blocks.
And declaring that takes `"agents": []`, not an omitted key — measured, not assumed. With the key absent, claude plugin details still reported Agents (25): the loader picks ./agents up by directory convention, so the first attempt at this rule was a claim with nothing behind it, which is code-baseline §8 exactly. The empty array reports Agents (0). Anything a manifest is supposed to not ship has to be denied explicitly and then read back from claude plugin details, because the default is discovery.
A note on symlinking skills: a block whose Steps became a router needs its references/ directory symlinked too, not just its SKILL.md. A router pointing at sections that aren't there is worse than a long block.
3. Update: they pull, we don't push
- Stash or commit local work first. An update that starts on a dirty tree is how someone loses an
afternoon.
- Fetch, then merge. Fast-forward if their copy hasn't diverged, an ordinary merge if it has.
- Conflicts are shown to the human, with both sides explained, and resolved by them. Never
resolved silently in favour of upstream: a conflict means the two of us changed the same rule, and ours isn't automatically right for their repo.
- Restore the stashed work, then confirm the block list still loads.
Their customisations are commits, so they survive the merge by construction. This is the whole reason for using git rather than a copy-over installer: we don't need a folder convention separating "our blocks" from "their overrides", because version control already models it.
4. Version, so pinning is possible
- Tag releases and keep a changelog of what changed per block, so a consumer can read before merging
rather than after.
- A consumer must be able to stay on an older version deliberately. "Everyone is always on
latest" is the property that lets an upstream break people.
Output / checkpoint
For a new consumer: a clone they own, blocks installed, hooks wired knowingly. For an update: the merge done, conflicts resolved by a human, local work restored, block list verified.
Guardrails
- Never a silent auto-update. An update that rewrites someone's agents without them reading it is
exactly what rule B forbids others from doing to us. Pull, not push.
- Never resolve a conflict for them. Surface both versions; the decision is theirs.
- Don't share a block that has never been tested. Distributing something never run once spends
the credibility of the first colleagues who try it, and that's the hardest credit to win back. Use testing-blocks at minimum; real use is better.
- The decision to publish more widely (outside the company, under a licence) is a human decision,
out of scope for any agent.
Origin
Rewrite of pulling-updates-from-skills-repository and sharing-skills from a market skills repository (the companion repo of the upstream this framework responds to). The git-based pull-and-merge flow, the stash-first ordering and the share-vs-keep-private criteria come from there.
What's ours: framing the whole thing as rule B applied in the reverse direction, the requirement that pinning an older version be possible, and the observation that git already provides the ours-vs-theirs boundary, which had been flagged in the README roadmap as an unsolved design problem needing a folder convention. It didn't.