Skill Suitcase

技能简介

Skill Suitcase 是一款面向 AI 编程 Agent 的技能包管理器，核心理念是「一份审核过的技能目录，覆盖所有主流 Agent 运行时」。传统方案中，Claude、Codex、OpenClaw、Hermes 等 Agent 各自维护独立的技能目录，同一个技能需要反复复制到不同平台，容易出现版本漂移、无法追溯安装来源的问题。Skill Suitcase 通过一个 Git 目录作为唯一的真实来源，配合事务性安装、锁文件、收据机制，实现了跨平台的技能分发与一致性保障。

核心能力

1. Git 目录驱动：所有技能来源、变体、分配策略和上游元数据均存储在 Git 目录中，Agent 运行时目录永远不被视为真实来源。
2. 多运行时支持：内置支持 OpenClaw、Codex、Claude（Code）、Hermes、OpenCode、Pi、Grok 等主流 Agent，覆盖业界主流产品。
3. 只读命令优先：plan、diff、status、validate 等命令在执行任何变更前先展示 JSON 结果，用户确认后再执行写操作。
4. 事务性安装：apply 命令具有原子性，支持 Plan Lock 模式和 Artifact 模式，拒绝无管理的目标目录。
5. 收据与回滚：每次安装均生成收据（Receipt），记录技能来源、目标路径、安装模式、文件哈希等，支持 rollback、repair、prune 等恢复操作。
6. 质量验证：内置 validate 命令对 SKILL.md 结构、必填字段进行校验，支持 strict 模式。
7. 跨平台打包：pack 命令可将技能打包为特定 Agent 的格式，写入指定输出目录，全程不影响真实运行时目录。

安装配置

环境要求：Node.js 20 及以上版本

# 通过 npm 全局安装
npm install --global skill-suitcase

# 通过 Homebrew 安装（macOS/Linux）
brew tap pandemonium-research/skilldex
brew install skilldex-cli

# 通过 curl 安装（macOS/Linux）
curl -fsSL https://skilldex-web.vercel.app/install.sh | sh

# 通过 Scoop 安装（Windows）
scoop bucket add skilldex https://github.com/Pandemonium-Research/scoop-skilldex
scoop install skilldex-cli

使用步骤

1. 安装 CLI：选择上述任意一种方式完成安装后，运行 skill-suitcase --version 验证安装成功。
2. 设置技能目录：将包含 skill-suitcase.yaml 和 skills 目录的 Git 仓库克隆到本地，例如 git clone https://github.com/your-org/skills-catalog.git ~/skills-catalog。
3. 执行只读审计：运行 skill-suitcase import --source ~/skills-catalog --json 导入目录，再运行 skill-suitcase validate --source ~/skills-catalog --strict --json 验证结构完整性。
4. 规划安装：运行 skill-suitcase plan --source ~/skills-catalog --target claude --json 查看针对目标 Agent 的安装计划。
5. 正式安装：确认计划无误后，运行 skill-suitcase apply --source ~/skills-catalog --target claude --apply 执行事务性安装，CLI 会为每个技能生成收据文件。

适用场景

1. 多 Agent 团队：同一份技能库需要在 Claude Code、Codex、Cursor 等多个 Agent 中保持一致。
2. 技能质量管控：需要在安装前验证技能格式是否符合规范，避免低质量技能进入生产环境。
3. 技能版本追溯：当某个技能发生变更时，需要精确知道哪些运行时受到影响、影响的版本是什么。
4. CI/CD 集成：在持续集成流水线中，使用 skill-suitcase check --frozen 确保技能锁文件是最新的。
5. 跨平台迁移：将现有 Claude Code 技能迁移到 OpenClaw 或其他 Agent 平台。

适用人群

• 平台工程师：负责维护企业内部多 Agent 基础设施的技术负责人。
• AI 效能工程师：专注于提升 AI 编程工具链一致性和可靠性的开发者。
• 开源技能维护者：需要将技能发布到多个平台并希望统一管理发布流程的贡献者。
• 安全审计人员：需要审查技能行为、追踪网络和命令调用风险的安全团队。

工作原理

Skill Suitcase 由三部分组成：CLI 工具、Git 目录（Catalog）和运行时适配层。Catalog 是技能的真实来源，包含技能源文件、变体定义、分配规则和上游元数据，采用 YAML 格式声明式描述。CLI 工具负责解析 Catalog，对目标 Agent 的运行时目录进行建模，生成安装计划或差异报告。所有变更操作（apply、track、rollback 等）均通过收据文件（Receipt）记录，每次变更前必须先有 Plan Lock 或 Artifact 作为审批边界，确保没有未经过审查的变更直接写入运行时目录。

官方链接

• npm 页面：https://www.npmjs.com/package/skill-suitcase
• GitHub 仓库：https://github.com/calvinnwq/skill-suitcase
• 官方文档：https://calvinnwq.github.io/skill-suitcase/
• 安装指南：https://github.com/calvinnwq/skill-suitcase/blob/main/INSTALL.md