Local Skill Manager

Manage installed skills with versioning and rollback capabilities.

How It Works

Each skill stores its version number in .version. All version archives are centralized under skill-version-manager/.versions/your-skill/:

skill-version-manager/
└── .versions/                  # centralized archive storage
    ├── skill-a/
    │   ├── 1.3.12_20260721_120000_fix_bug.zip
    │   └── 1.3.13_20260721_150000_add_feature.zip
    └── skill-b/
        └── 2.0.1_20260721_120000_init.zip

your-skill/
└── .version              # {"major":1,"minor":3,"patch":12,"last_updated":"..."}

save: zips current state → bumps version → writes .version
rollback: backs up current state → clears files → extracts archive
Archives automatically exclude .token, config.json, *.env, .git, __pycache__, *.pyc

Scripts

Two implementations, pick whichever runs:

| Script | Runtime | Dependencies | |--------|---------|-------------| | scripts/skill-manager.py | Python 3.6+ | None (stdlib only) | | scripts/skill-manager.js | Node.js 10+ | None (JSZip embedded) |

Prefer Python. Both work on macOS / Windows / Linux.

Commands

python3 scripts/skill-manager.py <command> [options]
node scripts/skill-manager.js <command> [options]

| Command | Usage | |---------|-------| | list <root> | List all installed skills in the given directory | | version <path> | Show current version of a skill | | history <path> | List all version archives with IDs, timestamps, descriptions | | save <path> [desc] [--bump patch\|minor\|major] | Archive current state and bump version (default: patch) | | rollback [--force] <path> <id> | Revert to archive by ID (1-based). --force skips confirmation |

Versioning: --bump patch (bug fix), --bump minor (new feature), --bump major (breaking change).

Interactive Workflow

Below are the conversation flows you MUST follow when users ask you to perform skill management tasks.

Rule 0: Universal Rules

Never guess paths. If unsure where a skill lives, ask the user or run list on a likely directory.
Never archive without a description. If the user didn't provide one, ask. An archive without a description is like a git commit without a message — useless.
Always report results. After any command, tell the user what happened (new version number, which archive was restored, etc.).
Pick the right runner. Use python3 scripts/skill-manager.py if Python 3 is available; fall back to node scripts/skill-manager.js. Either works.

Scenario 1: Save / Archive a Skill

Triggers: "archive X", "save X", "保存版本", "归档 X", "打个版本", "存档"

Step 1 — Resolve path:

If user said a skill name (e.g. "归档 lol"):
  Try the path they mentioned directly. If unsure, ask the user or run `list`.
If user didn't name a skill but you just edited one in this conversation:
  Use that skill's path directly.

Step 2 — Demand a description (HARD RULE):

If the user did NOT provide a description of what changed:

请描述一下这次改动了什么，我加到归档信息里。

Do NOT proceed until they answer. No exceptions.

Step 3 — Choose bump type:

| User said | Use | |-----------|-----| | (nothing specific) | --bump patch (default) | | "新功能" / "新增" / "加了" / "new feature" | --bump minor | | "重构" / "大改" / "不兼容" / "breaking" | --bump major | | Unsure | Ask: "这次是 bug 修复(patch)、新功能(minor)还是大版本(major)？" |

Step 4 — Execute and report:

python3 scripts/skill-manager.py save <path> "<description>" --bump <type>

Report the new version number to the user.

Examples:

User: 归档 lol，修复了登录接口返回 500 的问题

AI: (resolves path → ~/.claude/skills/lol/, sees "修复" → --bump patch) → runs: python3 scripts/skill-manager.py save ~/.claude/skills/lol "修复登录接口返回500的问题" --bump patch → replies: 已归档 lol，版本 v1.2.3 → v1.2.4

User: 保存版本

AI: 请描述一下这次改动了什么，我加到归档信息里。

User: 加了批量删除功能

AI: (sees "加了" → --bump minor) → runs: python3 scripts/skill-manager.py save <path> "新增批量删除功能" --bump minor → replies: 已归档，版本 v1.2.4 → v1.3.0

User: 归档 my-skill，重构了整个插件架构，breaking change

AI: (sees "重构" and "breaking" → --bump major) → runs: python3 scripts/skill-manager.py save ~/.claude/skills/my-skill "重构插件架构" --bump major → replies: 已归档，版本 v1.3.0 → v2.0.0

Scenario 2: Rollback / Revert a Skill

Triggers: "回滚", "rollback", "恢复", "退回到", "revert"

Step 1 — Show history first:

python3 scripts/skill-manager.py history <path>

Present the output. Let the user pick which archive ID to restore.

Step 2 — Warn and confirm:

Tell the user:

All current files will be overwritten
A backup of current state will be auto-created before rollback
Suggest checking files after rollback

Step 3 — Execute:

# Interactive terminal (user can type y/N)
python3 scripts/skill-manager.py rollback <path> <archive-id>

# Non-interactive (CI, piped, background scripts)
python3 scripts/skill-manager.py rollback --force <path> <archive-id>

Example:

User: 回滚 lol，之前那个版本有问题

AI: (runs history ~/.claude/skills/lol) → shows:
ID  | Version  | Timestamp         | Description
1   | v1.2.4   | 20260721_150000   | 修复登录接口返回500的问题
2   | v1.2.3   | 20260721_120000   | 新增批量删除功能
3   | v1.2.2   | 20260720_090000   | 初始化
AI: 有三个存档，要回滚到哪个？

User: 第 2 个

AI: 回滚到 v1.2.3 会覆盖当前所有文件，操作前会自动备份当前状态。确认继续吗？ → runs: python3 scripts/skill-manager.py rollback ~/.claude/skills/lol 2 → replies: 已回滚到 v1.2.3，当前状态已备份为 pre_rollback_to_v1.2.3

Scenario 3: View History

Triggers: "history", "历史", "版本记录", "有哪些版本"

No confirmation needed. Just run:

python3 scripts/skill-manager.py history <path>

Example:

User: lol 有哪些版本？

AI: → runs: python3 scripts/skill-manager.py history ~/.claude/skills/lol

Scenario 4: Check Current Version

Triggers: "version", "版本", "当前版本", "什么版本"

python3 scripts/skill-manager.py version <path>

Example:

User: lol 现在什么版本？

AI: → runs: python3 scripts/skill-manager.py version ~/.claude/skills/lol → replies: lol 当前版本 v1.2.4，最后更新 2026-07-21 15:00

Scenario 5: List All Skills

Triggers: "list", "有哪些 skill", "列出", "list skills"

python3 scripts/skill-manager.py list

Example:

User: 有哪些 skill？

AI: → runs: python3 scripts/skill-manager.py list