SkillFS

One source of truth for all your AI agent skills

English | 中文文档

You run Claude Code, Cursor, and a few other AI coding agents. Each one wants its skills in a different directory. So you end up with:

~/.claude/skills/pdf/SKILL.md
~/.agents/skills/pdf/SKILL.md
~/.clawdbot/skills/pdf/SKILL.md
~/.cursor/skills/pdf/SKILL.md

Same skill. Four copies. Every time you tweak the PDF skill, you have to sync four places — or forget, and they silently diverge.

SkillFS fixes this. It finds all your duplicate skills, migrates them to ~/.skills/, and replaces the copies with symlinks. Each agent still sees its own skills/pdf/ — but now they all point to the same files.

Quick Start

# 1. Install
npm install -g skillfs

# 2. See what's duplicated
sk doctor

# 3. Fix it
sk dedupe

That's it. Your agents won't notice the difference — they follow symlinks transparently.

Features

sk doctor          Scan all runtimes, find duplicates, estimate savings
sk doctor --json   Machine-readable JSON output for automation
sk doctor --snapshot  Cargo.lock-style reproducible lockfile
sk dedupe          Migrate duplicates to ~/.skills/, replace with symlinks
sk dedupe --dry-run   Preview without touching anything
sk install <path>  Install a skill to ~/.skills/ and link to runtimes
sk uninstall <name>   Remove a skill from ~/.skills/ and clean up symlinks
sk link --all      Link all ~/.skills/ back to every runtime
sk list            Visual tree of every skill and its link status
sk watch           Watch runtime dirs for new skills in real time

sk doctor

Auto-discovers every AI agent on your machine, then scans for duplicates:

• Scans ~/.*/skills/ — finds agents you forgot you even installed
• Identical duplicates (same MD5 hash) — safe to auto-migrate
• Conflicting versions (different content, same name) — needs your decision
• Disk space savings — how much you'll reclaim
• Drift detection — warns if a skill's SKILL.md has changed since last registry update
• Incomplete transactions — if a previous dedupe was interrupted, tells you how to recover

$ sk doctor

🔍 SkillFS Doctor 🔍

扫描目录：
✓ ~/.claude/skills      (5 skills)
✓ ~/.agent/skills       (3 skills)
✓ ~/.clawdbot/skills    (4 skills)
✓ ~/.skills              (2 skills)

发现重复 Skill：

  pdf          × 3  [内容相同 ✓]
  code-review  × 2  [内容不同 ⚠]

汇总：
  重复 Skill：2 个（共 5 个副本）
  内容冲突：1 个（需手动确认）
  可节省空间：约 156.3 KB

运行 sk dedupe 开始迁移

sk dedupe

The main event. Identical skills are migrated automatically. For conflicts, you get an interactive prompt:

• Choose which version to keep
• View a colored line-by-line diff between versions
• Skip and come back later

Every migration follows a transactional safety protocol:

1. Copy to ~/.skills/<name>/
2. Verify the copy is complete (recursive hash comparison)
3. Remove originals and create symlinks
4. Update the registry

If anything fails, all changes are rolled back.

sk dedupe           # Interactive
sk dedupe --dry-run # See what would happen, no changes made

sk link

Re-link centralized skills to your runtimes:

sk link pdf --runtime claude    # One skill → one runtime
sk link pdf --all               # One skill → all runtimes
sk link --all                   # Everything → everywhere

sk list

A tree view of your entire skill ecosystem:

$ sk list

📋 SkillFS List 📋

~/.skills (Source of Truth)
├── pdf              [claude ✓] [agent -] [clawdbot ✓]
└── code-review      [claude ✓] [agent ✓] [clawdbot ⚠]

~/.agent/skills (额外，未迁移)
└── legacy-formatter (未在 ~/.skills 中，运行 sk dedupe 迁移)

图例: ✓ 已链接  - 未链接  ⚠ 链接断裂

sk install

Copy a skill directory to ~/.skills/ and create symlinks to runtimes:

sk install ~/projects/my-skill           # Install and link to all runtimes
sk install ~/projects/my-skill -r claude # Install and link to one runtime
sk install --all-from claude             # Batch-install all unique skills from one runtime
sk install --all-from claude --dry-run   # Preview before batch-installing

The source must be a directory containing a SKILL.md file. SkillFS extracts the directory name as the skill name, copies everything to ~/.skills/<name>/, and optionally creates symlinks in each runtime's skills directory.

sk uninstall

Remove a skill from ~/.skills/ and clean up symlinks:

sk uninstall my-skill           # Remove from ~/.skills/ and all runtimes
sk uninstall my-skill -r claude # Remove from one runtime only, keep ~/.skills/

When removing from all runtimes (no --runtime flag), every symlink pointing to ~/.skills/<name> is removed, the central copy is deleted, and the registry entry is cleared. With --runtime, only the specified runtime's symlink is removed.

sk watch

Monitor runtime skills directories for new skills in real time:

sk watch                  # Watch all configured runtimes
sk watch --runtime claude # Watch one runtime only

Polling-based detection (every 2 seconds) — reliable across all platforms. When a new skill directory containing a SKILL.md appears, prints:

✨ 发现新 skill: my-skill — 使用 sk install ~/.claude/skills/my-skill 安装

Runs until Ctrl+C. Graceful shutdown on SIGINT.

CLI Reference

sk (top-level)

sk --help       # Show all commands and options
sk --version    # Print version number

sk doctor

Auto-discover agents and scan for duplicates, estimate savings.

sk doctor              # Human-readable report
sk doctor --json       # Machine-readable JSON output
sk doctor --snapshot   # Cargo.lock-style lockfile

| Option | Alias | Description | |--------|-------|-------------| | --json | — | Output analysis results as structured JSON to stdout | | --snapshot | — | Output a reproducible lockfile ({ skills: { name: { hash, runtimes } } }) |

Run it anytime — it's read-only, zero side effects. Automatically finds any ~/.{name}/skills/ directory with valid SKILL.md files.

When --json is passed, the output is a JSON object with runtimes, central, duplicates, totalDuplicatesCount, conflictsCount, savingsBytes, and incompleteTransactions fields — suitable for piping to jq or consumption by other tools.

sk dedupe

Migrate duplicates to ~/.skills/ and replace originals with symlinks.

sk dedupe              # Interactive migration
sk dedupe --dry-run    # Preview only — no files are modified

| Option | Alias | Description | |--------|-------|-------------| | --dry-run | — | Show what would happen without making any changes |

Identical skills (same MD5) are auto-migrated. Conflicting versions offer an interactive prompt to choose, view a diff, or skip.

sk link

Create symlinks from ~/.skills/ to runtime skills directories.

sk link <name> --runtime <name>      # Link one skill to one runtime
sk link <name> --all (-a)            # Link one skill to all runtimes
sk link --all (-a)                   # Link all skills to every runtime

| Option | Alias | Description | |--------|-------|-------------| | --runtime <name> | -r | Target runtime (e.g. claude, cursor, gemini) | | --all | -a | Link to all configured runtimes |

sk list

Display all skills in ~/.skills/ with their symlink status across runtimes.

sk list

No options. Shows ✓ (linked), - (not linked), ⚠ (broken link) per runtime.

sk install

Install skill(s) to ~/.skills/ and link to runtimes.

sk install <path>                     # Install one skill, link to all runtimes
sk install <path> --runtime <name>    # Install one skill, link to one runtime
sk install --all-from <runtime>       # Batch-install all unique skills from a runtime
sk install --all-from claude --dry-run # Preview batch install, no changes

| Option | Alias | Description | |--------|-------|-------------| | --runtime <name> | -r | Target runtime. If omitted, links to all configured runtimes. | | --all-from <name> | — | Scan a runtime's skills dir and install every non-symlink skill not yet in ~/.skills/ | | --dry-run | — | Preview only — no files are modified |

For single-skill install, <path> must be a directory containing a SKILL.md file. For batch install with --all-from, no <path> is needed — the runtime's skills directory is scanned automatically.

sk uninstall

Remove a skill from ~/.skills/ and clean up symlinks.

sk uninstall <name> --runtime <name>  # Remove from one runtime only
sk uninstall <name>                   # Remove from all runtimes and ~/.skills/

| Option | Alias | Description | |--------|-------|-------------| | --runtime <name> | -r | Only remove symlink from the specified runtime. Keeps the skill in ~/.skills/. Without this flag, removes everything: symlinks, central copy, and registry entry. |

Only removes symlinks that actually point to ~/.skills/<name>. Symlinks pointing elsewhere are left untouched.

sk watch

Monitor runtime skills directories for new skills in real time.

sk watch                  # Watch all configured runtimes
sk watch --runtime <name> # Watch one runtime only

| Option | Alias | Description | |--------|-------|-------------| | --runtime <name> | -r | Only watch the specified runtime. Omitting watches all configured runtimes. |

Polls every 2 seconds. Prints a notification when a new skill directory (with SKILL.md) appears. Runs until Ctrl+C.

Safety & Security

SkillFS modifies your filesystem. We take that seriously.

| Protection | How it works | |------------|-------------| | Dry run | sk dedupe --dry-run shows everything that would happen without touching a single file | | Transactional migration | Copy → verify → remove → symlink → registry. Any failure triggers full rollback | | Atomic file lock | O_CREAT \| O_EXCL prevents two sk processes from corrupting the registry | | Path traversal guard | All paths are validated — config.json can't trick the scanner into reading /etc | | Symlink target validation | Symlinks pointing outside your home directory are detected and rejected | | Incomplete transaction detection | sk doctor flags interrupted dedupe runs and shows recovery steps | | 127 tests | Full coverage of filesystem operations, scanner, registry, lock, and security edge cases |

Installation

Global install (recommended)

npm install -g skillfs
sk doctor

After global install, all commands are available as sk <command> anywhere.

From GitHub

git clone https://github.com/ares0x/skillfs.git
cd skillfs
pnpm install
pnpm run build

After building, use commands via one of these methods:

# Method 1: npm link (makes `sk` available globally)
npm link
sk doctor

# Method 2: pnpm dev script
pnpm run dev doctor
pnpm run dev dedupe --dry-run
pnpm run dev link --all
pnpm run dev list

# Method 3: direct Node execution
node dist/index.js doctor
node dist/index.js dedupe --dry-run
node dist/index.js link --all
node dist/index.js list

Requirements

• Node.js ≥ 18
• macOS or Linux (symlinks are Unix-only)
• pnpm (for development)

Custom Runtimes

Got an agent that isn't in the defaults? Add it to ~/.skills/config.json:

{
  "runtimes": [
    {
      "name": "custom-agent",
      "path": "~/my-custom-agent/skills"
    }
  ]
}

Auto-discovery — zero config. SkillFS scans ~/.*/skills/ for any directory with valid SKILL.md files. Install a new agent and sk doctor sees it immediately. No manual config, no hardcoded list to maintain. Use ~/.skills/config.json to exclude specific directories.

If you only use one agent — you probably don't need this. If you have 27 and didn't even remember half of them, this changes everything.

Architecture

src/
├── index.ts              # Commander CLI entry (6 subcommands)
├── commands/
│   ├── doctor.ts         # Scan, analyze, report (human + JSON)
│   ├── dedupe.ts         # Migrate with rollback + interactive diff
│   ├── link.ts           # Symlink management
│   ├── list.ts           # Tree visualization
│   ├── install.ts        # Skill installation
│   ├── uninstall.ts      # Skill removal
│   └── watch.ts          # Real-time directory monitor
├── core/
│   ├── config.ts         # Runtime definitions + custom config
│   ├── registry.ts       # ~/.skills/registry.json with atomic locking
│   ├── scanner.ts        # Multi-runtime directory scanner
│   └── skill.ts          # SKILL.md parser + MD5 identity
└── utils/
    ├── fs.ts             # Safe filesystem ops + path validation
    ├── lock.ts           # Atomic PID-based file lock
    └── display.ts        # Terminal output formatting

Data flow: Config → Scanner → Skill Parser → Registry → Commands

The central directory ~/.skills/ becomes the single source of truth. Runtimes see symlinks that transparently resolve to it. No agent needs to know SkillFS exists.

Who is this for?

• AI agent power users running multiple coding agents simultaneously
• Teams that want shared, version-controlled skill directories
• Anyone who ran ls ~/.*/skills and was surprised by the number

SkillFS auto-discovers every agent on your machine — you don't need to remember which ones you installed. sk doctor tells you.

Contributing

Bug reports and PRs welcome. Run tests before submitting:

pnpm test          # 127 tests, must all pass
pnpm run build     # TypeScript compilation, must succeed

Tests use vitest with isolated temporary directories (os.tmpdir()) — they never touch your real ~/.skills/.

License

ISC © Jace (Sanage)