Skip to content

Commit 8f1adec

Browse files
tc9011tc9011
committed
docs: add Chinese README and language switcher
1 parent db84ee5 commit 8f1adec

7 files changed

Lines changed: 763 additions & 76 deletions

File tree

‎README.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ A CLI companion to [vercel-labs/skills](https://github.com/vercel-labs/skills)
1111
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
1212
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
1313

14+
English | [中文](./README.zh-CN.md)
15+
1416
</div>
1517

1618
---
@@ -103,6 +105,7 @@ sm link --agents cursor opencode claude-code
103105
| `-p, --project` | Link skills to project directory (CWD) instead of global paths |
104106
| `-s, --skills <skills...>` | Skill names to link (project mode only, skips skill prompt) |
105107
| `--mode <mode>` | `copy` or `symlink` (project mode only, default: `copy`, skips prompt) |
108+
106109
An interactive multiselect prompt lets you pick which agents to link. Only agents with local directories are pre-selected. Your selection is remembered for next time.
107110

108111
When `--agents` is provided, the agent selection prompt is skipped entirely — useful for scripting and AI agent automation:
@@ -251,6 +254,7 @@ sm link --project reads .skill-lock.json → select skills → choose copy/symli
251254
./my-project/.agents/skills/my-skill ← copied from ~/.agents/skills/
252255
./my-project/.claude/skills/my-skill ← copied from ~/.agents/skills/
253256
```
257+
254258
## Skill
255259

256260
This project includes a skill at `skills/skills-manager/` that teaches AI agents how to operate the CLI — push, pull, and link commands.
@@ -313,10 +317,12 @@ src/
313317
├── lockfile.ts # Read-only .skill-lock.json parser
314318
├── linker.ts # Symlink creation + project-level copy/link
315319
├── git-ops.ts # Git push/pull via simple-git
316-
└── commands/
317-
├── push.ts # Push handler
318-
├── pull.ts # Pull handler (auto-runs link)
319-
└── link.ts # Link handler (interactive multiselect)
320+
├── commands/
321+
│ ├── push.ts # Push handler
322+
│ ├── pull.ts # Pull handler (auto-runs link)
323+
│ └── link.ts # Link handler (interactive multiselect)
324+
└── prompts/
325+
└── search-multiselect.ts # Searchable multi-select prompt component
320326
```
321327

322328
### Releasing

‎README.zh-CN.md‎

Lines changed: 349 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,349 @@
1+
<div align="center">
2+
3+
# skills-manager
4+
5+
**将 AI 智能体技能备份并恢复到 GitHub。**
6+
7+
这是 [vercel-labs/skills](https://github.com/vercel-labs/skills) 的 CLI 配套工具 —— 将你的 `~/.agents/` 目录推送到远程仓库，在任意机器上拉取，并自动为所有智能体创建技能符号链接。
8+
9+
[![npm version](https://img.shields.io/npm/v/%40tc9011%2Fskills-manager?color=cb0000&label=npm)](https://www.npmjs.com/package/@tc9011/skills-manager)
10+
[![CI](https://img.shields.io/github/actions/workflow/status/tc9011/skills-manager/ci.yml?label=CI)](https://github.com/tc9011/skills-manager/actions/workflows/ci.yml)
11+
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
12+
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
13+
14+
[English](./README.md) | 中文
15+
16+
</div>
17+
18+
---
19+
20+
## 为什么需要它
21+
22+
[vercel-labs/skills](https://github.com/vercel-labs/skills) 负责安装和管理技能，但不处理备份、恢复或跨机器同步。`skills-manager` 补上了这个缺口：
23+
24+
- **Push（推送）** — 提交并推送 `~/.agents/`（技能 + 锁定文件）到 GitHub
25+
- **Pull（拉取）** — 在任意机器上克隆或拉取技能
26+
- **Link（链接）** — 读取 `.skill-lock.json`，为每个使用的智能体创建符号链接
27+
- **项目链接** — 将技能直接链接或复制到当前项目目录，用于本地开发
28+
29+
> **注意：** 本工具只读取 `.skill-lock.json`，从不修改它 —— 该文件由 `vercel-labs/skills` 管理。
30+
31+
## 安装
32+
33+
```bash
34+
# 直接运行（无需安装）
35+
npx @tc9011/skills-manager push
36+
37+
# 或全局安装
38+
npm install -g @tc9011/skills-manager
39+
```
40+
41+
> **提示：** 全局安装后，以下命令中可以使用 `sm`（或完整名称 `skills-manager`）代替 `npx @tc9011/skills-manager`。
42+
43+
**环境要求：** Node.js ≥ 20，推荐安装 [GitHub CLI](https://cli.github.com/)（`gh`）用于认证。
44+
45+
## 快速开始
46+
47+
```bash
48+
# 1. 将技能备份到 GitHub
49+
sm push
50+
51+
# 2. 在新机器上恢复
52+
sm pull --repo owner/my-skills
53+
54+
# 3. 重新链接技能到智能体（pull 后自动执行）
55+
sm link
56+
57+
# 4. 将技能链接到当前项目目录
58+
sm link --project
59+
```
60+
61+
首次运行时，如果 `~/.agents/` 还不是 git 仓库，`push` 和 `pull` 会交互式引导你完成 git 仓库和远程地址的设置。
62+
63+
## 命令
64+
65+
### `sm push`
66+
67+
将 `~/.agents/` 提交并推送到配置的 GitHub 远程仓库。
68+
69+
```bash
70+
sm push
71+
sm push -m "添加新的调试技能"
72+
```
73+
74+
| 选项 | 说明 |
75+
|------|------|
76+
| `-m, --message <msg>` | 自定义提交信息（默认：自动生成） |
77+
78+
### `sm pull`
79+
80+
从 GitHub 拉取并自动执行 `link`。
81+
82+
```bash
83+
sm pull --repo tc9011/my-skills
84+
sm pull # 使用已有远程地址
85+
sm pull --skip-link # 仅拉取，不执行链接
86+
```
87+
88+
| 选项 | 说明 |
89+
|------|------|
90+
| `-r, --repo <owner/name>` | 要拉取的 GitHub 仓库 |
91+
| `--skip-link` | 拉取后跳过自动链接 |
92+
93+
### `sm link`
94+
95+
读取 `.skill-lock.json`，从每个智能体的技能目录到 `~/.agents/skills/` 创建相对符号链接。
96+
97+
```bash
98+
sm link
99+
sm link --agents cursor opencode claude-code
100+
```
101+
102+
| 选项 | 说明 |
103+
|------|------|
104+
| `-a, --agents <ids...>` | 要链接的智能体 ID（指定后跳过交互提示） |
105+
| `-p, --project` | 链接到项目目录（CWD）而非全局路径 |
106+
| `-s, --skills <skills...>` | 要链接的技能名称（仅项目模式，跳过技能提示） |
107+
| `--mode <mode>` | `copy` 或 `symlink`（仅项目模式，默认：`copy`，跳过提示） |
108+
109+
交互式多选提示允许你选择要链接的智能体。已有本地目录的智能体会被预选。你的选择会被记录以供下次使用。
110+
111+
指定 `--agents` 时，直接跳过智能体选择提示 —— 适合脚本和 AI 智能体自动化场景：
112+
113+
```bash
114+
# 非交互式：将所有技能链接到指定智能体
115+
sm link --agents cursor opencode
116+
```
117+
118+
**符号链接模型：**
119+
120+
```
121+
~/.config/opencode/skills/my-skill → ../../../.agents/skills/my-skill (相对路径)
122+
~/.claude/skills/my-skill → ../../.agents/skills/my-skill (相对路径)
123+
```
124+
125+
**项目模式：**
126+
127+
使用 `--project`（或 `-p`）时，会依次经过三个交互提示：
128+
129+
1. **选择技能** — 选择要链接的技能（默认不预选）
130+
2. **复制或符号链接** — 复制文件（默认，推荐）或创建绝对路径符号链接
131+
3. **选择智能体** — 选择要配置项目级技能的智能体
132+
133+
通过命令行提供 `--skills`、`--mode` 和 `--agents` 可跳过所有提示：
134+
135+
```bash
136+
# 完全非交互式的项目链接
137+
sm link --project --agents cursor claude-code --skills my-skill --mode copy
138+
```
139+
140+
`link --project` 后的项目目录结构示例：
141+
142+
```
143+
./project/
144+
├── .agents/skills/my-skill ← 通用智能体共享（复制或符号链接）
145+
├── .claude/skills/my-skill ← claude-code 专属
146+
├── .cursor/skills/my-skill → ~/.agents/skills/my-skill（绝对路径符号链接）
147+
└── .trae/skills/my-skill ← trae 专属
148+
```
149+
150+
- **技能选择：** 只复制/链接你选中的技能，无需包含全部。
151+
- **去重：** 共享同一项目路径的智能体只触发一次复制/链接操作。
152+
- **复制 vs 符号链接：** 复制会创建独立文件（推荐，便于移植）。符号链接使用绝对路径指向 `~/.agents/skills/`。
153+
154+
## 认证
155+
156+
认证是**可选的**。如果 git 已配置好凭证（SSH 密钥、macOS Keychain、`git credential-manager` 等），push 和 pull 无需额外设置即可工作。
157+
158+
当 git 凭证不可用时，CLI 按以下顺序查找 token：
159+
160+
1. **`gh auth token`** — GitHub CLI（推荐）
161+
2. **`$GITHUB_TOKEN`** — 环境变量
162+
3. **`$GH_TOKEN`** — 环境变量
163+
164+
如果都未找到，git 会尝试未认证操作 —— 公开仓库可以，私有仓库会失败。`link` 命令不需要认证。
165+
166+
## 支持的智能体
167+
168+
41 个智能体 —— 与 [vercel-labs/skills](https://github.com/vercel-labs/skills) 完整注册表保持同步。
169+
170+
<details>
171+
<summary><strong>通用智能体</strong>（共享 <code>~/.agents/skills</code>）</summary>
172+
173+
| 智能体 | ID | 全局路径 |
174+
|--------|----|---------:|
175+
| Amp | `amp` | `$XDG_CONFIG_HOME/agents/skills` |
176+
| Cline | `cline` | `~/.agents/skills` |
177+
| Codex | `codex` | `$CODEX_HOME/skills` |
178+
| Cursor | `cursor` | `~/.cursor/skills` |
179+
| Gemini CLI | `gemini-cli` | `~/.gemini/skills` |
180+
| GitHub Copilot | `github-copilot` | `~/.copilot/skills` |
181+
| Kimi Code CLI | `kimi-cli` | `$XDG_CONFIG_HOME/agents/skills` |
182+
| OpenCode | `opencode` | `$XDG_CONFIG_HOME/opencode/skills` |
183+
| Replit | `replit` | `$XDG_CONFIG_HOME/agents/skills` |
184+
| Universal | `universal` | `$XDG_CONFIG_HOME/agents/skills` |
185+
186+
</details>
187+
188+
<details>
189+
<summary><strong>专属智能体</strong>（各自独立路径）</summary>
190+
191+
| 智能体 | ID | 全局路径 |
192+
|--------|----|---------:|
193+
| AdaL | `adal` | `~/.adal/skills` |
194+
| Antigravity | `antigravity` | `~/.gemini/antigravity/skills` |
195+
| Augment | `augment` | `~/.augment/skills` |
196+
| Claude Code | `claude-code` | `$CLAUDE_CONFIG_DIR/skills` |
197+
| CodeBuddy | `codebuddy` | `~/.codebuddy/skills` |
198+
| Command Code | `command-code` | `~/.commandcode/skills` |
199+
| Continue | `continue` | `~/.continue/skills` |
200+
| Cortex Code | `cortex` | `~/.snowflake/cortex/skills` |
201+
| Crush | `crush` | `$XDG_CONFIG_HOME/crush/skills` |
202+
| Droid | `droid` | `~/.factory/skills` |
203+
| Goose | `goose` | `$XDG_CONFIG_HOME/goose/skills` |
204+
| iFlow CLI | `iflow-cli` | `~/.iflow/skills` |
205+
| Junie | `junie` | `~/.junie/skills` |
206+
| Kilo Code | `kilo` | `~/.kilocode/skills` |
207+
| Kiro CLI | `kiro-cli` | `~/.kiro/skills` |
208+
| Kode | `kode` | `~/.kode/skills` |
209+
| MCPJam | `mcpjam` | `~/.mcpjam/skills` |
210+
| Mistral Vibe | `mistral-vibe` | `~/.vibe/skills` |
211+
| Mux | `mux` | `~/.mux/skills` |
212+
| Neovate | `neovate` | `~/.neovate/skills` |
213+
| OpenClaw | `openclaw` | `~/.openclaw/skills` |
214+
| OpenHands | `openhands` | `~/.openhands/skills` |
215+
| Pi | `pi` | `~/.pi/agent/skills` |
216+
| Pochi | `pochi` | `~/.pochi/skills` |
217+
| Qoder | `qoder` | `~/.qoder/skills` |
218+
| Qwen Code | `qwen-code` | `~/.qwen/skills` |
219+
| Roo Code | `roo` | `~/.roo/skills` |
220+
| Trae | `trae` | `~/.trae/skills` |
221+
| Trae CN | `trae-cn` | `~/.trae-cn/skills` |
222+
| Windsurf | `windsurf` | `~/.codeium/windsurf/skills` |
223+
| Zencoder | `zencoder` | `~/.zencoder/skills` |
224+
225+
</details>
226+
227+
## 环境变量
228+
229+
| 变量 | 使用场景 | 默认值 |
230+
|------|---------|--------|
231+
| `GITHUB_TOKEN` | `push`、`pull` | — |
232+
| `GH_TOKEN` | `push`、`pull` | — |
233+
| `XDG_CONFIG_HOME` | `opencode`、`amp`、`kimi-cli`、`replit`、`universal`、`goose`、`crush` | `~/.config` |
234+
| `CODEX_HOME` | `codex` | `~/.codex` |
235+
| `CLAUDE_CONFIG_DIR` | `claude-code` | `~/.claude` |
236+
237+
## 工作原理
238+
239+
```
240+
~/.agents/ ← Git 仓库（push/pull 目标）
241+
├── .skill-lock.json ← 由 vercel-labs/skills 管理（只读）
242+
└── skills/
243+
├── my-skill/
244+
└── another-skill/
245+
246+
sm link 读取 .skill-lock.json → 创建相对路径符号链接：
247+
248+
~/.cursor/skills/my-skill → ../../.agents/skills/my-skill
249+
~/.claude/skills/my-skill → ../../.agents/skills/my-skill
250+
~/.config/opencode/skills/my-skill → ../../../.agents/skills/my-skill
251+
```
252+
253+
```
254+
sm link --project 读取 .skill-lock.json → 选择技能 → 选择复制/符号链接 → 选择智能体 → 复制/链接到 CWD：
255+
256+
./my-project/.agents/skills/my-skill ← 从 ~/.agents/skills/ 复制
257+
./my-project/.claude/skills/my-skill ← 从 ~/.agents/skills/ 复制
258+
```
259+
260+
## 技能
261+
262+
本项目在 `skills/skills-manager/` 提供了一个技能，教 AI 智能体如何操作 CLI —— push、pull 和 link 命令。
263+
264+
```bash
265+
# 通过 vercel-labs/skills CLI 安装
266+
npx skills add tc9011/skills-manager
267+
268+
# 将指定技能安装到指定智能体
269+
npx skills add tc9011/skills-manager --skill skills-manager -a opencode -a claude-code
270+
271+
# 全局安装（跨项目可用）
272+
npx skills add tc9011/skills-manager -g
273+
```
274+
275+
## 贡献
276+
277+
### 初始化
278+
279+
```bash
280+
git clone https://github.com/tc9011/skills-manager.git
281+
cd skills-manager
282+
npm install
283+
```
284+
285+
### 开发
286+
287+
```bash
288+
# 直接运行命令（无需构建）
289+
npx tsx src/index.ts push
290+
npx tsx src/index.ts link
291+
292+
# 或通过 npm script
293+
npm run dev -- push
294+
```
295+
296+
### 测试
297+
298+
```bash
299+
npm test # 运行测试
300+
npm run test:watch # 监听模式
301+
npm run test:coverage # 生成覆盖率报告
302+
```
303+
304+
### 构建
305+
306+
```bash
307+
npm run build # 编译 TypeScript → dist/
308+
npm run lint # 运行 ESLint
309+
```
310+
311+
### 项目结构
312+
313+
```
314+
src/
315+
├── index.ts # CLI 入口（Commander.js）
316+
├── agents.ts # 41 个智能体注册表 + 路径解析
317+
├── auth.ts # GitHub token 解析
318+
├── config.ts # XDG 规范的配置持久化
319+
├── lockfile.ts # 只读 .skill-lock.json 解析器
320+
├── linker.ts # 符号链接创建 + 项目级复制/链接
321+
├── git-ops.ts # 通过 simple-git 执行 Git push/pull
322+
├── commands/
323+
│ ├── push.ts # Push 处理器
324+
│ ├── pull.ts # Pull 处理器（自动执行 link）
325+
│ └── link.ts # Link 处理器（交互式多选）
326+
└── prompts/
327+
└── search-multiselect.ts # 可搜索多选提示组件
328+
```
329+
330+
### 发布
331+
332+
发布流程完全通过 [semantic-release](https://github.com/semantic-release/semantic-release) 自动化。只需使用 [Conventional Commits](https://www.conventionalcommits.org/) 并推送到 `main`：
333+
334+
| 提交前缀 | 版本升级 | 示例 |
335+
|----------|---------|------|
336+
| `fix:` | Patch（`0.1.0` → `0.1.1`） | `fix: handle missing config` |
337+
| `feat:` | Minor（`0.1.0` → `0.2.0`） | `feat: add export command` |
338+
| `feat!:` 或 `BREAKING CHANGE:` | Major（`0.1.0` → `1.0.0`） | `feat!: drop Node 18 support` |
339+
340+
CI 流水线会自动：
341+
1. 分析上次发布以来的提交
342+
2. 确定版本升级幅度
343+
3. 更新 `package.json` + `CHANGELOG.md`
344+
4. 发布到 npm
345+
5. 创建 GitHub Release 并附带说明
346+
347+
## License
348+
349+
[MIT](./LICENSE)

0 commit comments

Comments
 (0)