# 把自己的 Skill 放上 GitHub，再从仓库装回来（中）

上集我们已经从零做出一个 Skill，并在本地完成第一次调用。可它现在还住在桌面：电脑一换、文件夹一丢，作品就容易变成“只在作者机器上表演过一次”的限定款。

所以这一集不再给 X-ray 加功能，而是借它示范一套通用流程：**把自己的 Skill 发布到 GitHub，再从仓库重新安装，验证换台电脑、换个目录还能用。**

下面的仓库名、地址和截图来自 X-ray；制作你自己的 Skill 时，换成自己的名称和仓库即可。

![中集主线：发布 GitHub，再从仓库安装并换一个项目复验](images/01-episode-guide.png)<!-- display-width:520 -->

- **预计用时**：25～35 分钟。
- **需要准备**：[GitHub 账号](https://github.com/signup)、已经能用的 [Git](https://git-scm.com/downloads) 和 [CodeBuddy](https://www.codebuddy.cn/ide/)。
- **成功标志**：GitHub 仓库能看到完整源码；新测试目录里，CodeBuddy 从仓库安装 X-ray，并为另一个项目生成 `xray-report.html`。
- **今天不做**：不发布 ClawHub，不改 X-ray 的核心代码。

推上去只是“存好了”；从一个新文件夹重新装回来，才算真的能复用。

## 1. 先看懂这一集的闭环

![GitHub 闭环：源码进入仓库，再从新文件夹重新安装验证](images/02-github-flow-diagram.png)<!-- display-width:520 -->

路线只有四步：

```text
本地 X-ray
  → GitHub 保存源码与版本
  → CodeBuddy 从仓库重新安装
  → 新项目再次生成项目报告
```

这次我们刻意换一个项目。否则同一个文件夹反复跑成功，很容易把“缓存还在”误当成“发布真的有效”。

## 2. 在 GitHub 创建空仓库

GitHub 在这里不只是“备份网盘”，它会保存 Skill 的源码、说明、许可证和每次修改历史，也为后面的重新安装提供稳定地址。

打开 [GitHub 新建仓库页面](https://github.com/new)。为了和截图一致，仓库名填写 `x-ray`；制作自己的 Skill 时改成自己的名称即可。准备公开分享时选择 `Public`，只做内部练习则先确认组织规则。

![在 GitHub 创建公开的 x-ray 仓库](images/03-create-github-repo.png)<!-- display-width:600 -->

为了和我们的真实实验一致，这里先不要勾选自动创建 README、`.gitignore` 和 License。稍后我们亲手补齐，也能看清每个文件为什么存在。

创建完成后先别急着关页面，记下仓库地址。截图中的地址是：

```text
https://github.com/ppshuX/x-ray.git
```

你跟做时，把用户名换成自己的。

## 3. 先写 .gitignore：别把运行垃圾一起搬家

在本地 `x-ray` 根目录创建 `.gitignore`，写入：

```gitignore
# Python 缓存
__pycache__/
*.pyc

# X-ray 运行生成的数据
xray-data.json
xray-report.html
```

![用 .gitignore 排除缓存与运行生成的数据](images/04-gitignore.png)<!-- display-width:600 -->

这两个输出文件属于“每次扫描的结果”，不是 Skill 源码。把它们提交到仓库，就像搬家时把垃圾桶也打包贴上“祖传资产”——不是不行，主要是没必要。

## 4. 提交并推送到 GitHub

如果这是一个全新的本地目录，复制下面这组命令：

```powershell
git init
git add .
git commit -m "Initial release of X-ray Skill"
git branch -M main
git remote add origin https://github.com/你的用户名/x-ray.git
git push -u origin main
```

命令中的 `你的用户名` 要替换成真实 GitHub 用户名。

![本地提交后把 main 分支推送到 GitHub](images/05-git-push.png)<!-- display-width:600 -->

这张图是我们的真实实验现场，有两个细节和全新目录不同：

- 本地已经有初始提交，所以画面里用了 `git commit --amend --no-edit`；第一次跟做请使用上面的 `git commit -m ...`，不要无缘无故改写历史。
- GitHub 提示仓库地址大小写发生跳转，但最终仍成功显示 `main -> main`。

**你真正要比对的成功标志：** 终端最后没有报错，并出现 `branch 'main' set up to track 'origin/main'` 或同义提示。

刷新 GitHub 页面，应该能看到 `assets`、`references`、`scripts`、`.gitignore` 和 `SKILL.md`。

![GitHub 已收到 X-ray 的目录与源码](images/06-github-repo-created.png)<!-- display-width:600 -->

## 5. 给仓库补一张“说明书”

点击 GitHub 页面上的 `Add a README`，写清三件事：

1. X-ray 能做什么；
2. 它怎样工作；
3. 目录里每一部分负责什么。

我们的 README 页面是这样：

![补充 README，说明 X-ray 的用途、原理和目录](images/07-add-readme.png)<!-- display-width:600 -->

如果不想从空白开始，可以参考已经公开的 [X-ray GitHub 仓库](https://github.com/ppshuX/x-ray)，但建议用自己的话改一遍。README 是写给人看的，`SKILL.md` 才是写给 Agent 执行的，两者别串台。

## 6. 再补一个开源许可证

回到仓库主页，点击 `Add file → Create new file`。

![从 GitHub 页面创建开源许可证文件](images/08-add-license.png)<!-- display-width:600 -->

文件名输入 `LICENSE`，再点击 `Choose a license template`，选择 MIT License。

![实验选择 MIT License 作为 GitHub 仓库许可证](images/09-choose-mit.png)<!-- display-width:600 -->

确认年份和版权人后提交：

![提交 LICENSE 文件，完成仓库说明](images/10-commit-license.png)<!-- display-width:600 -->

GitHub 官方的[开源许可证说明](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository)也提醒：许可证决定别人可以怎样使用、修改和分发代码，不要把它当成仓库装饰品。

现在仓库里已经有源码、README 和 MIT License：

![GitHub 仓库已经包含源码、README 与许可证](images/11-github-release.png)<!-- display-width:600 -->

如果你在网页端新增了 README 或 LICENSE，之后还要继续从本地推送，先执行一次：

```powershell
git pull --rebase origin main
```

这样本地和远端不会各写各的，最后在历史里上演“双城记”。

## 7. 新建一个干净的 GitHub 测试目录

现在开始验证“从仓库装回来”。在桌面新建 `github测试skill` 文件夹。

![新建 github测试skill 文件夹，模拟一台没装过 X-ray 的环境](images/12-create-github-test-folder.png)<!-- display-width:600 -->

这一步看似普通，却很重要：我们不在原来的 X-ray 开发目录里测试，避免本地文件让结果作弊。

## 8. 换一个项目做复验

这里同样不用照搬 AcApp。你可以选择自己的公开项目，或者任何允许当前模型读取的仓库；刻意换项目，是为了排除旧目录和缓存带来的“假成功”。

如果暂时没有合适项目，可以进入 `github测试skill`，执行和截图一致的 SSH 命令：

```powershell
git clone git@github.com:ppshux/acapp.git
```

![克隆另一个公开仓库，准备验证 GitHub 安装路线](images/13-clone-acapp.png)<!-- display-width:600 -->

没有配置 GitHub SSH Key 时，用 HTTPS：

```powershell
git clone https://github.com/ppshuX/acapp.git
```

本次截图使用公开的 [AcApp 仓库](https://github.com/ppshuX/acapp)，只是为了方便对照；我们只读取文件，不安装依赖、不启动服务。

## 9. 让 CodeBuddy 从 GitHub 安装 X-ray

这一步验证的不是 X-ray 功能，而是“仅凭 GitHub 地址，Agent 能不能把一个 Skill 正确装回来”。

用 CodeBuddy 打开 `github测试skill`，把截图里的这句话原样发给它。制作自己的 Skill 时，把 URL 换成自己的仓库：

```text
帮我装一下这个skill：https://github.com/ppshuX/X-ray.git
```

![把 GitHub 仓库地址交给 CodeBuddy 安装](images/14-install-from-github-prompt.png)<!-- display-width:600 -->

这里的 URL 直接指向刚刚发布的仓库。CodeBuddy 会克隆它，并放入本地 Skill 目录。

![CodeBuddy 将 GitHub 仓库安装到 .codebuddy/skills/x-ray](images/15-install-from-github-result.png)<!-- display-width:600 -->

在结果里重点检查两项：

- 安装来源是 `git@github.com:ppshuX/x-ray.git` 或同一个仓库的 HTTPS 地址；
- 安装目录是 `C:\Users\你的用户名\.codebuddy\skills\x-ray`。

如果旧版本已经存在，先让 CodeBuddy 明确是覆盖、更新还是复用，别让两个同名 X-ray 在后台玩“真假美猴王”。安装完成后重启或重载 CodeBuddy。

## 10. 用 /x-ray 分析新项目

重新打开 `github测试skill`，输入：

```text
/x-ray
```

![重新执行 /x-ray 验证 GitHub 安装版本](images/16-invoke-github-skill.png)<!-- display-width:600 -->

等待它完成扫描、抽样阅读和 HTML 生成。目录里应该再次出现：

```text
xray-data.json
xray-report.html
```

打开报告，顶部会显示新项目的文件数、目录数、语言与项目概况：

![从 GitHub 安装的 X-ray 已生成第二份项目报告](images/17-acapp-report-overview.png)<!-- display-width:600 -->

继续往下看复杂度、学习方向、推荐阅读顺序和注意事项：

![第二份报告给出复杂度、学习方向与阅读顺序](images/18-acapp-report-details.png)<!-- display-width:600 -->

**中集通关：** X-ray 不再只存在于桌面。它已经进入 GitHub，并能从仓库重新安装，在新项目上交出第二份报告。

## 11. 这里到底验证了什么？

我们验证了三层：

1. **源码层**：GitHub 能完整保存 Skill 的目录和历史；
2. **安装层**：CodeBuddy 能根据仓库地址把 X-ray 装进 Skill 目录；
3. **复用层**：换一个项目后，X-ray 仍能生成独立报告。

但 GitHub 还不是专门的 Skill 市场。别人需要先知道仓库地址，也看不到统一的版本页和自动扫描状态。

## 12. 收尾：GitHub 路线闭环

![中集通关：X-ray 已经能从 GitHub 重新安装并完成独立复验](images/19-episode-summary.png)<!-- display-width:520 -->

这一集完成了：

1. 把 Skill 源码、README 与许可证放进 GitHub；
2. 从 GitHub 仓库重新安装 Skill；
3. 用另一个项目生成第二份项目解剖报告。

你真正可以复用的，是“整理发布内容 → 推送仓库 → 换目录重装 → 换项目验收”这条路线。下一集只增加一个变量：**把 Skill 发布到 ClawHub，获得版本、安装入口和自动扫描结果，再做第三次复验。**