Skip to content
BranchesTags
 
 

Repository files navigation

skillstash Banner

CI Status Release npm downloads License

One hub, all agents. Manage your AI agent skills in a single git-backed directory, and sync them to WorkBuddy, Codex, Claude Code, and more.

English | 中文

📦 Overview

skillstash is a CLI tool that centralizes your AI agent skills into a single git-backed hub. Install skills from ClawHub, GitHub, or local paths — then let skillstash copy them to every agent directory you use. Pull on one machine, sync everywhere.

~/.skillstash/skills-hub/ (git) ← Single source of truth
 ┌──────────────────────────┐
 │     registry.json  (git) │  ← Skill metadata (shared across devices)
 ├──────────────────────────┤
 │     local.json (ignored) │  ← Agent config & assignments (per-device)
 └──────────────────────────┘
 ┌──────────────────────────┐
 │     skills/              │
 │       finance-ops/       │
 │       anti-distill/      │
 │       my-custom-skill/   │
 └──────────────────────────┘
          │  skillstash link (copy)
    ┌─────┼──────┬──────────┐
    ▼     ▼      ▼          ▼
   WB    Codex  Claude    Agents
 skills/ skills/ skills/  skills/

Design decisions:

  • Copy by default — maximum compatibility, no symlink permission issues on Windows
  • Git-backed — version control, multi-device sync, and conflict resolution built in
  • Agent-agnostic — auto-detects installed agents, works with any combination
  • Remote-first init — init requires a remote Git URL, ensuring multi-device sync from day one

🚀 Quick Start

# Install globally
npm install -g skillstash

# Or use directly with npx
npx skillstash --help

# 1. Initialize the hub with a remote repository
skillstash init git@github.com:yourname/my-skills.git
# → Interactive prompt: choose which agents to manage (space to toggle, enter to confirm)

# 2. Install skills (from ClawHub, GitHub, or local path)
skillstash install clawhub:finance-ops
skillstash install owner/repo@skill-name   # GitHub
skillstash install ./my-local-skill         # Local path

# 3. Import existing skills from agent directories
skillstash import --force   # --force to overwrite existing

# 4. Link (copy) to all agent directories
skillstash link

# 5. Full sync — pull + verify + link + push
skillstash sync

🔄 Multi-Device Sync

Since init requires a remote URL, multi-device sync is built in from the start:

# On device A (first time)
skillstash init git@github.com:yourname/my-skills.git
# → Creates hub, imports local skills, pushes to remote

# On device B (first time)
skillstash init git@github.com:yourname/my-skills.git
# → Clones hub, imports any local-only skills, pushes merged result

# Daily workflow on any device
skillstash sync    # pull + verify + link + push

⚙️ Conflict Resolution

skillstash sync handles merge conflicts automatically — no manual intervention required in most cases.

How it works:

When two devices independently install or modify skills, sync uses a smart three-way merge instead of a plain git pull:

  1. git fetch — downloads remote changes without touching local files
  2. If both sides have diverged, skillstash performs an application-level merge of registry.json:
    • Newer updatedAt wins when the same skill was modified on both sides
    • Remote additions are merged in; local additions are preserved
    • A deletion on one side is respected unless the other side modified the skill after the deletion
  3. Any skill directory file conflicts are resolved automatically based on the same registry decision
  4. A merge commit is created and the sync continues normally

Uncommitted local changes are automatically committed before fetching, so they're never at risk.

If the hub is stuck in a MERGING state (e.g. from a previous interrupted sync):

cd ~/.skillstash/skills-hub && git merge --abort
# Then re-run:
skillstash sync

📖 Command Reference

skillstash init <remote-url>

Initialize the skills-hub with a remote Git repository. The hub is always at ~/.skillstash/skills-hub.

During init, you'll be prompted to choose which agents to manage. Use arrow keys to navigate, space to toggle selection, and enter to confirm. You can change this later with skillstash agents.

After agent selection and skill import, you'll be asked whether to run link immediately — this copies all skills from the hub into your managed agent directories so they're ready to use right away.

Remote Status Behavior
Empty repo Create hub locally → select agents → auto-import existing agent skills → prompt to link → git push
Non-empty with registry.json Clone hub → select agents → re-detect local agents → import new local skills → prompt to link → git push
Non-empty without registry.json ❌ Reject — not a skillstash repo. Prompt to create a new empty repo 
skillstash init git@github.com:yourname/my-skills.git
skillstash init https://github.com/yourname/my-skills.git

skillstash install <source>

Install a skill from ClawHub, a local path, or a GitHub repository.

skillstash install clawhub:finance-ops         # From ClawHub (requires clawhub CLI)
skillstash install ./my-local-skill            # From local path
skillstash install owner/repo@skill-name       # From GitHub
skillstash install clawhub:finance-ops --no-lint # Skip SKILL.md validation

ClawHub integration requires the clawhub CLI installed and logged in:

npm install -g clawhub
clawhub login

GitHub installation supports three repository layouts:

  • Standalone skill repo: SKILL.md at repository root
  • Skill-hub repo: skills/<name>/SKILL.md
  • Subdirectory skill: <name>/SKILL.md

Multi-skill repositories without @skill-name will prompt for selection.

skillstash import

Scan agent directories (resolving symlinks/Junctions), and import skills into the hub.

skillstash import                  # Import from all agents
skillstash import --agent claude   # Only from specific agent
skillstash import --force          # Re-import existing skills (overwrite)
skillstash import --dry-run        # Preview without making changes
skillstash import --no-lint        # Skip SKILL.md validation

skillstash link

Copy skills from hub to all agent directories.

skillstash link                    # Link all skills to all agents
skillstash link --agent workbuddy  # Only to specific agent
skillstash link --skill finance-ops # Only specific skill
skillstash link --clean            # Remove unmanaged skills from agent dirs

skillstash list

List installed skills and their status across agents.

skillstash list                    # Summary view
skillstash list -v                 # Verbose with descriptions

skillstash sync

Full sync: git pull → verify integrity → link to agents → git push.

skillstash sync                    # Full sync
skillstash sync --no-pull          # Skip git pull
skillstash sync --no-push          # Skip git push
skillstash sync --no-link          # Skip linking
skillstash sync --clean            # Remove unmanaged skills

skillstash diff

Show differences between hub and agent directories.

skillstash diff                    # Compare all agents
skillstash diff --agent workbuddy  # Only specific agent

skillstash remove <skill-name>

Remove a skill from hub and all agent directories.

skillstash remove old-skill              # Remove everywhere
skillstash remove old-skill --keep-agents  # Only remove from hub

skillstash agents

Manage which agents skillstash syncs with. Only enabled agents receive skills during link and sync.

skillstash agents list              # Show all agents with available/managed status
skillstash agents select            # Interactively choose which agents to manage
skillstash agents enable claude     # Enable a specific agent
skillstash agents disable codex     # Disable an agent (skip for link/sync)

The select subcommand shows the same interactive checkbox UI as init — arrow keys to navigate, space to toggle, enter to confirm. Shortcuts: a to select all, i to invert selection.

skillstash assign

Configure which skills each agent receives on the current device, independently from every other device.

skillstash assign                   # Configure all enabled agents
skillstash assign --agent claude    # Configure only a specific agent

Running the command opens a checkbox prompt for each agent. Items are pre-checked based on the previous assignment (or all-checked on first run). After confirming, you are prompted to apply the changes immediately with link.

Assignments are stored in local.json (gitignored) and are completely independent per machine. Agents without an explicit assignment continue to receive all globally enabled skills — the new capability is entirely opt-in.

Example: different skills per device

# On your workstation: claude gets coding tools only
skillstash assign --agent claude
# → select: git-commit, finance-ops

# On your writing machine: claude gets document tools only
skillstash assign --agent claude
# → select: document-pdf, citation-management

Both machines share the same hub and sync the same skill files. Only the assignment differs.

🤖 Supported Agents

Agent Skills Directory Auto-detected
WorkBuddy ~/.workbuddy/skills/ ✅
CodeBuddy ~/.codebuddy/skills/ ✅
Codex ~/.codex/skills/ ✅
Claude Code ~/.claude/skills/ ✅
Agents (generic) ~/.agents/skills/ ✅

All agents are auto-detected, but you can choose which ones to manage via skillstash init or skillstash agents select. Disabled agents are still detected but skipped during link and sync.

🗂️ Registry Schema

The hub splits state across two files:

File Git-tracked Contains
registry.json ✅ Skill metadata: name, version, hash, source URL
local.json ❌ Agent config, skill assignments, last sync time

local.json is added to the hub's .gitignore automatically. This eliminates merge conflicts from device-specific state, and gives each device its own independent assign configuration.

registry.json (shared across devices):

{
  "version": "1.0",
  "skills": {
    "finance-ops": {
      "version": "1.0.0",
      "source": "github",
      "sourceUrl": "https://github.com/owner/repo",
      "hash": "sha256:abc123...",
      "enabled": true,
      "description": "AI CFO assistant",
      "installedAt": "2026-04-24T12:00:00Z",
      "updatedAt": "2026-04-24T12:00:00Z"
    }
  }
}

local.json (gitignored, per-device):

{
  "lastSync": "2026-04-24T12:00:00Z",
  "agents": {
    "claude": {
      "name": "claude",
      "skillsPath": "~/.claude/skills",
      "linkType": "copy",
      "available": true,
      "enabled": true
    }
  },
  "agentSkills": {
    "claude": ["finance-ops", "git-commit"]
  }
}

🏗️ Project Structure

skillstash/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── commands/
│   │   ├── agents.ts         # skillstash agents
│   │   ├── assign.ts         # skillstash assign
│   │   ├── init.ts           # skillstash init <remote-url>
│   │   ├── install.ts        # skillstash install
│   │   ├── link.ts           # skillstash link
│   │   ├── list.ts           # skillstash list
│   │   ├── sync.ts           # skillstash sync
│   │   ├── diff.ts           # skillstash diff
│   │   ├── remove.ts         # skillstash remove
│   │   └── import.ts         # skillstash import
│   ├── core/
│   │   ├── registry.ts       # Registry types & operations
│   │   ├── hub.ts            # Hub directory management
│   │   ├── git.ts            # Git operations
│   │   ├── merge.ts          # Three-way registry merge
│   │   └── skill.ts          # SKILL.md parsing & linting
│   └── utils/
│       ├── fs.ts             # File system utilities
│       ├── logger.ts         # Colored logging
│       └── prompt.ts         # Interactive prompts (checkbox)
├── docs/
│   └── images/               # Assets
├── package.json
├── tsconfig.json
└── README.md

🛠️ Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js --help

# Watch mode
npm run dev

📄 License

MIT

About

One hub, all agents. Manage your AI agent skills in a single git-backed directory, and sync them to WorkBuddy, Codex, Claude Code, and more.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages