skill-flow

v1.6.10

Published

6 days ago

Workflow-first management for AI agent skills. Group, project, and sync skills across multiple agents with explicit state tracking.

Downloads

301

0High
0Medium
0Low

vintonlin

ai agent skills workflow claude cursor copilot cli management git

Skill Flow

将散落的 AI agent skill 整合为有序工作流。

English · 日本語

在所有主流编码 agent 中安装、管理和共享 skill —— Claude Code、Cursor、Grok Build、Copilot、Kimi Code、WorkBuddy、CodeBuddy、ZCode 等。

从 skills.sh、GitHub 或本地来源搜索并导入 skill。一次部署到多个 agent。保持一切井然有序且及时更新。

Skill Flow 桌面总览

为什么要做这个

逐个安装 skill 在规模化后会崩溃：

仓库包含多个相关 skill，但你分别安装它们
不同 agent 期望不同的位置
更新会悄悄漂移
未管理的目录不断累积
没人追踪实际部署了什么

skill-flow 保留了工作流分组。一个 source 始终是一个内聚单元——检查它、选择 skill、部署到多个目标、干净地更新，并始终了解你的状态。

当前能力

分组化 source 管理：本地、Git、skills.sh 统一走同一套导入模型。
多 agent 部署：把同一组选中的 skill 部署到 Claude Code、Codex、Cursor、Grok Build、Gemini CLI、OpenCode、OpenClaw、Hermes Agent、MiniMax Code、Kimi Code、WorkBuddy、CodeBuddy、Trae、Trae CN、Windsurf、ZCode 等目标。
交互式配置流程：基于 Ink 的 add/config/find TUI，覆盖选择、审阅和修复流程。
macOS 15+ 桌面应用：SwiftUI 主窗口、导入页、详情页、设置页和菜单栏快速配置。
安全退出桌面端：按下 Command-Q 时会取消正在运行的托管更新/导入，恢复未完成的组，并在下次启动继续前先处理遗留恢复。
显式状态：manifest.json 记录意图，lock.json 记录实际 inventory 与 deployment。
Bridge 协议：通过 skill-flow bridge --json 提供机器可读入口。
修复与诊断：doctor、repair-source、repair-state、repair-targets 负责处理最容易坏掉的地方。

界面预览

| 使用情况视图 | 导入页 | | --- | --- | | | |

| 详情页 | 设置页 | | --- | --- | | | |

| 菜单栏 | | --- | | |

快速开始

安装

npm install -g skill-flow
skill-flow --help

也可以不全局安装，直接运行：

npx skill-flow --help

桌面端前置依赖

Skill Flow Desktop release 构建会内置用于 desktop helper 和 skills.sh 导入的原生 Node.js/npm/npx 工具链，因此双击启动不再依赖 asdf 或 nvm 写入 shell 的 Node 路径。

导入非 GitHub Git source 需要 git

开发构建和损坏的 release bundle 仍会 fallback 到系统 Node.js 20 或更高版本及 npm/npx。如果桌面应用检测到依赖缺失，会直接提示可执行的错误信息，并引导回本节处理。

常见使用流程

# 添加一个 source
skill-flow add garrytan/gstack

# 查看当前 workflow group 及其 ID
skill-flow list
skill-flow list --ids

# 打开交互式配置 UI
skill-flow config

# 搜索本地技能、内置目录和 skills.sh
skill-flow find browser

# 更新单个 source 或全部 source
skill-flow update garrytan-gstack
skill-flow update --all

# 诊断漂移和坏掉的部署
skill-flow doctor

首次使用模型

这些命令的职责不同：

add 安装或登记新的 source，并选择要使用的 skill 与目标。
list 查看已登记的 workflow group，以及管理命令会使用的稳定 ID。
config 配置已有 group；它不是安装新 source 的入口。
find 帮助查找可安装的 skill 和 source。

如果 skill-flow config 打开后没有任何 group，请先运行 skill-flow add <source>。

术语分成几个层次：

source locator：你提供的来源地址，例如 mattpocock/skills。
source ID：登记后用于命令和状态关联的稳定标识。
display name：列表和配置界面中显示的可读名称。
skill group：作为一个单位被选择和部署的一组 skill。

命令要求 sourceId 时，请使用 skill-flow list --ids 显示的 ID。

机器桥接入口

桌面端和辅助工具通过版本化 JSON 协议调用 CLI：

printf '%s' '{"protocolVersion":"1.0","command":"list"}' | skill-flow bridge --json

支持的来源

skill-flow add <source> 目前支持：

本地目录
owner/repo GitHub 简写
完整 HTTPS Git URL
SSH Git URL
GitHub tree URL
clawhub:<slug>[@version]

示例：

skill-flow add ~/code/my-skills
skill-flow add garrytan/gstack
skill-flow add https://github.com/garrytan/gstack.git
skill-flow add [email protected]:garrytan/gstack.git
skill-flow add https://github.com/garrytan/gstack/tree/main/skills
skill-flow add clawhub:example/skill-pack
skill-flow add clawhub:example/[email protected]

如果仓库很大，但默认只想从某个子目录开始预选，可以加 --path <repoSubpath>。

支持的目标 Agent

当前内置目标（32 个）：

Claude Code
Codex
Cursor
Grok Build
GitHub Copilot
Gemini CLI
OpenCode
OpenClaw
Hermes Agent
MiniMax Code
Kimi Code
WorkBuddy
CodeBuddy
Pi
Trae
Trae CN
Windsurf
Roo Code
Cline
Amp
Kiro
ZCode
DeepSeek Harness
Antigravity
Junie
Mistral Vibe
OpenHands
Qoder
Qwen Code
Zencoder
Kilo Code
Goose

目标路径可以通过 SKILL_FLOW_TARGET_* 环境变量覆盖。

命令总览

| 命令 | 作用 | | --- | --- | | add <source> | 导入 source，并选择 skill 与目标 | | list | 查看 workflow group 和当前健康状态 | | list --ids --warnings | 显示 source ID 与 warning 详情，便于迁移和排查 | | enable <sourceIds...> --targets <ids> --all-skills | 为已注册 group 开启目标；--all-skills 会先填充空的 skill 选择 | | disable <sourceIds...> | 不卸载 group，只关闭目标 | | only <sourceIds...> --targets <ids> --all-skills | 只保留指定 group 开启；--all-skills 会先填充空的 skill 选择 | | import-manifest <file> | 批量导入 source manifest；带 targets 的 JSON 条目必须设置 skills: "all" | | find <query> / search <query> | 搜索本地技能、内置 Git 目录与 skills.sh | | config | 配置已登记 group 的 skill 和目标；不会安装新的 source | | update [sourceId] --all | 更新单个或全部已注册 source | | adopt <paths...> --name <name> | 登记由其他安装器管理的已有 skill，不复制也不部署 | | external status [sourceId] | 刷新外部 source，并比较已配置的版本 | | external update <sourceId> --confirm-external-update | 运行明确配置的外部更新器 | | remove <sourceIds...> | 取消登记 group；外部文件保持不动 | | doctor | 诊断漂移、缺失路径和投影问题 | | migrate-state --to v2 [--dry-run] | 检查或迁移本地状态目录到 schema v2 | | repair-source [sourceId] --all | 修复 source checkout 元数据 | | repair-state [sourceId] --all | 重建 source 侧状态 | | repair-targets [sourceId] --all | 修复目标部署内容 | | uninstall <sourceIds...> | 移除 group 及其部署 | | bridge --json | 执行机器协议请求 |

外部托管 group 仅用于观察：不能配置目标、不能由常规 update 更新，也不能由修复流程接管。

状态如何组织

skill-flow 默认把状态放在 ~/.skillflow/：

manifest.json：你想要什么
lock.json：系统实际装成了什么
source/local/*：由 Skill Flow 管理的本地 source 缓存
source/git/*：Git source 缓存
source/clawhub/*：skills.sh source 缓存
catalog/git/*：内置 Git catalog 缓存

目标目录只是部署结果，不是真正的事实源。

状态 schema 迁移

迁移前先 dry-run：

skill-flow migrate-state --to v2 --dry-run
skill-flow migrate-state --to v2
SKILL_FLOW_STATE_ROOT=/custom/path skill-flow migrate-state --to v2

默认状态目录是 ~/.skillflow/。正常迁移会创建 <stateRoot>.backup-YYYYMMDD-HHMMSS 备份，重写权威状态文件，并清理 catalog/ 下可重建的 cache；cache 会在后续 CLI 或桌面读取时重建。目标目录不是权威来源，不要用目标目录反推状态。迁移后如果目标目录看起来过期，运行 skill-flow repair-targets --all。

回滚时先停止 Skill Flow，把备份状态目录移回原位置，再运行 skill-flow migrate-state --to v2 --dry-run 或通过桌面迁移状态检查确认后重新迁移。

Monorepo 结构

apps/cli：对外发布的 npm CLI 包
apps/desktop-mac：macOS 15+ SwiftUI 桌面应用
packages/domain：领域模型和核心类型
packages/storage：manifest/lock/preferences/cache 持久化
packages/integration：Git、GitHub、skills.sh、路径与命名集成
packages/core-engine：inventory、deployment、doctor、bootstrap 等服务
packages/query：共享运行时与 bridge 编排
packages/shared-types：bridge 协议类型
packages/tui：Ink add/find/config UI
docs：架构、贡献指南、参考资料、计划与打包文档

开发

npm install
npm run build
npm test

CLI 开发调试：

npm run -w skill-flow dev -- --help

桌面端开发调试：

npm run build
cd apps/desktop-mac
swift build
swift test

让桌面端使用本地 CLI 构建产物：

export SKILL_FLOW_DESKTOP_HELPER_OVERRIDE=/absolute/path/to/apps/cli/dist/cli.js

无 Apple Developer 证书时的 macOS 安装说明：

Apple Silicon Mac 可使用 Skill-Flow-arm64.dmg 或 Skill-Flow-universal.dmg。
Intel Mac 可使用 Skill-Flow-x86_64.dmg 或 Skill-Flow-universal.dmg。
将 Skill Flow.app 复制到“应用程序”后，如果 Gatekeeper 阻止首次启动，请在 Finder 中右键并选择“打开”。
如果 macOS 仍将应用标记为已隔离，请运行：

sudo xattr -dr com.apple.quarantine "/Applications/Skill Flow.app"

每种发布架构在各版本间保持稳定的 Bundle ID 和 designated requirement，因此已授权安装被同架构新版本替换后，通常无需再次执行 sudo xattr。

文档入口

许可证

Apache License 2.0。见 LICENSE。