npm package: @hzpeng/aisync
Description: Sync AI tool skills and MCP configs across Claude Code, Cursor, Codex, and OpenCode
Author: hrrmzp@163.com
Latest version: 0.2.0

# aisync

在 Cursor、Claude Code、Codex、OpenCode 之间同步 AI 编码工具的 Skills。

每个 AI 编码工具都有自己的 skills 目录。**aisync** 提供一个统一的中心库（`~/.aisync/skills/`），在各工具间导入、管理和导出 skills，同时保留软链接和真实文件的原始状态。

## 安装

```bash
npm install -g @hzpeng/aisync
```

## 快速开始

```bash
# 扫描本地已安装的 AI 工具
aisync scan

# 从 Cursor 导入 skills 到中心库
aisync skills import --from cursor

# 导出 skills 到 Claude Code
aisync skills export --to claude_code

# 创建或绑定 GitHub 仓库并发布选中的 skills
aisync skills github connect --repo you/ai-skills

# 同步本地和远端 skills
aisync skills github sync

# 查看当前 GitHub 目标
aisync skills github status
```

## 命令

### `aisync scan`

检测已安装的 AI 工具，显示各工具的 skills 数量。

```bash
aisync scan           # 概览
aisync scan --detail  # 展开每个工具的 skills 列表
```

```
  ✓ Cursor 15 skill(s)
  ✓ Claude Code 18 skill(s)
  ✓ OpenCode (no skills)
```

### `aisync skills import --from <tool>`

从指定工具导入 skills 到中心库（`~/.aisync/skills/`）。交互式多选列表让你选择要导入的 skills，已存在的会标注 `(exists)` 并默认不勾选。

```bash
aisync skills import --from cursor
aisync skills import --from claude_code
```

### `aisync skills export --to <tool>`

从中心库导出 skills 到指定工具的 skills 目录。通过交互式多选列表选择要导出的内容。

```bash
aisync skills export --to cursor
aisync skills export --to codex
```

### `aisync skills add <path>`

从任意本地路径直接添加一个 skill 到中心库。

```bash
aisync skills add ~/my-skills/custom-skill
aisync skills add ./local-skill
```

### `aisync skills remove <name>`

从中心库中删除一个 skill。如果这个 skill 之前通过 aisync 导出到了其他支持的工具，并且是由 aisync 管理的软链接，aisync 也会一并清理这些链接。

```bash
aisync skills remove my-skill
```

### `aisync skills github connect --repo <owner/repo>`

通过 `gh` 创建 GitHub 仓库，或绑定一个已存在的 GitHub 仓库，把选中的 skills 首次发布进去，自动生成仓库 `README.md` 和 `.aisync-skills.json`，并把它保存为后续命令的默认 GitHub 目标。

```bash
aisync skills github connect --repo you/ai-skills
aisync skills github connect --repo your-org/ai-skills --private
aisync skills github connect --repo you/ai-skills --dir ai/skills --description "Managed AI skills"
```

说明：

- 需要本机安装 `gh`，并先执行 `gh auth login`
- 默认创建私有仓库，传 `--public` 才会创建公开仓库
- 该仓库会被视为 aisync 管理仓库，`README.md` 和 `.aisync-skills.json` 会自动生成

### `aisync skills github sync`

同步默认 GitHub 目标。本地独有的 skills 会自动发布到 GitHub，远端独有的 skills 会自动安装回中心库；同名但内容不同的 skills 会被标记为冲突并保持不变。

```bash
aisync skills github sync
aisync skills github sync --message "sync local updates"
aisync skills github sync --repo your-org/ai-skills
aisync skills github sync --prune
```

如果你希望 GitHub 严格跟随本地中心库，可以使用 `--prune`。启用后，远端独有的 skills 不会安装回本地，而是会直接从 GitHub 删除。

### `aisync skills github status`

查看当前保存的 GitHub 目标，以及远端仓库是否可达。

```bash
aisync skills github status
```

### `aisync list`

列出中心库中当前存储的所有 skills。

```bash
aisync list   # 或: aisync ls
```

### `aisync clean`

清除 `~/.aisync/` 下的存储数据，执行前需要二次确认。

```bash
aisync clean            # 清除全部
aisync clean --skills   # 仅清除 skills
aisync clean --mcp      # 仅清除 MCP 配置
```

## 命令一览

| 命令 | 说明 |
| --- | --- |
| `aisync scan` | 检测已安装的 AI 工具 |
| `aisync scan -d` | 检测工具并列出各工具的 skills |
| `aisync skills import --from <tool>` | 从工具导入 skills 到中心库 |
| `aisync skills export --to <tool>` | 从中心库导出 skills 到工具 |
| `aisync skills add <path>` | 从任意路径添加 skill |
| `aisync skills remove <name>` | 从中心库删除 skill，并清理 aisync 管理的工具侧链接 |
| `aisync skills github connect --repo <owner/repo>` | 创建或绑定 GitHub 仓库，发布选中的 skills，并保存为默认目标 |
| `aisync skills github sync` | 将本地独有 skills 发布到 GitHub，并把远端独有 skills 安装回本地 |
| `aisync skills github status` | 查看当前 GitHub 目标和远端可达性 |
| `aisync list` | 列出中心库所有 skills |
| `aisync clean` | 清除所有存储数据 |
| `aisync clean --skills` | 仅清除 skills |
| `aisync clean --mcp` | 仅清除 MCP 配置 |

## 支持的工具

| Key | 工具 | Skills 目录 | 检测目录 |
| --- | --- | --- | --- |
| `cursor` | Cursor | `~/.cursor/skills/` | `~/.cursor/` |
| `claude_code` | Claude Code | `~/.claude/skills/` | `~/.claude/` |
| `codex` | Codex | `~/.codex/skills/` | `~/.codex/` |
| `opencode` | OpenCode | `~/.config/opencode/skills/` | `~/.config/opencode/` |

## 工作原理

### 中心库

所有 skills 以真实文件的形式合并到 `~/.aisync/skills/` 中——这是唯一的数据源。导入时，源工具目录中的软链接会被解引用，确保中心库始终持有实际内容。

从多个工具导入时，如果遇到同名 skill，会提示你选择跳过或覆盖。

### 基于软链接的导出

导出时，aisync 在工具的 skills 目录中创建指向 `~/.aisync/skills/` 的软链接：

- 在中心库修改一次 skill，所有工具立刻生效。
- 不浪费磁盘空间，没有重复副本。
- 修改后无需重新导出。

如果创建软链接失败（如权限问题），会回退为普通复制并给出警告。

### GitHub 分发

GitHub 工作流的目标不是简单包装 `git push` 和 `git pull`，而是提供更高层的 skills 分发体验：

- `connect` 直接通过 `gh` 创建或绑定仓库
- `sync` 用一个命令处理最常见的日常同步
- 本地独有 skills 自动发布
- 远端独有 skills 自动安装
- `sync --prune` 会删除远端独有 skills
- 冲突项只提示，不自动覆盖

## 许可

MIT