symskill

Symlink your AI skills. Edit once, apply everywhere.

Maintain your own AI skills library (Claude, Cursor, etc.) in one place. Changes propagate instantly to all linked projects via symlinks.

No more copy-paste. No more reinstall. Just link.

The Problem

When working with AI coding tools, you accumulate skills/rules/commands that you want to reuse:

1. Scattered skills — You copy the same skills to multiple projects, they drift out of sync
2. Edit-reinstall cycle — Copy-based tools require reinstalling when you update a skill
3. Multi-tool chaos — Claude uses .claude/skills/, Cursor uses .cursor/skills/ — managing both is tedious

The Solution

symskill uses symlinks instead of copies:

~/my-skills/
  go-expert/
  k8s-debug/

# Register your skills directory
symskill source add ~/my-skills

# Apply to current project (auto-detects .claude/ and .cursor/)
symskill apply go-expert

# Result: project/.claude/skills/go-expert -> ~/my-skills/go-expert (symlink)

Edit ~/my-skills/go-expert once → all linked projects see the change instantly.

Installation

# Clone and build
git clone https://github.com/clark-ioe/symskill.git
cd symskill
npm install
npm run build

# Link globally (optional)
npm link

Quick Start

# 1. Register your skills directory
symskill source add ~/my-skills

# 2. List available skills
symskill list

# 3. Apply a skill to current project
cd ~/projects/my-app
symskill apply go-expert

# 4. Check status
symskill status

Commands

symskill source

Manage skill source directories.

symskill source add <path>     # Register a skills directory
symskill source remove <path>  # Unregister a directory
symskill source list           # List registered sources

symskill list

List all available skills from registered sources.

symskill apply

Apply skills to the current project.

symskill apply <skillname>           # Apply to auto-detected targets
symskill apply <skillname> -t claude # Apply to specific target
symskill apply <skillname> --global  # Apply to ~/.claude/skills/
symskill apply <skillname> --copy    # Copy instead of symlink
symskill apply <skillname> --force   # Overwrite existing
symskill apply --all                 # Apply all available skills

symskill remove

Remove a skill from the current project.

symskill remove <skillname>
symskill remove <skillname> --global

symskill status

Show status of skills in the current project.

Skills status:
  ✓ symlink  [claude] go-expert
  ✓ symlink  [cursor] go-expert
  - missing  [claude] k8s-debug

How It Works

┌─────────────────┐
│  ~/my-skills/   │  <- Your skills library (single source of truth)
│  ├── go-expert/ │
│  └── k8s-debug/ │
└────────┬────────┘
         │ symlink
         ▼
┌─────────────────────────────────────────┐
│  project-a/.claude/skills/go-expert -> ~/my-skills/go-expert
│  project-a/.cursor/skills/go-expert -> ~/my-skills/go-expert
│  project-b/.claude/skills/go-expert -> ~/my-skills/go-expert
└─────────────────────────────────────────┘

symskill vs Copy-based Tools

	Copy-based tools	symskill
Model	Install -> Copy	Register -> Symlink
On edit	Reinstall everywhere	Instant everywhere
Philosophy	npm install	dotfiles / GNU Stow
Best for	Community skills	Your own skills library

Supported Targets

• Claude (.claude/skills/) — project and global
• Cursor (.cursor/skills/) — project only

More targets coming (Windsurf, Codex, etc.)

Configuration

Config is stored at ~/.symskill/config.json:

{
  "sources": [
    "/Users/you/my-skills",
    "/Users/you/work-skills"
  ]
}

No config files are created in your projects — zero intrusion.

Status

Personal tool, actively used. Issues and PRs welcome, but no SLA.

License

MIT