Skill/openspec/changes/archive/2026-02-25-build-skillmgr-cli/proposal.md

Why

当前手动管理和分发 AI 编程平台的 skills/commands 存在诸多问题：需要手动理解不同平台（Claude Code、OpenCode）的目录结构差异、手动复制文件、手动处理命名转换（如 OpenCode 的扁平化命名），且难以追踪已安装的内容和版本。随着 skills 数量增长和多平台支持需求，这种手动流程变得不可维护。需要一个自动化的管理工具来简化从源仓库到目标平台的完整流程。

What Changes

• 新增：创建独立的 Go CLI 工具（skillmgr），提供命令行界面管理 skills/commands 的完整生命周期
• 新增：支持从 git 仓库拉取和缓存 skills/commands 源代码
• 新增：内置 Claude Code 和 OpenCode 两个平台的适配规则
• 新增：支持全局安装（/.claude/、/.opencode/）和项目级安装（./.claude/、./.opencode/）
• 新增：安装记录追踪系统，支持更新、卸载、清理孤立记录
• 新增：事务性安装机制，通过 tmp staging 避免部分失败导致的不一致状态
• 新增：用户交互确认（目录覆盖、冲突解决）

Capabilities

New Capabilities

• repository-management：管理源仓库配置（添加、移除、同步 git 仓库）
• skill-installation：安装 skills 到目标平台（支持全局/项目作用域）
• command-installation：安装 commands 到目标平台（处理命令组和平台特定命名）
• platform-adaptation：适配不同 AI 编程平台的目录结构和命名规则
• install-tracking：跟踪和管理安装记录（查询、更新、清理）
• transactional-install：事务性文件安装（staging → commit → rollback）
• test-infrastructure：测试环境隔离和自动化（零污染测试、fixture 管理、CI 集成）

Modified Capabilities

（无现有能力需要修改）

Impact

• 新增项目：在 manager/ 目录下创建独立的 Go 项目（不影响现有 skills 仓库结构）
• 用户配置：在用户目录创建 ~/.skillmgr/ 配置目录（repository.json、install.json、cache/）
• 目标平台：修改目标平台的 .claude/ 和 .opencode/ 目录（根据用户操作）
• 依赖：需要 Git 客户端（用于 clone/pull 操作）
• 兼容性：工具设计为独立运行，不破坏现有手动管理的 skills/commands