Skip to content

songpl-AI/LocalSkillsManager

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
docs
docs
 
 
library/skill-manager
library/skill-manager
 
 
profiles
profiles
 
 
skill-manager
skill-manager
 
 
.DS_Store
.DS_Store
 
 
CLAUDE.md
CLAUDE.md
 
 
INSTALL.md
INSTALL.md
 
 
README.md
README.md
 
 
sm
sm
 
 

Repository files navigation

LocalSkillManager

Claude Code skill 的集中管理方案。

所有 skill 存放在一个 library/ 目录，通过包管理器模式部署到全局或任意项目。sm install 复制完整文件，在编辑器里可见可浏览；sm update 先从远程拉取最新版（如有 source 字段），再将变更推送到所有安装位置。

目录

为什么需要它

痛点 sm 的解法
新建项目要手动复制 skill sm init 一键建目录 + 安装默认 skill
不知道项目里装了哪些 skill 真实文件，编辑器直接可见
skill 更新后要逐项目同步 sm update 推送到所有已注册项目
散落在各处的副本不知哪个最新 sm import-scan 批量扫描 + 交互去重
已安装的 skill 想纳入库管理但不想重新安装 sm adopt 原地接管，自动重建 manifest
不知道某个 skill 装在哪里 sm where <skill> 全局查找
没有版本历史，改坏了无法恢复 library 是 git repo，sm log / sm rollback
来自别人的 skill 无法追踪更新 source 字段 + sm update 自动拉取

核心概念

包管理器模式

sm install 将 skill 的所有文件完整复制到项目，同时写入 .sm-manifest.json 记录文件 hash：

project/.claude/skills/lua-analyze/      ← 真实文件，编辑器可见（自动触发）
  SKILL.md
  scripts/
  references/

project/.claude/skills/.sm-manifest.json
{
  "lua-analyze": {
    "version": "1.2.0",
    "files": { "SKILL.md": "sha256:...", "scripts/run.sh": "sha256:..." }
  }
}

sm update 比对 hash，只更新有变化的文件，不触碰 skill 生成的 output/、cache/ 等额外目录。

四级部署

部署位置 命令 触发方式 作用范围
~/.claude/skills/ sm install skill <name> -g Claude 自动调用 所有项目
~/.claude/commands/ sm install cmd <name> -g /skill-name 手动触发 所有项目
<project>/.claude/skills/ sm install skill <name> Claude 自动调用 仅该项目
<project>/.claude/commands/ sm install cmd <name> /skill-name 手动触发 仅该项目

安装

cd /path/to/LocalSkillManager
./sm setup          # 写入 ~/.zshrc，将 sm 加入 PATH
source ~/.zshrc     # 立即生效
sm help             # 验证安装

依赖：bash 3.2+、Python 3（macOS 自带）、git（版本管理功能需要）

详细安装步骤见 INSTALL.md。

新手入门：第一次使用

第一步：初始化新项目

这是最常见的起点。一条命令完成所有准备工作：

sm init ~/Documents/MyProject

执行内容：创建 .claude/commands/ 和 .claude/skills/，注册项目，安装默认 skill。

Initializing: MyProject
  ~/Documents/MyProject

✓  Created .claude/commands/
✓  Created .claude/skills/
✓  Registered for tracking

→  Default skills configured:
    • lua-analyze   ✓ in library

  Install default skills? (Y/n): y
✓  lua-analyze   → project Skill tool (MyProject)

✓  Done — MyProject is ready

安装后在 VS Code 里可以直接展开 .claude/commands/lua-analyze/ 看到文件内容。

如果还没有配置默认 skill，先跳过，后面再用 sm install 逐个安装。

第二步：安装更多 skill

cd ~/Documents/MyProject

sm install skill lua-debug    # 安装到当前项目（Claude 自动触发）
sm install skill lua-analyze  # 再安装一个

sm install cmd init-git       # 安装为斜杠命令（手动 /init-git 触发）

# 或者按技能包批量安装（默认 skill 类型）
sm profile install my-profile
  • skill 类型安装到 .claude/skills/，Claude 根据上下文自动调用
  • cmd 类型安装到 .claude/commands/，在对话中输入 /name 手动触发

第三步：发现有哪些 skill

sm list              # 查看 library 里的全部 skill
sm list lua          # 搜索名称或描述包含 "lua" 的 skill
sm status            # 查看当前全局 + 所有注册项目的安装状态

进阶使用

全局安装

加 -g 即可全局安装，所有项目都能用，无需每次 sm install：

# 全局自动触发（所有项目 Claude 都能感知）
sm install skill skill-manager -g    # 推荐：skill 管理助手
sm install skill lua-analyze -g      # Claude 自动判断何时分析 Lua 脚本

# 全局斜杠命令（所有项目都能 /name 触发）
sm install cmd init-git -g

skill 与 cmd 的区别：

  • skill → ~/.claude/skills/：Claude 自动调用，根据上下文判断
  • cmd → ~/.claude/commands/：需要你手动 /name 触发

创建自己的 skill

方式一：向导式创建（推荐）

sm new my-skill
# → 填写向导：description、version、source、allowed-tools
# → 自动打开 $EDITOR
# → 选择是否 commit

方式二：基于已有 skill 改造

sm cp lua-analyze lua-analyze-v2   # 复制为起点
sm open lua-analyze-v2             # 编辑修改

测试后部署：

sm install skill my-skill         # 先装到当前项目测试（自动触发）
sm install skill my-skill -g      # 稳定后全局化

订阅他人的 skill

# 直接用 GitHub URL 导入（自动记录 source）
sm add https://github.com/someone/skills/tree/main/cool-skill

# 以后一键更新到最新版
sm update cool-skill

整理散落的旧 skill

如果以前的 skill 散落在各个项目目录里：

# 扫描整个目录，重名的交互去重，自动导入
sm import-scan ~/Documents/AIProjects/Skills

# 验证导入结果
sm validate

# 提交初始库
git add -A && git commit -m "init: import skill library"

如果只想接管某个已知位置的单个 skill，且不想重新安装（保持原位），用 sm adopt：

# 接管项目 skill（识别为 .claude/skills/，重装为 project skill）
sm adopt ./.claude/skills/my-old-skill

# 接管全局 skill（识别为 ~/.claude/skills/，重装为全局 skill）
sm adopt ~/.claude/skills/my-old-skill

# 接管斜杠命令
sm adopt ~/.claude/commands/init-git

# 等价的 --adopt flag 写法
sm add ./.claude/skills/my-old-skill --adopt

维护与管理

更新 skill

修改了 library 里的 skill 后，推送到所有已安装的项目：

# 推送单个 skill 到所有安装位置
sm update lua-analyze

# 同时从远程拉取最新版 + 推送到所有安装位置
sm update lua-analyze    # 如果有 source 字段，会先 pull 再 push

# 全量更新（有 source 字段的先拉取；所有 skill 均推送到已安装位置）
sm update

update 的安全保证：

  • 只覆盖 manifest 追踪的文件（即 install 时从 library 复制来的）
  • skill 生成的 output/、cache/ 等目录不受影响
  • 如果某个文件被本地修改过，会在覆盖前发出警告

版本与回滚

# 查看某个 skill 的提交历史
sm log lua-analyze

# 交互式选择版本恢复到 library
sm rollback lua-analyze

# 恢复后推送到各项目
sm update lua-analyze

最佳实践： 每次对 library 做修改后先 commit，才有历史可回滚：

git add -A && git commit -m "update lua-analyze: add nil-check support"

整理迭代版本

# 查看所有 figma 相关 skill
sm list figma

# 废弃旧版本
sm deprecate figma-to-unity-old on figma-to-unity

# 重命名最终版为正式名（同步更新所有安装位置）
sm rename figma-to-unity-new-4 figma-to-unity

# 确认
sm where figma-to-unity

对话式管理（skill-manager）

全局安装 skill-manager 后，在任何项目的 Claude Code 对话中直接用自然语言操作：

"帮我列出所有 skill" "把 lua-debug 安装到当前项目" "查看 lua-analyze 部署在哪里" "更新所有 skill"

命令详解

库管理

sm list [query]

sm list              # 全部
sm list lua          # 过滤名称或描述包含 "lua" 的 skill

标记说明：

  • v1.0.0 — frontmatter version 字段
  • [↑remote] — 有 source 字段，支持 sm update 拉取更新
  • [deprecated] — 已标记废弃，红色显示

sm add <path-or-url> [name]

# 本地路径
sm add ~/my-project/.claude/commands/lua-debug
sm add ~/Downloads/some-skill.md
sm add ~/skills/figma-skill figma-to-unity   # 指定导入名称

# GitHub URL
sm add https://github.com/owner/repo/tree/main/path/to/skill
sm add https://github.com/owner/skill-repo
  • 递归下载目录中所有文件（SKILL.md、references/、scripts/ 等）
  • 如果 SKILL.md 中没有 source 字段，自动注入来源 URL
  • 私有 repo 需设置 GITHUB_TOKEN 环境变量
  • 加 --adopt 时：导入后删除原文件并在原位置重装（等同于 sm adopt）

sm adopt <path> [name]

把本地已有的 skill 纳入库管理，并在原位置重建 manifest。适合"已经安装好、只想让 sm 接管"的场景。

sm adopt ~/.claude/skills/lua-analyze          # 接管全局 Skill tool
sm adopt ~/.claude/commands/init-git           # 接管全局斜杠命令
sm adopt ./.claude/skills/my-old-skill        # 接管项目 skill
sm adopt ./.claude/skills/my-old-skill v2     # 接管并指定 library 名称

执行步骤：

  1. 复制到 library/<name>/
  2. 删除原路径文件
  3. 在原路径重装（写入 manifest），行为与 sm install 完全一致

路径自动识别：/.claude/skills/ → skill 类型；/.claude/commands/ → cmd 类型。若路径不在 .claude 目录内，只导入库，不做删除和重装。

与 sm add 的区别：sm add 只把 skill 导入 library，不影响原路径；sm adopt 额外删除原文件并重建 manifest。

sm import-scan <dir>

批量扫描，处理重名副本：

sm import-scan ~/Documents/AIProjects/Skills

已在 library 的同名 skill 自动跳过；多个副本按最后修改时间倒序展示，交互选择。

sm new <name>

向导式在 library 里创建新 skill，自动打开 $EDITOR，可选择是否 commit。

sm validate [skill]

sm validate              # 检查所有 skill
sm validate lua-analyze  # 检查单个
级别 条件
error 缺少 name 或 description 字段
warning frontmatter name ≠ 目录名、缺少 version、description 过短

sm status

全景查看全局 + 所有注册项目的安装状态。

sm sync

验证所有安装位置的 manifest 文件完整性（检查 manifest 里追踪的文件是否都存在）。若发现 manifest 条目有但目录已丢失，sm install 时会自动清除 stale 条目并重装（自愈）。

生命周期管理

sm open <skill>

sm open lua-analyze    # 在 $EDITOR 打开 SKILL.md

sm cp <source> <new-name>

复制一个 skill 作为新起点，自动更新 frontmatter 中的 name 字段。

sm rename <old> <new>

重命名 skill，自动同步更新：library 目录名、frontmatter name、所有安装位置（全局 + 注册项目）、所有 profile 引用。

sm deprecate <skill> [on|off] [replaced-by]

sm deprecate figma-to-unity-old on figma-to-unity   # 废弃并指明替代品
sm deprecate figma-to-unity-old off                 # 取消废弃

部署管理

sm install skill|cmd <name> [dir | -g]

# 项目级（默认当前目录）
sm install skill lua-analyze                        # → .claude/skills/  自动触发
sm install skill lua-analyze ~/Documents/GameProject
sm install cmd   init-git                           # → .claude/commands/ 斜杠命令

# 全局（所有项目）
sm install skill skill-manager -g                  # → ~/.claude/skills/
sm install cmd   init-git -g                       # → ~/.claude/commands/

自动注册项目（无需单独 sm register）。

sm remove skill|cmd <name> [dir | -g]

sm remove skill lua-analyze                        # 移除项目 skill
sm remove skill lua-analyze ~/Documents/GameProject
sm remove cmd   init-git                           # 移除项目斜杠命令
sm remove skill skill-manager -g                   # 移除全局 skill
sm remove cmd   init-git -g                        # 移除全局斜杠命令

只删除 manifest 追踪的文件，skill 生成的其他文件（output/、cache/ 等）保留不动。

sm where <skill>

查看某个 skill 被安装在哪些位置（全局 + 所有注册项目的 skills/ 和 commands/）。

项目初始化

sm init [dir]

新项目一键初始化（最常用命令）。重复执行是幂等的。

sm default [show|set|add|remove|clear]

管理 sm init 时自动安装的默认 skill 列表：

sm default                              # 查看当前列表
sm default set lua-analyze lua-debug    # 替换整个列表
sm default add lua-analyze              # 追加
sm default remove lua-debug             # 移除
sm default clear                        # 清空

项目追踪

sm install 时会自动注册项目，手动注册只用于已有的旧项目：

sm register ~/Documents/GameProject    # 注册
sm unregister ~/Documents/OldProject   # 取消注册

注册后 sm status、sm where、sm sync、sm update 都会覆盖到这些项目。

Profile 技能包

一组 skill 的命名集合，用于一键配置新项目：

sm profile list                                  # 列出所有 profile
sm profile install my-profile                     # 安装到当前项目
sm profile install my-profile ~/Documents/Proj    # 安装到指定项目
sm profile create backend lua-analyze bug-reporter refactor   # 创建新 profile

版本管理

sm update [skill]    # 拉取远程（如有 source）+ 推送到所有安装位置
sm log <skill>       # 查看 git 提交历史
sm rollback <skill>  # 交互式恢复历史版本（恢复到 library，需再 sm update 推送）

SKILL.md 规范

---
name: my-skill              # 必填 — 须与 library 目录名一致
description: "..."          # 必填 — sm list 显示；Claude 根据此判断何时触发
version: 1.2.0              # 推荐 — 语义化版本
source: https://github.com/user/repo/tree/main/skills/my-skill
                            # 可选 — 填写后 sm update 可自动拉取最新版
author: tal                 # 可选
allowed-tools: Read Grep Write Bash   # 可选 — 限制 skill 可使用的工具
deprecated: true            # 可选 — sm deprecate 自动写入
replaced-by: new-skill      # 可选 — 配合 deprecated 指明替代品
---

运行时文件的存储规则： skill 执行时产生的数据文件（索引、缓存等）应写入项目目录（如 .claude/lua-skills/），不应写入 skill 自身目录，否则 sm update 时会被视为需要保留的本地修改。

目录结构

LocalSkillManager/
├── sm                      # CLI 工具（bash 3.2+，零额外依赖）
├── .gitignore              # 排除 .registry、SKILL.md.bak、__pycache__
├── CLAUDE.md               # Claude Code 在此项目内的上下文
├── README.md               # 本文档
├── INSTALL.md              # 新电脑安装指南
│
├── library/                # 所有 skill 的唯一来源
│   └── <skill-name>/
│       ├── SKILL.md        # skill 正文 + frontmatter（必须）
│       ├── SKILL.md.bak    # sm update 时自动备份（被 .gitignore 排除）
│       ├── references/     # 可选：skill 运行时只读的参考资料
│       └── scripts/        # 可选：skill 调用的辅助脚本
│
├── profiles/               # 命名技能包（JSON）
│   └── default.json        # sm init 时自动安装的默认列表
│
├── skill-manager/          # 对话式管理 skill
│   └── SKILL.md
│
└── .registry               # 注册的项目路径（本地生成，不纳入 git）

注意事项

sm remove 只删 manifest 追踪的文件 skill 运行时生成的文件（output/、cache/ 等）不在 manifest 里，sm remove 不会碰它们。

sm update 会覆盖本地修改 如果你在项目里直接修改了某个 skill 文件，sm update 时会警告并覆盖。如果需要定制，建议 sm cp 出一个新 skill 再改。

sm add / sm import-scan 是复制 导入到 library 后修改 library 里的文件，不影响原始路径。

sm adopt 会删除原文件 接管完成后原路径的文件会被删除，由 sm install 重建的 manifest 副本取代。skill 生成的 output/、cache/ 等额外目录不在 manifest 范围内，sm adopt 不会删除它们，但执行前请确认清楚。

版本管理依赖 git sm log 和 sm rollback 需要 LocalSkillManager 是 git repo 且有提交历史。

.registry 不纳入 git 内含本机绝对路径，不适合共享。团队协作时各自维护自己的 .registry。

About

Claude Code skill 包管理器 - 集中管理 + 包管理器风格部署

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages