CriticalOptimisation/scm-skill

The software configuration management process used by CalCool Studios' Claude Code sessions, packaged as a Claude Code skill. SKILL.md at the root is the entry point; references/ holds the task-by-task workflow; tools/worktree.sh implements the one-worktree-per-branch convention the skill relies on. The skill refers to its own files through its own directory, so it works wherever a project links it; tools/skill-copy.sh installs it.
Using it in a project
A project uses its own **fixed copy** of the skill: a detached worktree of the skill's repository at one commit, .worktrees/skill- - , which is never edited and never checked out again. stands for the project: the first 8 hex digits of the SHA-1 of its absolute path. A copy is never shared: two projects on the same commit get two copies, because a skill may be set up with files of the project that uses it (see *The skill-copy hook*). Each copy has a USER_PROJECT file, a plain file (not a link) holding the absolute path of its project, which skill-copy.sh reads to find the project back and check that it is still there. USER_PROJECT is excluded in the skill repository's .git/info/exclude, unless git already ignores it, so that the copy of any commit stays clean. The project only gets links to it, and only the links move. A checkout, a pull or a branch switch in the skill's repository therefore never changes the skill under a running session, and a session that has loaded a copy keeps it when the links move (it resolves once; see *Paths* in SKILL.md).
tools/skill-copy.sh makes the copies and the links. Run it from the **main worktree of the project**:
**Bootstrap.** A project that has no scm-skill yet runs the tool from a clone of scm-skill, made next to the project:
may also be a URL: when the repository is missing locally, use clones it next to the project, as ../ , or where --clone-to says.
use [options], run again, updates the installation; with the same ref, it changes nothing. It:
1. fetches origin in the skill repository (a failed fetch only warns), and creates the project's copy /.worktrees/skill- - of , with its USER_PROJECT, if it is missing;
2. sources the skill's hook, if the copy has one (see *The skill-copy hook*);
3. moves the links, all relative: / to the copy, where is the name: field of the copy's SKILL.md (scm-skill here, whatever the repository is called), and one link per agent, / , to each agents/ of the copy. A link of this skill under an old name, or to an agent the copy no longer has, is removed. The project's own files and agents, and the links of other skills, are never touched;
4. excludes each link in the project's .git/info/exclude, unless git already ignores it, so that the project repository never carries a path specific to one machine;
5. logs skill- - in /.worktrees/skill-copies.log;
6. prunes the copies that nothing uses any more.
Agents and skills are loaded when a session starts: after use, start a new session. The conductor's own update at session start is the exception (see *Updating* below).
**Updating.** skill-copy.sh update , run from the main worktree of the project, brings the project's copy up to origin/main of the skill's repository. is the copy the project uses, the resolved target of its skill link (readlink -f .claude/skills/scm-skill); the conductor runs it at the start of every session (see *Conductor and Engineer* in SKILL.md). It finds everything from the copy: the skill repository is the copy's own repository, the project is the copy's USER_PROJECT, the link directories are those recorded in /.worktrees/ .links, and --frozen is repeated when the copy was made with it (use --frozen writes a marker /.worktrees/ .frozen, which use without --frozen removes). It fetches origin, then compares the copy's commit with origin/main, and prints one line on stdout: