# Symlink Skills

> Symlink skills from this repo into one or more agent skill directories (defaults to ~/.claude/skills/ and ~/.agents/skills/) so they become globally discoverable. Supports interactive per-target selection via fzf, or --only/--skip filters. Use when the user says "install these skills", "make these skills global", "symlink skills to ~/.claude", "symlink skills to ~/.agents", "register the skills", or wants to update the global skill set after editing skills here.

- Skill: `usrrname/symlink-skills` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add usrrname/symlink-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/usrrname/symlink-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: usrrname (https://skillmd.com/u/usrrname)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/usrrname/symlink-skills

---


# Symlink Skills

Symlinks every directory under `<repo>/skills/` into each configured target,
making each skill in the registry globally discoverable. Edits in the repo are
picked up live because the symlinks point at the real files.

Default targets:

- `~/.claude/skills/` (Claude Code's standard skill directory)
- `~/.agents/skills/` (other agents that follow the same convention)
- `~/.cursor/skills/`
- `~/.config/opencode/skills/` on macOS, `~/.opencode/skills/` elsewhere (auto-detected via `$OSTYPE`; override with `OPENCODE_SKILLS_DIR`)

## Run

From the repo root:

```sh
./skills/symlink-skills/link.sh                          # link all skills into all default targets
./skills/symlink-skills/link.sh --interactive            # fzf checklist per target (pick which skills)
./skills/symlink-skills/link.sh --only gcm,depcheck      # link only named skills (comma-separated)
./skills/symlink-skills/link.sh --skip web-perf,changelog # link all except named skills
./skills/symlink-skills/link.sh --dry-run                # preview without changes
./skills/symlink-skills/link.sh --force                  # replace existing files / mis-pointed symlinks
./skills/symlink-skills/link.sh --unlink                 # remove only symlinks created by this skill
```

Pick targets explicitly (skips the defaults entirely once `--target` is set):

```sh
# Just Claude Code:
./skills/symlink-skills/link.sh --target ~/.claude/skills

# Multiple custom targets:
./skills/symlink-skills/link.sh --target ~/.claude/skills --target /work/.agents/skills

# Interactive per-target selection:
./skills/symlink-skills/link.sh --interactive --target ~/.claude/skills
```

`--interactive` (`-i`) shows an fzf multi-select checklist for each target — Tab/Space to toggle skills, Enter to confirm, Esc to skip that target. Falls back to all skills if fzf isn't installed. `--only` and `--skip` bypass the checklist.

Or override any default via env var:

```sh
CLAUDE_SKILLS_DIR=/tmp/fake-claude/skills \
AGENTS_SKILLS_DIR=/tmp/fake-agents/skills \
CURSOR_SKILLS_DIR=/tmp/fake-cursor/skills \
OPENCODE_SKILLS_DIR=/tmp/fake-opencode/skills \
  ./skills/symlink-skills/link.sh
```

## Behaviour

- **Idempotent.** Re-running is safe; correct symlinks are left alone.
- **Safe by default.** If `<target>/<name>` exists as a real directory (or as
  a symlink to a different target), the script refuses to overwrite it and
  exits non-zero. Pass `--force` to replace.
- **Per-target reporting.** Each target is processed in turn with its own
  pass/fail summary.
- **Scoped unlink.** `--unlink` removes only symlinks under each target whose
  target resolves back into this repo. Other files and symlinks are untouched.
- **Returns non-zero** if any skill could not be linked in any target.

## Why

Editing skills in one place (this repo) and having them auto-available in
every agent that reads from `~/.claude/skills/` or `~/.agents/skills/` beats
maintaining multiple copies.