xc-skills 🚀

一款专门为 XC 开发团队定制的 Agent 资产（技能、规则、工作流）管理 CLI 工具。它模仿了官方 skills 的交互体验，内置了团队常用的开发工具配置，提供了更细致的安装控制，并全面支持资产的自进化同步、远程/本地双模管理、以及单文件/文件夹混合资产兼容。

✨ 核心特性

• 🤖 内置 Agent 深度支持：默认支持 Antigravity, Trae, Codex, Claude Code 等主流 AI 编码工具。
• 📦 智能多资产兼容处理 (Skills, Rules, Workflows)：
  • 技能 (Skills)：支持文件夹形式的多文件技能，包含 SKILL.md 和进化历史 EVOLUTION.md。
  • 规则 (Rules)：支持单文件形式的规则配置。
  • 工作流 (Workflows)：支持单文件形式的工作流资产配置。
• 🔗 软链接自动解析与保护：自动识别与解析软链接状态；同步时支持“真身校验”，防止误覆盖用户通过软链进行的实时修改；支持软链断开的防御性清理。
• 🌐 远程/本地双模管理 (Repository Mode)：
  • 本地模式 (Local)：直接对齐并管理本地路径下的中央技能仓库。
  • 远程模式 (Remote)：全面原生支持 GitHub、Coding.net 等远程 Git 仓库。同步与查看时在系统临时目录中动态克隆/缓存，流程结束自动清理。
• 🕰 智能历史追溯与自愈解析 (View)：
  • Tag-First 读取：优先使用语义化的 Git Tag（[email protected]）拉取历史版本，自动降级至 Git Commit Hash。
  • 重命名自愈 (Dynamic Path Resolution)：如果资产在历史提交中曾被重命名、改组或移动目录，系统会通过 git ls-tree 进行深度动态检索，确保历史版本仍能成功加载！
• 🎋 多分支覆盖控制 (Branch Override)：支持在 add、pull、publish 等命令中使用 -b, --branch 参数随时覆盖默认分支，方便多分支联调与测试。

📦 安装

你可以通过 npm 全局安装：

npm install -g xc-skills

或者使用 pnpm dlx 临时执行：

pnpm dlx xc-skills add .

⚙️ 初始化配置 (Config)

运行交互式配置命令，可以轻松设置工具的操作模式及关联仓库：

xc-skills config

运行后将进入深度交互引导流程：

1. 操作模式选择：选择 Local (本地管理) 或 Remote (远程管理)。
2. 设置资产中心：输入本地仓库的绝对路径或远程仓库的 Git 地址（如 Coding / GitHub）。
3. 发布仓库设置：输入用于发布技能的远程仓库地址 (Remote URL)。
4. 默认分支设置：指定拉取/发布的默认分支（默认为 master）。
5. 平台/分组加载设置：设置默认扫描和加载的分组目录（如 miniapp, backend, h5, common）。
6. 自动化克隆与对齐：工具会智能检测您的环境，若为 Local 模式且路径不存在，会自动克隆远程仓库；若指定分支不存在，会交互式引导您基于 master 自动创建并推送新分支。

🚀 使用指南

1. 资产添加与安装 (Add)

在项目根目录下运行，用于交互式选择并安装技能或资产：

# 扫描本地技能并安装
xc-skills add .

# 支持指定资产类型 (skills, rules, workflows)，例如安装规则：
xc-skills add . -t rules

# 指定具体技能、Agent 及输出路径
xc-skills add . -s use-icon -a Antigravity -o .agents/skills

2. 从 GitHub/Coding.net 远程安装

可以直接传入远程 Git 仓库地址进行安装，且支持指定拉取的分支：

# 从 GitHub 默认分支拉取
xc-skills add https://github.com/vuejs-ai/skills.git

# 使用 -b / --branch 参数覆盖默认分支，拉取特定分支的技能进行测试
xc-skills add https://github.com/vuejs-ai/skills.git -b feature/new-skills

3. 发布技能到远程仓库 (Publish) 🚀

如果你本地开发了新资产，想要一键推送到远程仓库：

# 自动扫描当前目录下的子文件/文件夹作为技能并发布
xc-skills publish

# 发布特定类型的资产（例如规则 rules）到指定远程仓库的分支
xc-skills publish -t rules -r [email protected]:your-team/skills.git -b main

4. 同步进化到中央仓库 (Sync) 🌟

当你在业务项目里改进了某个技能或资产（生成了 PENDING_SYNC.md）后，使用此命令安全地将变更同步回本地或远程中央仓库：

# 在业务项目根目录下运行
xc-skills sync

该命令采用了原生的安全合并与 Git 历史管理，会自动：

• 自动检测软链关联（真身校验），若是软链则安全跳过，防止误覆写。
• 对齐远程状态（执行安全的 pull --rebase --autostash）。
• 物理拷贝 SKILL.md / EVOLUTION.md 内容时自动解引用软链，拷贝真实内容。
• 缺失 EVOLUTION.md 时自动防御性补全。
• 自动在中央仓库执行 Git Commit，并创建语义化的 Git Tag（格式如 [email protected]）。
• 将本次提交的 Git Hash 自动记录回 EVOLUTION.md，并自动清理本地同步标记 PENDING_SYNC.md。

5. 交互式历史追溯 (View) 🕰️

由于采用了 Git 增量历史管理，你可以使用 view 命令随时以超轻量体验回溯资产的历史版本：

# 交互式选择查看某个技能的进化历史列表
xc-skills view use-icon

# 远程模式下会自动在临时目录克隆、缓存，并在阅读完成后自动清理！
# 若资产曾在历史上被重命名、改组或移动目录，系统也会通过 git ls-tree 动态解析恢复历史文件路径。

# 直接查看特定语义化 Tag 版本的技能内容
xc-skills view [email protected]

# 直接查看特定 Hash 版本的技能内容
xc-skills view use-icon@abc1234

6. 从中央仓库拉取最新 (Pull) 📥

当你需要在当前项目中获取中央仓库的最新资产版本时使用。

xc-skills pull

该命令会自动扫描当前项目已安装的资产，从配置的中央仓库拉取最新版，并覆盖本地副本（方便你基于最新版再次进化）。

7. 查看已安装的资产 (List)

# 查看当前项目的已安装资产
xc-skills list
# 别名形式
xc-skills ls

# 查看全局已安装的资产
xc-skills list -g

8. 清理项目技能目录 (Remove)

xc-skills remove

# 别名形式
xc-skills cleanup
xc-skills rm

# 清理全局已安装资产
xc-skills remove -g

🔄 自进化工作流

1. 就地进化：AI 在业务项目中发现技能缺陷，直接修改 .agents/skills/xxx/SKILL.md 并创建 PENDING_SYNC.md 标记。
2. 本地验证：在业务项目中验证改进是否有效。
3. 一键同步：运行 xc-skills sync。
4. 追溯历史：通过 EVOLUTION.md 中的 Hash 或运行 xc-skills view 随时回溯之前的版本。

🛠 命令参数说明

add 指令参数

| 选项 | 别名 | 描述 | 默认值 | | --- | --- | --- | --- | | -s, --skill <names> | - | 指定要安装的资产/技能名称（多个用逗号分隔，* 代表全部） | - | | -a, --agent <names> | - | 指定目标 Agent 名称（多个用逗号分隔，* 代表全部） | - | | -d, --dir <dir> | - | 指定源目录中资产存放的目录名 | skills | | -o, --out <path> | - | 指定输出的目标目录路径 | - | | -t, --type <type> | - | 指定安装资产类型：skills, rules, workflows | skills | | -b, --branch <branch>| - | 指定拉取的远程 Git 分支（覆盖全局配置） | - | | -y, --yes | - | 跳过所有确认和交互步骤，全部使用默认选项 | - |

publish 指令参数

| 选项 | 描述 | 默认值 | | --- | --- | --- | | -d, --dir <dir> | 指定需要发布的本地资产存放的文件夹 | skills | | -r, --remote <url> | 目标远程仓库 Git 地址 | - | | -b, --branch <branch>| 目标发布的远程分支名称 | - | | -t, --type <type> | 指定发布资产类型：skills, rules, workflows | skills |

config 指令参数

无选项参数。运行后进入交互式配置界面，引导配置本地/远程模式、分支、分组文件夹及关联对齐。

sync 指令参数

| 选项 | 描述 | 默认值 | | --- | --- | --- | | -d, --dir <dir> | 业务项目中待同步进化资产存放的目录 | .agents/skills | | -r, --repo <path> | 临时指定本地仓库路径或远程 Git 地址进行同步 | - |

list 指令参数

| 选项 | 描述 | | --- | --- | | -g, --global | 查看全局安装的资产，而非当前项目的资产 |

remove 指令参数

| 选项 | 描述 | | --- | --- | | -g, --global | 清理全局已安装资产，而非当前项目的资产 |

安装历史tag

格式：xc-skills add <仓库地址> -b <技能名>@<版本号>

xc-skills add https://github.com/your-team/skills.git -b [email protected]

📄 License

MIT