Skip to content

cli-reference.md

Latest commit

 

History

History
261 lines (185 loc) · 5.81 KB

cli-reference.md

File metadata and controls

261 lines (185 loc) · 5.81 KB
Raw

Skillman CLI 详细设计 (v2.2)

目标对齐：安装 / 发布 / 更新闭环；跨项目快速构建只走 profile

1. 全局约定

  • 通用参数：--json、--verbose、--quiet
  • 退出码：0=成功、1=业务错误、2=参数错误、3=系统错误
  • config.json.agents 只负责安装时路径声明与运行时归类

2. 命令总览

skillman
├── market
│   ├── add <uri>
│   ├── remove <name>
│   ├── list
│   └── update [name]
│
├── skill
│   ├── search <keyword>
│   ├── install <market>:<skill>
│   ├── uninstall <skill_name>
│   ├── list
│   └── sync
│
├── archive [skill_path]
│
├── worktree
│   ├── list
│   └── discard <market>:<skill>
│
├── profile
│   ├── snapshot
│   ├── apply
│   ├── list
│   └── delete <name>
│
└── project
    ├── add <path>
    ├── remove <name>
    └── list

3. Market 命令组

3.1 skillman market add

与 v2 一致。

3.2 skillman market remove

skillman market remove <name> [--clean] [--no-agent-uninstall] [--json]

默认行为：

  • 删除 link 安装目标与记录
  • 处理 copy 时进入交互
  • 按最新 config.json.agents 路径归类并执行 agent 卸载
  • 匹配失败归到 unmatched，仅提示不执行卸载

copy 交互（CLI）

当检测到该 market 下存在 copy 技能，提示：

检测到非 link 技能，选择处理方式：
[1] 全部保留
[2] 全部不保留
[3] 保留指定 skill

若选 [3]，再展开具体 skill 多选。

API 参数映射（CLI 会显示）

CLI 在确认后展示等价 API 参数：

  • 选 [1] 全部保留 → discard_all=false
  • 选 [2] 全部不保留 → discard_all=true, discard_ignore=
  • 选 [3] 保留指定 → discard_all=true, discard_ignore=skill1,skill2

示例输出：

API 参数等价：discard_all=true discard_ignore=http-retry,grpc-retry

3.3 skillman market update

skillman market update [name] [--json]

规则：

  1. git market 执行 pull + PR 状态检查。
  2. fs market no-op（显示 skipped）。
  3. merged PR 场景：
    • project_hash == worktree_hash：自动同步到 market 最新。
    • 否则：不覆盖本地文件，提示后续动作。

冲突后覆盖可执行：

skillman skill sync --market skill-market --skill http-retry --install-path /repo/foo/.claude/skills/http-retry --force

4. Skill 命令组

4.1 skillman skill search

与 v2 一致。

4.2 skillman skill install

skillman skill install <market>:<skill> [--agent <agent>]... [--mode copy|link] [--force] [--json]

规则：

  • --agent 可重复，一次安装到多个路径。
  • 不传 --agent：使用 settings.defaults.default_agents；为空时交互选择。
  • 每个 agent 产生一条安装记录（主键仍按 install_path 区分）。

4.3 skillman skill uninstall

skillman skill uninstall <skill_name> [--agent <agent>]... [--install-root <path>]... [--json]

规则：

  • 不传过滤条件：卸载当前项目该 skill 的全部安装记录。
  • --agent 按当前配置映射到 install_root 过滤。

4.4 skillman skill list

skillman skill list [--market <name>] [--agent <agent|unmatched>] [--json]

输出列建议：

  • MARKET / SKILL / INSTALL_ROOT / INSTALL_PATH / AGENT_BUCKET / MODE / SOURCE / VERSION

说明：AGENT_BUCKET 为运行时按路径归类结果，不是持久化字段。

4.5 skillman skill sync

skillman skill sync [--market <market>] [--skill <name>] [--install-path <path>] [--force] [--json]

规则：

  • 默认跳过 source_type=worktree 记录。
  • 处理 merged 后冲突时使用 --force + 精确 --install-path。

5. Archive 命令组

5.1 交互式 archive

skillman archive [--market <name>] [--json]

5.2 指定式 archive

skillman archive <skill_path> --market <name> [--dest <skill_name>] [--overwrite] [--json]

语义：

  • 仅 copy 技能可归档。
  • git market 走 worktree + PR。
  • 归档后发起项目记录切到 source_type=worktree（git）。

6. Worktree 命令组

6.1 skillman worktree list

skillman worktree list [--market <name>] [--json]

6.2 skillman worktree discard

skillman worktree discard <market>:<skill_name> [--sync] [--json]

默认：

  • 清理 worktree 与分支
  • market 有 skill：切回 market source，默认保留本地文件
  • market 无 skill：删记录，保留本地文件

7. Profile 命令组

7.1 skillman profile snapshot

  • 快照结构按 relative_path 分组：items[].skills[]
  • 每个 skill 保留：market/skill_name/mode/source_type

7.2 skillman profile apply

skillman profile apply --name <profile> [--force] [--json]

规则：

  • project_root 可从 projects.txt + cwd 自动解析。
  • install_root = project_root + relative_path。
  • source_type=worktree 缺失时回退 market；都缺失则跳过并警告。

7.3 skillman profile list / delete

与 v2 一致。

8. 典型流程

8.1 多 agent 安装

cd /repo/my-app
skillman skill install skill-market:http-retry --agent codex --agent claude
skillman skill list

8.2 修改并归档

skillman skill install skill-market:http-retry --agent codex --mode copy --force
vim .codex/skills/http-retry/SKILL.md
skillman archive .codex/skills/http-retry --market skill-market --overwrite
skillman market update

8.3 移除 market（含 copy 交互）

skillman market remove skill-market --clean

输出重点：

  • link 删除统计
  • copy 保留/删除统计
  • codex/claude/gemini/其他/unmatched 分组处理结果