skills-manager

Backup and restore your AI agent skills to GitHub.

A CLI companion to vercel-labs/skills — push your ~/.agents/ directory to a remote repo, pull it on any machine, and automatically symlink skills to all your agents.

English | 中文

---

Why

vercel-labs/skills installs and manages skills, but doesn't handle backup, restore, or cross-machine sync. skills-manager fills that gap:

• Push — commit and push ~/.agents/ (skills + lock file) to GitHub
• Pull — clone or pull your skills on any machine
• Link — read .skill-lock.json and create symlinks to every agent you use
• Project Link — link or copy skills directly to your current project directory for localized development

Note: This tool reads .skill-lock.json but never modifies it — that file is owned by vercel-labs/skills.

Installation

# Run directly (no install)
npx @tc9011/skills-manager push

# Or install globally
npm install -g @tc9011/skills-manager

Tip: After global install, use sm (or the full name skills-manager) instead of npx @tc9011/skills-manager in all commands below.

Requirements: Node.js ≥ 20, GitHub CLI (gh) recommended for auth.

Quick Start

# 1. Backup skills to GitHub
sm push

# 2. Restore on a new machine
sm pull --repo owner/my-skills

# 3. Re-link skills to agents (auto-runs after pull)
sm link

# 4. Link skills to current project directory
sm link --project

On first run, push and pull will interactively set up a git repo and remote if ~/.agents/ isn't already one.

Commands

sm push

Commits and pushes ~/.agents/ to its configured GitHub remote.

sm push
sm push -m "add new debugging skill"

Option	Description
-m, --message <msg>	Custom commit message (default: auto-generated)

sm pull

Pulls from GitHub and automatically runs link.

sm pull --repo tc9011/my-skills
sm pull                          # uses existing remote
sm pull --skip-link              # pull only, don't link

Option	Description
-r, --repo <owner/name>	GitHub repo to pull from
--skip-link	Skip automatic agent linking after pull

sm link

Reads .skill-lock.json and creates relative symlinks from each agent's skills directory to the canonical ~/.agents/skills/.

sm link
sm link --agents cursor opencode claude-code

Option	Description
-a, --agents <ids...>	Agent IDs to link (skips agent prompt when provided)
-p, --project	Link skills to project directory (CWD) instead of global paths
-s, --skills <skills...>	Skill names to link (project mode only, skips skill prompt)
--mode <mode>	copy or symlink (project mode only, default: copy, skips prompt)

An interactive multiselect prompt lets you pick which agents to link. Only agents with local directories are pre-selected. Your selection is remembered for next time.

When --agents is provided, the agent selection prompt is skipped entirely — useful for scripting and AI agent automation:

# Non-interactive: link all skills to specific agents
sm link --agents cursor opencode

Symlink model:

~/.config/opencode/skills/my-skill → ../../../.agents/skills/my-skill   (relative)
~/.claude/skills/my-skill          → ../../.agents/skills/my-skill      (relative)

Project Mode:

When using --project (or -p), you'll go through three interactive prompts:

1. Select skills — choose which skills to link (none pre-selected)
2. Copy or symlink — copy files (default, recommended) or create absolute symlinks
3. Select agents — choose which agents to set up project-level skills for

All three prompts can be skipped by providing --skills, --mode, and --agents on the command line:

# Fully non-interactive project link
sm link --project --agents cursor claude-code --skills my-skill --mode copy

Example project structure after link --project:

./project/
├── .agents/skills/my-skill       ← shared by universal agents (copied or symlinked)
├── .claude/skills/my-skill       ← claude-code specific
├── .cursor/skills/my-skill       → ~/.agents/skills/my-skill (absolute symlink)
└── .trae/skills/my-skill         ← trae specific

• Skill Selection: Only the skills you pick are copied/linked — you don't have to include everything.
• Deduplication: Agents sharing the same project path only trigger one copy/link operation.
• Copy vs Symlink: Copying creates independent files (recommended for portability). Symlinking points back to ~/.agents/skills/ using absolute paths.

Authentication

Authentication is optional. If git already has credentials configured (SSH keys, macOS Keychain, git credential-manager, etc.), push and pull will work without any extra setup.

When no git credentials are available, the CLI looks for a token in this order:

1. gh auth token — GitHub CLI (recommended)
2. $GITHUB_TOKEN — environment variable
3. $GH_TOKEN — environment variable

If none are found, git will attempt the operation unauthenticated — which works for public repos but will fail for private ones. The link command never requires authentication.

Supported Agents

46 agents — matching the full vercel-labs/skills registry.

Universal Agents (share ~/.agents/skills)

Agent	ID	Global Path
Amp	amp	$XDG_CONFIG_HOME/agents/skills
Antigravity	antigravity	~/.gemini/antigravity/skills
Cline	cline	~/.agents/skills
Codex	codex	$CODEX_HOME/skills
Cursor	cursor	~/.cursor/skills
Deep Agents	deepagents	~/.deepagents/agent/skills
Firebender	firebender	~/.firebender/skills
Gemini CLI	gemini-cli	~/.gemini/skills
GitHub Copilot	github-copilot	~/.copilot/skills
Kimi Code CLI	kimi-cli	$XDG_CONFIG_HOME/agents/skills
OpenCode	opencode	$XDG_CONFIG_HOME/opencode/skills
Replit	replit	$XDG_CONFIG_HOME/agents/skills
Universal	universal	$XDG_CONFIG_HOME/agents/skills
Warp	warp	~/.agents/skills

Non-Universal Agents (agent-specific paths)

Agent	ID	Global Path
AdaL	adal	~/.adal/skills
Augment	augment	~/.augment/skills
Claude Code	claude-code	$CLAUDE_CONFIG_DIR/skills
CodeBuddy	codebuddy	~/.codebuddy/skills
Command Code	command-code	~/.commandcode/skills
Continue	continue	~/.continue/skills
Cortex Code	cortex	~/.snowflake/cortex/skills
Crush	crush	$XDG_CONFIG_HOME/crush/skills
Droid	droid	~/.factory/skills
Goose	goose	$XDG_CONFIG_HOME/goose/skills
Hermes Agent	hermes	~/.hermes/skills
IBM Bob	bob	~/.bob/skills
iFlow CLI	iflow-cli	~/.iflow/skills
Junie	junie	~/.junie/skills
Kilo Code	kilo	~/.kilocode/skills
Kiro CLI	kiro-cli	~/.kiro/skills
Kode	kode	~/.kode/skills
MCPJam	mcpjam	~/.mcpjam/skills
Mistral Vibe	mistral-vibe	~/.vibe/skills
Mux	mux	~/.mux/skills
Neovate	neovate	~/.neovate/skills
OpenClaw	openclaw	~/.openclaw/skills
OpenHands	openhands	~/.openhands/skills
Pi	pi	~/.pi/agent/skills
Pochi	pochi	~/.pochi/skills
Qoder	qoder	~/.qoder/skills
Qwen Code	qwen-code	~/.qwen/skills
Roo Code	roo	~/.roo/skills
Trae	trae	~/.trae/skills
Trae CN	trae-cn	~/.trae-cn/skills
Windsurf	windsurf	~/.codeium/windsurf/skills
Zencoder	zencoder	~/.zencoder/skills

Environment Variables

Variable	Used By	Default
GITHUB_TOKEN	push, pull	—
GH_TOKEN	push, pull	—
XDG_CONFIG_HOME	opencode, amp, kimi-cli, replit, universal, goose, crush	~/.config
CODEX_HOME	codex	~/.codex
CLAUDE_CONFIG_DIR	claude-code	~/.claude

How It Works

~/.agents/                  ← Git repo (push/pull target)
├── .skill-lock.json        ← Owned by vercel-labs/skills (read-only)
└── skills/
    ├── my-skill/
    └── another-skill/

sm link reads .skill-lock.json → creates relative symlinks:

~/.cursor/skills/my-skill        → ../../.agents/skills/my-skill
~/.claude/skills/my-skill        → ../../.agents/skills/my-skill
~/.config/opencode/skills/my-skill → ../../../.agents/skills/my-skill

sm link --project reads .skill-lock.json → select skills → choose copy/symlink → select agents → copies/symlinks to CWD:

./my-project/.agents/skills/my-skill    ← copied from ~/.agents/skills/
./my-project/.claude/skills/my-skill    ← copied from ~/.agents/skills/

Skill

This project includes a skill at skills/skills-manager/ that teaches AI agents how to operate the CLI — push, pull, and link commands.

# Install via vercel-labs/skills CLI
npx skills add tc9011/skills-manager

# Install a specific skill to specific agents
npx skills add tc9011/skills-manager --skill skills-manager -a opencode -a claude-code

# Install globally (available across all projects)
npx skills add tc9011/skills-manager -g

Contributing

Setup

git clone https://github.com/tc9011/skills-manager.git
cd skills-manager
npm install

Development

# Run commands directly (no build step)
npx tsx src/index.ts push
npx tsx src/index.ts link

# Or via npm script
npm run dev -- push

Testing

npm test                  # run tests
npm run test:watch        # watch mode
npm run test:coverage     # with coverage report

Build

npm run build             # compile TypeScript → dist/
npm run lint              # run ESLint

Project Structure

src/
├── index.ts              # CLI entry point (Commander.js)
├── agents.ts             # 46-agent registry + path resolution
├── auth.ts               # GitHub token resolution
├── config.ts             # XDG-compliant config persistence
├── lockfile.ts           # Read-only .skill-lock.json parser
├── linker.ts             # Symlink creation + project-level copy/link
├── git-ops.ts            # Git push/pull via simple-git
├── commands/
│   ├── push.ts           # Push handler
│   ├── pull.ts           # Pull handler (auto-runs link)
│   └── link.ts           # Link handler (interactive multiselect)
└── prompts/
    └── search-multiselect.ts  # Searchable multi-select prompt component

Releasing

Releases are fully automated with semantic-release. Just use Conventional Commits and push to main:

Commit prefix	Version bump	Example
fix:	Patch (0.1.0 → 0.1.1)	fix: handle missing config
feat:	Minor (0.1.0 → 0.2.0)	feat: add export command
feat!: or BREAKING CHANGE:	Major (0.1.0 → 1.0.0)	feat!: drop Node 18 support

The CI pipeline will automatically:

1. Analyze commits since last release
2. Determine version bump
3. Update package.json + CHANGELOG.md
4. Publish to npm
5. Create a GitHub Release with notes

License

MIT