A pnpm-inspired CLI for managing Agent skills with content-addressable storage.
- Content-addressable storage — Skills are SHA-256 hashed and deduplicated in a global store
- Profile management — Create named skill collections, switch between them instantly
- Version tracking — Every save creates a new version; reference any version by number
- Global & project scopes — Install skills user-wide or per-project, move them freely between scopes
- Multiple sources — Add skills from GitHub repos, git URLs, or local paths
- Multi-client support — Sync skills to Claude, Cursor, OpenCode, Gemini, Copilot, Roo, Goose, and Amp simultaneously
npm install -g better-skills
pnpm add -g better-skills
bun add -g better-skillsRequires Node.js >= 18 (or Bun).
curl -fsSL https://raw.githubusercontent.com/ocherry341/better-skills/main/packages/install/install.sh | bashInstalls a platform-specific binary to ~/.local/bin/. Supports Linux (x64/arm64) and macOS (x64/arm64).
You can also download binaries directly from the GitHub Releases page.
Still managing your skills manually? Just one command to unlock the full power of bsk:
bsk saveVersioning, deduplication, profile switching — all yours, instantly.
# Launch interactive TUI
bsk
# Add a skill from GitHub
bsk add owner/repo
# Add a skill from a subdirectory
bsk add owner/repo/path/to/skill
# Add from a local path
bsk add ./my-skill
# List active skills
bsk ls
# List all managed skills (including inactive)
bsk ls -absk add <source> # Add a skill (github, git, local path)
bsk install <source> # Alias for add (also: bsk i)
bsk rm <name> # Remove a skill
bsk ls [-a] # List skills (-a for all managed)
bsk save [name] # Save new/changed skills to management
bsk mv <skill> <scope> # Move skill between global/project scopeOptions for add / install:
-g, --global # Install to global skills directory
-n, --name <name> # Override the skill name
-f, --force # Overwrite unmanaged skills
-y, --yes # Skip confirmation prompts
--hardlink # Use hard links instead of file copybsk add owner/repo # GitHub repo root
bsk add owner/repo/subdir # GitHub subdirectory
bsk add https://github.com/owner/repo # Full GitHub URL
bsk add https://github.com/owner/repo/tree/main/subdir # Branch + path
bsk add https://gitlab.com/owner/repo # Any HTTPS git URL
bsk add [email protected]:owner/repo.git # Git SSH
bsk add ./local/path # Local directory (also ../ and /abs)Profiles are named snapshots of skill collections with version references.
bsk profile create <name> # Create a profile from current skills
bsk profile ls # List all profiles
bsk profile show [name] # Show profile details
bsk profile use <name> # Switch to a profile
bsk profile add <skill> # Add a skill to active profile
bsk profile rm <skill> # Remove a skill from active profile
bsk profile clone <from> <to> # Clone a profile
bsk profile rename <old> <new>
bsk profile delete <name>Version specifiers for profile operations:
bsk profile add my-skill@latest # Latest version
bsk profile add my-skill@previous # Previous version
bsk profile add my-skill@v2 # Specific version
bsk profile add my-skill@~1 # Relative (latest minus 1)
bsk profile add my-skill@abc123 # Hash prefix matchEnable additional clients to automatically sync skills to their directories.
bsk client ls # List enabled clients
bsk client add claude cursor gemini # Enable clients
bsk client rm cursor # Disable a clientSupported clients: claude, cursor, opencode, gemini, copilot, roo, goose, amp
bsk store verify # Check integrity of all store entries
bsk store ls # List all store entries with skill/version info
bsk store prune # Delete all orphan entries from the store
bsk store adopt # Re-register orphan store entries into registry~/.better-skills/ is a self-contained data directory. Sync it with any tool you prefer.
bsk sync restore # Rebuild live skills from store and profile
bsk sync export # Export ~/.better-skills/ as tar.gz
bsk sync import <file> # Import tar.gz and restore
bsk cd # Open a shell in ~/.better-skills/Quick start with git:
cd ~/.better-skills
git init && git add -A && git commit -m "init"
git remote add origin <your-repo> && git push
# On another machine:
git clone <your-repo> ~/.better-skills
bsk sync restoreSimple backup/transfer (no git needed):
bsk sync export # Machine A
bsk sync import better-skills-backup.tar.gz # Machine Brsync:
rsync -az ~/.better-skills/ remote:~/.better-skills/
ssh remote bsk sync restoreSyncthing / other:
Sync ~/.better-skills/ as a shared folder, then run bsk sync restore on each machine.
Skills are directories containing a SKILL.md file with YAML frontmatter:
---
name: my-skill
description: What this skill does
---
# My Skill
Instructions for the AI agent...~/.better-skills/
├── store/{hash}/ # Content-addressable store (immutable)
├── registry.json # Tracks all skill versions and hashes
├── profiles/ # Named skill collections
├── active-profile # Currently active profile name
└── config.json # Enabled clients
~/.agents/skills/ # Global skills (copied from store)
./.agents/skills/ # Project skills
- Add — Skill is fetched, hashed, and stored in
~/.better-skills/store/{hash}/ - Link — Files are copied from the store to skill directories (use
--hardlinkfor hard links) - Sync — Copies are replicated to all enabled client directories (e.g.,
~/.claude/skills/,~/.cursor/skills/) - Version — Each save creates a new registry entry; old versions remain in store
Identical skills across projects share a single store entry. The SHA-256 hash is computed deterministically from file paths and contents, so the same skill always produces the same hash.
- TUI — Interactive terminal UI for managing skills
- Built-in
use better-skillsskill — A bundled skill that teaches agents how to usebsk - Skills security audit — Security review and sandboxing for skill content
This is a Bun workspace monorepo.
bun install # Install dependencies
bun run dev # Run CLI from source
bun run build # Build (tsdown → dist/cli.mjs)
bun run test # Run tests
bun run typecheck # TypeScript strict check
bun run build:binary # Compile cross-platform binariesMIT