一款专为 AI 时代开发者设计的"技能（Prompt/Script）生命周期管理工具"。它旨在解决 AI 指令碎片化、跨工具同步难、缺乏版本控制等痛点。

skill-hub 首先是一个命令行工具，用于管理 skill、在项目中启用 skill，并维护 skill 的仓库生命周期。

同时它支持以 serve 模式运行。serve 模式会托管用户本地的 ~/.skill-hub/ 目录，提供 Web 管理能力；CLI 在执行命令时会优先与本地 serve 实例交互，但 serve 不是必选项，本地服务不可用时所有命令都必须回退到本地执行。

当前除了前台直接运行：

skill-hub serve

也支持服务实例管理：

skill-hub serve register local --host 127.0.0.1 --port 6600
skill-hub serve start local
skill-hub serve status
skill-hub serve stop local
skill-hub serve remove local

服务注册信息会持久化到 ~/.skill-hub/services.json，start 会记录后台进程 pid 与日志路径，status 会显示 running / stopped / stale 三种状态。

1. 全局管理目录：~/.skill-hub/ 承接多仓库配置、本地仓库存储、默认仓库、全局状态、索引和缓存。

2. 项目本地工作区：<project>/.agents/skills/ 承接当前项目实际使用的 skill 内容，是项目侧的工作目录。

3. 来源仓库 指某个 skill 在 use 时选中的仓库。它决定 apply 的读取来源，以及 status 的上游对比基线。

4. 默认仓库 指当前配置中的默认仓库，同时也是归档仓库。feedback 只归档到默认仓库，pull / push 默认也只操作默认仓库。

5. 多仓库管理 指 ~/.skill-hub/ 下多个本地仓库的配置、启停、默认仓库切换和同步能力。

6. 服务实例 指 skill-hub serve 启动的本地服务。它托管 ~/.skill-hub/，为 Web 管理和 CLI 复用提供统一执行入口。

当前代码结构包含模块化内核与现有 CLI 实现。当前构建入口统一位于 application/skill-hub/cmd，实际命令执行仍由 internal/cli 承载，internal/modules/kernel 主要提供服务化封装与后续重构落点：

skill-hub/
├── application/skill-hub/      # 主应用入口
│   ├── cmd/                    # 推荐构建入口
│   └── docker/                 # Docker 启动定义
├── internal/modules/kernel/    # 核心模块壳层
├── internal/cli/               # CLI 命令实现
├── internal/adapter/           # 外部工具适配器
├── internal/engine/            # 技能引擎
├── internal/state/             # 状态管理
└── pkg/                        # 公共包

当前推荐构建命令：

go build -o bin/skill-hub ./application/skill-hub/cmd

• Git 为中心：所有技能存储在Git仓库中，作为单一可信源
• 多仓库架构：支持同时管理多个技能仓库（个人、社区、官方）
• 一键分发：将技能快速应用到不同的AI工具
• 闭环反馈：将项目中的手动修改反馈回技能仓库
• 现代架构：采用 Go 1.24+ 特性，遵循 Effective Go 最佳实践

• 技能管理：查看、启用、禁用技能
• 技能创建：从当前项目创建新的技能模板
• 已有技能登记：将 .agents/skills/<id>/SKILL.md 中的存量技能登记到项目状态
• 批量导入：扫描 .agents/skills/*/SKILL.md，批量登记、修复、验证并可选归档
• 重复检测与副本同步：扫描嵌套项目中的同 ID 技能副本，报告冲突，并可从 canonical 目录同步副本
• 本地验证：校验项目本地 skill 是否符合规范，并可用 --fix 修复 legacy frontmatter
• 技能归档：将验证通过的技能归档到正式仓库
• 跨工具同步：支持 Cursor、Claude Code、OpenCode 等AI工具
• 版本控制：基于Git的技能版本管理
• 差异检测：自动检测手动修改并支持反馈
• 安全操作：原子文件写入和备份机制
• 全面测试：单元测试 + 端到端测试覆盖

• 项目本地工作区命令：set-target、use、status、apply、feedback、pull、push、create、register、import、dedupe、sync-copies、lint、audit、remove、validate
• 多仓库管理命令：repo *
• 状态维护命令：prune
• 远端搜索命令：search
• 底层运维命令：git *、serve
• 引导命令：init

其中：

• create / remove 只作用于项目本地工作区，不参与服务化托管
• search 面向远端能力；当本地 serve 实例可用时优先通过服务承接远端交互，不可用时回退到本地执行
• repo * 面向 ~/.skill-hub/ 下的多仓库管理
• prune 用于清理 state.json 中因项目目录移动、删除而残留的失效项目记录
• use / status / apply / feedback / set-target / pull / push 都服务于项目工作流，但会依赖全局管理目录中的仓库与状态信息
• register / import / dedupe / sync-copies / lint --paths / validate / audit / pull / push 在本地 serve 实例可用时会优先通过服务桥接执行；涉及项目路径的命令会把路径解析为绝对路径再交给服务端，避免 serve 进程工作目录不同导致误扫或误改

使用一键安装脚本（最简单的方式）：

curl -s https://raw.githubusercontent.com/muidea/skill-hub/master/scripts/install-latest.sh | bash

安装完成后，按照以下工作流程开始使用：

项目本地 Skill 目录默认使用 .agents/skills/，target 主要用于记录和过滤兼容目标，不再要求每个命令都绑定某个具体工具的目录说明。

# 1. 初始化多仓库工作区（可指定初始仓库URL）
skill-hub init https://github.com/muidea/skill-hub-examples.git

# 2. 添加更多技能仓库（可选）
skill-hub repo add community https://github.com/community/skills.git
skill-hub repo add personal https://github.com/yourname/skills.git

# 3. 设置默认归档仓库
skill-hub repo default main

# 4. 设置项目兼容目标
skill-hub set-target open_code

# 5. 启用技能
skill-hub use git-expert

# 6. 应用技能到项目
skill-hub apply

# 1. 从当前项目创建新技能模板
skill-hub create my-new-skill

# 2. 在 feedback 前校验本地新建 skill
skill-hub validate my-new-skill

# 3. 反馈手动修改并归档到默认仓库
skill-hub feedback my-new-skill

# 批量反馈当前项目中已登记的所有技能，适合批量刷新后归档
skill-hub feedback --all --force --json

# 预览默认仓库待推送变更，输出机器可读摘要
skill-hub push --dry-run --json

# 检查默认仓库拉取动作，输出机器可读摘要
skill-hub pull --check --json

# 查看默认仓库工作区状态，输出机器可读摘要
skill-hub git status --json

# 执行底层默认仓库同步，输出机器可读摘要
skill-hub git sync --json

pull --check --json 会返回 no_remote、up_to_date、updates_available、ahead 或 divergent，并包含本地/远端提交与 ahead / behind 计数，便于自动化判断是否需要执行实际拉取。

服务 API 的默认仓库推送必须先预览再确认：GET /api/v1/skill-repository/push-preview 返回 changed_files，POST /api/v1/skill-repository/push 必须携带 confirm: true，并可携带 expected_changed_files 防止预览后文件变化仍继续推送。

Web UI 管理端的默认仓库推送入口也遵循同一约束：先点击“预览推送”取得变更列表，勾选确认后才会启用“推送默认仓库”。

服务 API 的业务错误会保留稳定错误码，例如 SKILL_NOT_FOUND、PROJECT_NOT_FOUND、VALIDATION_FAILED、INVALID_INPUT，并按错误类别映射到对应 HTTP 状态，便于 CLI bridge 和 Web UI 统一处理。

serve 默认绑定 127.0.0.1，在 loopback 监听下还会校验 Host header 必须为 loopback；显式绑定到非 loopback 地址时保留远程访问兼容行为。

# 登记已有 .agents/skills/<id>/SKILL.md，不创建或覆盖内容
skill-hub register existing-skill --target open_code

# 修复 legacy SKILL.md frontmatter（修改前自动创建 SKILL.md.bak.<timestamp>）
skill-hub validate existing-skill --fix

# 检查 SKILL.md 和技能目录内 Markdown 文件的本地链接
skill-hub validate existing-skill --links

# 批量扫描、修复、登记、验证，并归档到默认仓库
skill-hub import .agents/skills \
  --target open_code \
  --fix-frontmatter \
  --archive \
  --force

# 面向自动化脚本输出状态 JSON
skill-hub status --json

# 检测 scope 下所有 .agents/skills/<id>/SKILL.md 重复副本
skill-hub dedupe . --canonical .agents/skills --strategy newest

# 输出机器可读报告
skill-hub dedupe . --canonical .agents/skills --json

# 从 canonical 目录同步所有同 ID 副本，默认先创建 <skill-dir>.bak.<timestamp>
skill-hub sync-copies --canonical .agents/skills --scope .

# 只预览将同步的副本
skill-hub sync-copies --canonical .agents/skills --scope . --dry-run

# 扫描技能内容中的本机绝对路径、file://、vscode:// 链接
skill-hub lint . --paths --project-root "$PWD"

# 自动将 project-root 内的本机路径改写为相对路径，默认创建 SKILL.md.bak.<timestamp>
skill-hub lint . --paths --project-root "$PWD" --fix

# 演习模式输出 JSON，适合脚本审计
skill-hub lint . --paths --project-root "$PWD" --fix --dry-run --json

# 生成 Markdown 审计报告，聚合数量、登记、validate、status、dedupe、lint 和默认仓库推送状态
skill-hub audit .agents/skills --output .agents/skills-refresh-progress.md

# 输出 JSON 报告，适合 CI 或 agent 自动化消费
skill-hub audit .agents/skills --format json

# 查看所有仓库
skill-hub repo list

# 机器可读仓库列表
skill-hub repo list --json

# 同步所有仓库
skill-hub repo sync

# 机器可读同步摘要
skill-hub repo sync --json

# 启用/禁用仓库
skill-hub repo enable community
skill-hub repo disable personal

# 项目目录移动或删除后，清理 state.json 中的失效项目记录
skill-hub prune

语法说明：<参数>为必需参数，[参数]为可选参数

全局选项：

• -h, --help - 显示帮助信息
• -v, --version - 显示版本信息
• --dry-run - 演习模式
• --force - 强制模式

• 详细安装和使用指南 - 完整的安装方法、命令参考、技能管理和故障排除
  • 4种安装方法详解（一键脚本、预编译二进制、源码编译、本地开发）
  • 完整命令参考和常用工作流程
  • 技能规范、目录结构和变量系统
  • 支持的AI工具和兼容性说明
  • 常见问题故障排除

• 开发指南 - 构建、发布、贡献和架构设计
  • 项目结构和代码架构
  • 开发环境设置和构建系统
  • 测试策略和发布流程
  • 贡献指南和代码审查
  • 性能优化和安全考虑

MIT License - 详见 LICENSE 文件

如遇到问题或有功能建议，请：

1. 查看现有Issue是否已解决
2. 创建新的Issue，详细描述问题
3. 提供复现步骤和环境信息

欢迎贡献代码！请参考 DEVELOPMENT.md 中的贡献指南。

快速链接:

• GitHub仓库
• 最新发布版本
• 问题反馈
• 开发文档
• 安装指南