Stop Copying Skills: Private Repo + Symlinks Enable One-Command Machine Migration

Copying skill directories across projects created divergent copies, making bug fixes hard to track and machine migrations painful.

1. Use symlinks instead of copying

When installing a skill, choose between copying the files or creating a symbolic link (symlink). A symlink works like a Windows shortcut: the actual files exist in one place, and every link points to that single source. Changing the source updates all linked locations automatically.

Initially copying skills resulted in three projects each holding its own copy; fixing a bug in one project left the others outdated. Switching to symlinks eliminated the problem:

✅ Only one physical copy; a single edit propagates everywhere.

✅ No risk of divergent copies.

✅ Links can be added or removed without affecting the source.

All subsequent steps assume the rule: only symlink, never copy .

2. Store all custom skills in a private repository

Personal development skills—API scaffolding, database migration scripts, code‑review helpers, commit‑message generators, bug‑fix flows—are gathered into a single private Git repository:

~/code/claude-skills/
├── api-scaffold        # generate full CRUD API scaffolding
├── db-migration        # generate DB migration scripts
├── code-review         # pre‑commit code checks
├── commit-helper       # generate conventional commit messages
└── bug-fix-flow        # end‑to‑end bug‑fix workflow

Each subdirectory contains a SKILL.md documenting its purpose. Benefits:

✅ README serves as an index, making each skill’s role obvious.

✅ Script‑based skills lock their dependencies with a lockfile, ensuring identical versions when the repository is cloned on a new machine.

✅ Every change is tracked in Git history, allowing easy rollback.

3. One‑command machine restoration

Because the repository holds the single source of truth, restoring a new workstation is as simple as cloning the repo and running a short loop that creates symlinks in Claude Code’s ~/.claude/skills/ directory:

git clone REPO_URL ~/code/claude-skills
# Link each skill into Claude Code’s skills directory
for s in ~/code/claude-skills/*/; do
  ln -sfn "${s%/}" ~/.claude/skills/"$(basename "$s")"
done

Real‑world case: previously the author had to manually locate each skill, reinstall dependencies, and configure them after a machine change—a half‑day effort. After cloning and running the loop, all symlinks are created in seconds and dependencies are installed automatically from each skill’s lockfile.

4. Global vs. project‑level installation

After symlinking, the next question is whether a skill should be linked globally ( ~/.claude/skills/, shared by all projects) or only within a specific project’s .claude/skills/ directory.

Common practice favors installing only inside a project to keep Claude Code’s context window small; a large global list can clutter the prompt and increase the chance of accidental activation. However, Claude Code expands skill metadata on demand, showing only the name and one‑line description unless the skill is invoked, so the impact is minimal for a handful of skills.

Global – for high‑frequency, cross‑project utilities (e.g., code-review).

Project‑local – for skills tied to a specific project’s conventions (e.g., api-scaffold that assumes a particular folder structure).

Example: moved api-scaffold and db-migration from the global area into a backend project’s .claude/skills/. After restarting Claude Code, those skills appeared only for that project, eliminating irrelevant suggestions in other repositories.

Detail: after linking a skill into a project, add the link path to the project’s .gitignore. The actual skill lives in the monorepo, so the link itself should not be version‑controlled.

5. Let the AI agent create links for you

If remembering the ln -sfn syntax is difficult, describe the desired link in natural language to Claude Code, and it will generate the symlink and update .gitignore automatically.

“Link the api-scaffold from ~/code/claude-skills into the current project’s .claude/skills/ and add it to .gitignore .”

Claude Code executes the command, creates the link, and verifies that Git ignores it, handling future additions, removals, or relocations with the same conversational approach.

6. Why adopt this workflow?

✅ Update once, propagate everywhere – a single commit updates all linked projects.

✅ Bug fixes in any project flow back to the central repository.

✅ New machine setup with one clone + loop command restores the entire skill set in seconds.

✅ Context‑aware loading – common skills stay global, specialized ones stay project‑local, keeping Claude Code’s prompt lean.