# skillmgr

一个用于管理和分发 LLM 编程助手命令和技能的 CLI 工具。

## 功能特性

- 从 git 仓库拉取 skills 和 commands
- 支持多平台部署（Claude Code、OpenCode）
- 支持全局安装和项目级安装
- 事务性安装，避免安装失败导致的文件污染
- 完整的安装追踪和管理

## 安装

```bash
# 从源码构建
git clone https://github.com/your/skills.git
cd skills/manager
make build

# 将可执行文件添加到 PATH
cp bin/skillmgr /usr/local/bin/
```

## 快速开始

```bash
# 添加仓库
skillmgr add https://github.com/your/skills-repo.git --name my-skills

# 同步仓库内容
skillmgr sync

# 搜索可用的 skills 和 commands
skillmgr search

# 安装 skill 到 Claude Code（全局）
skillmgr install skill my-skill --platform claude --global

# 安装 command 到 OpenCode（项目级）
skillmgr install command my-cmd --platform opencode
```

## 命令参考

### 仓库管理

```bash
# 添加仓库
skillmgr add <url> --name <name> [--branch <branch>]

# 移除仓库
skillmgr remove <name>

# 列出仓库
skillmgr repos

# 同步仓库（拉取最新）
skillmgr sync [name]
```

### 安装管理

```bash
# 安装
skillmgr install <skill|command> <name> --platform <claude|opencode> [--global]

# 卸载
skillmgr uninstall <skill|command> <name> --platform <claude|opencode> [--global]

# 更新
skillmgr update <skill|command> <name> --platform <claude|opencode> [--global]
skillmgr update --all

# 列出已安装
skillmgr list [--type <skill|command>] [--platform <claude|opencode>] [--global]

# 搜索可用项
skillmgr search [keyword] [--type <skill|command>] [--repo <name>]

# 清理孤立记录
skillmgr clean [--dry-run]
```

## 平台适配

### Claude Code

- Skills 安装到 `~/.claude/skills/<skill-name>/` (全局) 或 `./.claude/skills/<skill-name>/` (项目)
- Commands 安装到 `~/.claude/commands/<cmd-name>/` (全局) 或 `./.claude/commands/<cmd-name>/` (项目)
- 保持原始目录结构

### OpenCode

- Skills 全局安装到 `~/.config/opencode/skills/<skill-name>/`，项目级安装到 `./.opencode/skills/<skill-name>/`
- Commands 全局安装到 `~/.config/opencode/commands/`，项目级安装到 `./.opencode/commands/`
- Command 文件名扁平化：`<group>-<action>.md`
- 例如：`commands/lyxy-kb/init.md` → `~/.config/opencode/commands/lyxy-kb-init.md`

## 配置文件

### 仓库配置

位置：`~/.skillmgr/repository.json`

```json
{
  "repositories": [
    {
      "name": "my-skills",
      "url": "https://github.com/user/skills.git",
      "branch": "main",
      "added_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```

### 安装记录

位置：`~/.skillmgr/install.json`

```json
{
  "installations": [
    {
      "type": "skill",
      "name": "my-skill",
      "source_repo": "my-skills",
      "platform": "claude",
      "scope": "global",
      "install_path": "/Users/xxx/.claude/skills/my-skill",
      "installed_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```

## 仓库结构

skillmgr 期望源仓库具有以下结构：

```
your-skills-repo/
├── skills/
│   ├── skill-a/
│   │   ├── SKILL.md     # 必需：skill 定义文件
│   │   └── ...          # 其他支持文件
│   └── skill-b/
│       └── SKILL.md
└── commands/
    ├── cmd-group-a/
    │   ├── init.md
    │   └── run.md
    └── cmd-group-b/
        └── action.md
```

## 测试

```bash
# 运行所有测试
make test

# 运行单元测试
make test-unit

# 生成覆盖率报告
make test-coverage

# 使用沙盒环境手动测试
make sandbox
```

### 测试环境变量

- `SKILLMGR_TEST_ROOT`: 覆盖配置目录（`~/.skillmgr`）
- `SKILLMGR_TEST_BASE`: 覆盖安装基础目录（用户主目录或当前目录）

## 故障排除

### 常见问题

1. **Git clone 失败**
   - 检查网络连接
   - 确认仓库 URL 正确
   - 对于私有仓库，确保已配置 SSH 密钥或 token

2. **找不到 skill/command**
   - 运行 `skillmgr sync` 更新本地缓存
   - 使用 `skillmgr search` 查看可用项

3. **安装冲突**
   - 已安装的项会提示覆盖确认
   - 使用 `skillmgr uninstall` 先卸载

4. **孤立记录**
   - 当文件被手动删除时，使用 `skillmgr clean` 清理记录

## 开发

```bash
# 依赖
make deps

# 构建
make build

# 代码格式化
make fmt

# 代码检查
make lint
```

## License

MIT