One Stow command links every skill on Linux

Why Care?

A skill that isn't linked doesn't exist. Claude Code, pi, and most other Agent-Skills-compatible tools look exactly one level deep, at <skills-dir>/<name>/SKILL.md. Link the whole repo as one folder and every skill inside it is invisible. Each skill needs its own link, and we've already lost days to skills that were written, committed, and silently never loaded.

On macOS we solved that with sync-skills-symlinks.sh. Then a Linux machine joined the tree, and Linux already ships a well-worn tool for exactly this job: GNU Stow, the symlink farm manager people have used for dotfiles for decades. So on Linux, we use it.

What's New?

On Linux, linking every skill in this repo is now one command, run from the monorepo root:

stow    -d context-v -t ~/.claude/skills agent-skills   # link every skill
stow -R -d context-v -t ~/.claude/skills agent-skills   # restow after adding a skill
stow -D -d context-v -t ~/.claude/skills agent-skills   # unlink every skill

• A new .stow-local-ignore at the repo root tells Stow which top-level entries are not skills, so only skill directories get linked.

• Unlinking is as clean as linking. stow -D removes exactly the links Stow made and nothing else. The script never had an undo.

• Any harness works. Point -t at a different skills directory (for example ~/.agents/skills) and the same ignore file applies.

The first run linked all 28 skills. A dry run beforehand showed exactly those 28 and nothing else, with no broken links afterwards.

How it works

Stow treats agent-skills/ as a package and mirrors its top-level entries into the target as symlinks. Because the target doesn't already contain those directories, Stow folds them, linking each skill directory whole rather than recreating it file by file:

~/.claude/skills/
├── git-conventions  -> ../../code/lossless-monorepo/context-v/agent-skills/git-conventions
├── theme-system     -> ../../code/lossless-monorepo/context-v/agent-skills/theme-system
├── …                   (26 more)
├── omarchy          -> /usr/share/omarchy/…   ← not ours; Stow leaves it alone
└── diagnose-crash   -> /usr/share/omarchy/…

Links Stow didn't create, like the two system skills above, are never touched. Stow only manages links that point back into its own package.

The catch is that Stow links everything at the top level: README.md, the sync scripts, changelog/, the splash/ site, .github/. That's what the ignore file is for:

# Top-level files and dot-entries (README.md, CLAUDE.md, *.sh, .git, .github, .claude, ...)
^/[^/]*\.[^/]*$
^/LICENSE$

# Top-level dirs that are not skills
^/changelog$
^/splash$

# Vendored submodules — their SKILL.md sits one level deeper; link those by hand
^/archify$
^/chroma-agent-skills$

The first pattern does most of the work. Skill names follow the Agent Skills spec (lowercase and hyphens, never a dot), so "any top-level name containing a dot" cleanly catches every file and dot-directory without touching a single skill. Patterns that begin with / match paths from the package root, so a skill with its own nested changelog/ is unaffected.

Gotchas worth knowing

The ignore file replaces Stow's defaults; it doesn't extend them. Out of the box Stow skips .git, README*, LICENSE* and friends. The moment a .stow-local-ignore exists, that built-in list is gone. So any new non-skill directory added at the top of this repo must be added to the ignore file too, or it will show up in ~/.claude/skills on the next restow.

Don't mix Stow and the sync script on one machine. Stow writes relative links. sync-skills-symlinks.sh compares link targets as absolute paths, sees a mismatch, and "repoints" every skill to an absolute link. Stow then no longer recognizes those links as its own and reports them as conflicts. Pick one tool per machine: Stow on Linux, the script on macOS.

Vendored skills still need a hand-made link. archify and chroma-agent-skills are upstream submodules whose SKILL.md sits one level deeper (archify/archify/SKILL.md, chroma-agent-skills/skills/chroma-local/). Stow can't reach them without linking the whole submodule, so they're ignored and linked by hand, exactly as before.

Renames still leave a stale link. Stow unstows by walking the package as it is now, so a link for a skill's old directory name isn't in that walk. Check after any rename:

find ~/.claude/skills -maxdepth 1 -xtype l

New links load next session. Same as with the script: a skill linked mid-session appears in the next one.

What's Next?

• This repo's own CLAUDE.md and README.md still describe only sync-skills-symlinks.sh. They should document Stow as the Linux path.

• The anchor monorepo's root AGENTS.md (with CLAUDE.md now a symlink to it) already documents the Stow commands and the don't-mix rule.