@dayinxisheng/skillctl

Claude Skills 管理工具 - 轻松管理你的 Claude Skills

管理 Claude Skills 的激活状态和项目归档，通过软链接实现 skills 的灵活切换。

📦 安装

npm install -g @dayinxisheng/skillctl

更新

npm update -g @dayinxisheng/skillctl

安装完成后，可以在任何目录使用 skillctl 命令。

🚀 快速开始

第一步：设置仓库路径

告诉 skillctl 你的 skills 仓库在哪里（存储所有 skill 文件的目录）：

skillctl config set-repo ~/my-skills

第二步：查看可用的 skills

skillctl ls-all

输出示例：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  项目中所有可用的 Skills
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Name                    Description
─────────────────────────────────────────────────────────────
brainstorming           Turn ideas into validated designs...
frontend-design         Generate frontend code from UI...
pdf-tools               PDF manipulation tools...

ℹ 共找到 3 个 skills
  位置: ~/my-skills

第三步：激活 skill

skillctl activate brainstorming

输出：

✓ 已激活: brainstorming (user)

📚 核心概念

User vs Project 两级作用域

skillctl 支持两个作用域：

| 作用域 | 路径 | 说明 | |--------|------|------| | User | ~/.claude/skills/ | 全局可用，所有项目共享 | | Project | ./.claude/skills/ | 仅当前项目可用 |

示例场景：

• 团队共享的技能 → 用 Project 级别
• 个人常用技能 → 用 User 级别

🎯 常用命令

1. 激活 Skill

# 激活到 user 级别（默认）- 全局可用
skillctl activate brainstorming

# 激活到 project 级别 - 仅当前项目
skillctl activate -p brainstorming

# 批量激活所有 skills
skillctl activate --all
skillctl activate -u --all  # 明确指定 user 级别
skillctl activate -p --all  # 明确指定 project 级别

2. 停用 Skill

# 停用 user 级别的 skill
skillctl deactivate brainstorming

# 停用 project 级别的 skill
skillctl deactivate -p brainstorming

# 批量停用所有
skillctl deactivate --all

3. 查看状态

# 查看所有 skills 的激活状态（表格形式）
skillctl status

输出示例：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Skills 激活状态
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Skill                 User       Project
──────────────────────────── ────────── ───────────
brainstorming         ✓          ✗
frontend-design       ✗          ✓
pdf-tools             ✓          ✓

ℹ 共 3 个 skills
  ✓ = 已激活  ✗ = 未激活

# 只看已激活的 skills
skillctl list

输出示例：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  当前激活的 Skills
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

全局 (~/.claude/skills):
  brainstorming → ~/my-skills/brainstorming
  pdf-tools → ~/my-skills/pdf-tools
ℹ 共 2 个

本地 (./.claude/skills):
  frontend-design → ~/my-skills/frontend-design
ℹ 共 1 个

4. 导入 Skill

将外部开发的 skill 导入到你的项目仓库：

# 假设你有一个 skill 在 ~/.claude/skills/my-new-skill
# 将其导入到项目仓库
skillctl import my-new-skill

这会：

1. 将 skill 移动到你的项目仓库
2. 在原位置创建软链接

5. 拉取 Skill

从 Git 仓库（如 GitHub）拉取 skill 到本地：

# 拉取单个 skill
skillctl pull https://github.com/owner/repo path/to/skill

# 拉取多个 skills
skillctl pull https://github.com/owner/repo \
  path/to/skill1 \
  path/to/skill2

# 强制覆盖已存在的 skill（自动备份）
skillctl pull <repo-url> <path> --force

使用仓库别名：

# 添加别名
skillctl config add-repo anthropic https://github.com/anthropics/anthropic-quickstarts

# 使用别名拉取
skillctl pull anthropic typescript/search

# 查看所有别名
skillctl config show

配置镜像加速：

# 设置镜像（用于加速访问 GitHub）
skillctl config set-mirror https://ghfast.top

# 之后所有 pull 命令都会自动使用镜像
skillctl pull https://github.com/owner/repo path/to/skill

# 取消镜像设置
skillctl config unset-mirror

特性：

• 支持从 GitHub 仓库提取指定目录作为 skill
• 严格验证 SKILL.md 文件及 name 字段
• 下载进度显示
• 跨平台支持（Linux/macOS 使用 tar.gz，Windows 使用 zip）
• 支持仓库别名，简化常用仓库的拉取
• 支持镜像加速配置

6. 定位 Skill

查找 skill 的实际存储位置：

skillctl locate brainstorming

输出示例：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Skill 定位: brainstorming
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  全局: ~/.claude/skills/brainstorming → ~/my-skills/brainstorming (软链接)

⚙️ 配置管理

# 查看所有配置
skillctl config
# 或
skillctl config show

输出示例：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  配置信息
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

配置文件: ~/.config/skillctl/config.json

仓库路径: ~/my-skills
镜像加速: https://ghfast.top

仓库别名:
  anthropic    → https://github.com/anthropics/anthropic-quickstarts
  my-skills    → https://github.com/dayinxisheng/skills

# 设置仓库路径
skillctl config set-repo /new/path/to/skills

# 添加仓库别名
skillctl config add-repo <别名名称> <仓库URL>

# 删除仓库别名
skillctl config remove-repo <别名名称>

# 设置镜像加速
skillctl config set-mirror https://ghfast.top

# 取消镜像设置
skillctl config unset-mirror

💡 实用场景

场景 1：新项目设置

# 1. 进入项目目录
cd ~/my-project

# 2. 激活项目需要的 skills
skillctl activate -p frontend-design
skillctl activate -p brainstorming

# 3. 验证
skillctl list

场景 2：切换技能集

# 停用当前所有 skills
skillctl deactivate --all

# 激活新的技能集
skillctl activate pdf-tools
skillctl activate docx-tools

场景 3：分享你的 skill

# 1. 导入你的 skill 到项目仓库
skillctl import my-awesome-skill

# 2. 提交到 git
cd ~/my-skills
git add skills/my-awesome-skill
git commit -m "Add my-awesome-skill"
git push

🛠️ 开发

# 克隆项目
git clone <repo-url>
cd skillctl

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建
npm run build

# 本地测试
npm link

# 运行测试
npm test

# 代码检查
npm run lint
npm run lint:fix

📁 项目结构

src/
├── index.ts           # CLI 入口
├── commands/          # 命令处理器
│   ├── activate.ts    # 激活命令
│   ├── deactivate.ts  # 停用命令
│   ├── import.ts      # 导入命令
│   ├── pull.ts        # 拉取命令
│   ├── locate.ts      # 定位命令
│   ├── status.ts      # 状态命令
│   ├── list.ts        # 列表命令
│   ├── all-list.ts    # 全部列表命令
│   ├── set-repo.ts    # 设置仓库命令
│   └── config.ts      # 配置命令
├── lib/              # 核心业务逻辑
│   ├── config-manager.ts  # 配置管理
│   ├── link-handler.ts    # 软链接处理
│   ├── pull-handler.ts    # 拉取处理逻辑
│   └── skill-manager.ts   # Skill 管理
├── utils/            # 工具函数
│   ├── output.ts      # 彩色输出
│   ├── errors.ts      # 错误类型
│   ├── platform.ts    # 平台检测
│   ├── downloader.ts  # 下载工具
│   ├── archive-extractor.ts  # 解压工具
│   ├── skill-validator.ts    # Skill 验证
│   ├── github-parser.ts      # GitHub URL 解析
│   └── url-validator.ts      # URL 验证
└── types/            # TypeScript 类型定义
    └── index.ts

📄 许可证

MIT License © 2026 hrjlab

📝 变更日志

查看 CHANGELOG.md 了解版本更新历史。

🔗 相关链接

• npm 包
• 问题反馈