从零开源：如何将自定义 AI Skill 发布到 GitHub

这篇文章不仅包含了您提供的完整文件结构，还详细讲解了每个文件的作用、GitHub 创建仓库的具体步骤（图文逻辑），以及后续的维护指南。您可以直接复制以下内容作为您的博客文章发布。

文章目录

[🚀 从零开源：如何将自定义 AI Skill 发布到 GitHub](#🚀 从零开源：如何将自定义 AI Skill 发布到 GitHub)
- [📂 1. 准备你的 Skill 项目结构](#📂 1. 准备你的 Skill 项目结构)
- - [📄 关键文件说明](#📄 关键文件说明)
- [🛠️ 2. 在 GitHub 创建仓库](#🛠️ 2. 在 GitHub 创建仓库)
- - 第一步：登录并新建仓库
  - 第二步：填写仓库信息
- [📤 3. 上传文件 (两种方法)](#📤 3. 上传文件 (两种方法))
- - [方法 A：网页直接拖拽 (最简单，适合首次上传)](#方法 A：网页直接拖拽 (最简单，适合首次上传))
  - [方法 B：Git 命令行 (推荐，适合后续维护)](#方法 B：Git 命令行 (推荐，适合后续维护))
- [✅ 4. 验证与使用](#✅ 4. 验证与使用)
- - 如何安装/使用？
  - - [方式一：Git Clone (本地部署)](#方式一：Git Clone (本地部署))
    - [方式二：直接引用 Raw 链接](#方式二：直接引用 Raw 链接)
- [🔄 5. 后续维护与迭代](#🔄 5. 后续维护与迭代)
- [🎉 结语](#🎉 结语)
- - [📝 附录：完整的文件内容参考](#📝 附录：完整的文件内容参考)

🚀 从零开源：如何将自定义 AI Skill 发布到 GitHub

在之前的文章中，我们探讨了如何编写一个高质量的 SKILL.md，让 AI 从"通用助手"变身"领域专家"。但代码写好了，如何分享？如何复用？

GitHub 是管理这些 AI 技能（Skills）的最佳平台。它不仅是一个代码托管地，更是你的技能分发中心。

本文将手把手教你，如何将一个包含核心指令、UI 元数据、参考文档和校验脚本的完整 Skill 项目，规范地上传到 GitHub，并开源给社区使用。

📂 1. 准备你的 Skill 项目结构

在上传之前，我们需要确保本地文件结构清晰、规范。一个成熟的 Skill 不仅仅是一个 Markdown 文件，它应该是一个包含指令、资源和工具的完整文件夹。

假设我们的技能名为 tech-blog-generator（技术博客生成器），其标准目录结构如下：

text 复制代码

tech-blog-generator/
├── SKILL.md                    # [核心] 5.7KB - AI 的执行指令与触发规则
├── README.md                   # [必读] 给人类看的介绍文档（可选但推荐）
├── LICENSE                     # [协议] 开源许可证（如 MIT）
├── .gitignore                  # [忽略] 排除缓存和敏感文件
│
├── agents/                     # UI 展示层
│   └── openai.yaml             # 628B - 技能在界面上的名称、简介和图标配置
│
├── references/                 # 知识库层 (按需加载)
│   ├── style_guide.md          # 1.2KB - 写作风格反模式清单（Anti-Patterns）
│   └── common_pitfalls.md      # 2.6KB - 常见技术坑点汇总
│
└── scripts/                    # 工具层 (确定性执行)
    ├── validate_yaml.py        # 1.6KB - 校验 frontmatter 格式是否合法
    └── count_tokens.py         # 1.4KB - 检查输出长度防止超限

📄 关键文件说明

文件/目录	作用	为什么需要它？
SKILL.md	大脑	包含 Frontmatter (触发条件) 和 Body (执行指令)。AI 仅凭此文件即可工作。
agents/openai.yaml	名片	定义技能在 UI 列表中的显示名称 (`display_name`) 和短描述。通常由脚本生成，保证格式严格合规。
references/	外挂大脑	存放详细的风格指南或领域知识。只有当 AI 需要时才加载，节省上下文窗口 (Token)。
scripts/	机械臂	存放 Python/Bash 脚本。用于执行那些"不能出错"的任务（如格式校验、Token 计数），实现零 Token 成本的确定性操作。

💡 提示：在上传前，请确保根目录下有一个 .gitignore 文件，内容如下，以避免上传 Python 缓存或敏感配置：
text 复制代码
__pycache__/
*.pyc
.env
.DS_Store

🛠️ 2. 在 GitHub 创建仓库

第一步：登录并新建仓库

访问 GitHub.com 并登录，访问不上或者不会注册请搜索相关教程，这里不扩展。
点击右上角的 + 号，选择 New repository。

第二步：填写仓库信息

Repository name : 建议与文件夹名一致，例如 tech-blog-generator。
Description: 一句话介绍，例如："Tech Blog Generator A high-precision OpenClaw skill that transforms source code and documentation into production-ready technical blog posts..."
Visibility : 选择 Public (公开，方便他人 Clone) 或 Private (私有，仅自己用)。
⚠️ 重要 : 不要勾选 "Initialize this repository with a README"。
- 原因：我们本地已经有完善的 README.md 和文件结构了，勾选此项会创建一个空的 README，导致后续推送时产生冲突。

点击 Create repository。

📤 3. 上传文件 (两种方法)

方法 A：网页直接拖拽 (最简单，适合首次上传)

在创建好的仓库页面，找到 "uploading an existing file" 链接。
打开你本地的 tech-blog-generator 文件夹。
全选所有文件和文件夹 (SKILL.md, agents, references, scripts 等)。
将它们直接拖拽到 GitHub 的上传区域。
等待上传进度条完成。
在底部的 Commit changes 区域：
- Commit message : 建议输入 Initial commit: Add full skill structure with scripts and references。其中文意思是：初始提交：添加完整的技能结构，包括脚本和引用
- 点击绿色按钮 Commit changes。

方法 B：Git 命令行 (推荐，适合后续维护)

如果你熟悉终端，这是更专业的方式：

bash 复制代码

# 1. 进入本地项目目录
cd tech-blog-generator

# 2. 初始化 git
git init

# 3. 添加所有文件
git add .

# 4. 提交
git commit -m "Initial commit: Add TechBlogGenerator skill"

# 5. 关联远程仓库 (替换为你自己的用户名和仓库名)
git remote add origin https://github.com/YOUR_USERNAME/tech-blog-generator.git

# 6. 重命名分支为主分支 (可选，视默认设置而定)
git branch -M main

# 7. 推送到 GitHub
git push -u origin main

✅ 4. 验证与使用

上传完成后，你的仓库页面应该能清晰地看到完整的目录结构：

如何安装/使用？

一旦开源，其他人（或你自己在新设备上）可以通过以下方式快速启用该 Skill：

方式一：Git Clone (本地部署)

适用于本地运行的 Agent 框架（如 OpenClaw, Codex CLI 等）：

bash 复制代码

cd ~/my-agent/skills
git clone https://github.com/YOUR_USERNAME/tech-blog-generator.git
# 重启 Agent，自动加载

方式二：直接引用 Raw 链接

部分支持远程 Skill 的工具，可以直接填入 SKILL.md 的 Raw 地址：
https://raw.githubusercontent.com/YOUR_USERNAME/tech-blog-generator/main/SKILL.md

🔄 5. 后续维护与迭代

Skill 不是一次性产物。当你发现 AI 在某些场景下表现不佳，或者想增加新的编程语言支持时：

本地修改 ：编辑 SKILL.md 中的指令，或在 references/ 中补充新知识。
测试脚本 ：运行本地脚本验证格式。
bash 复制代码
```
python scripts/validate_yaml.py .
```

提交更新 ：

bash 复制代码

git add .
git commit -m "Update: Add Python async/await patterns to references"
git push

GitHub 的版本历史功能将帮你记录每一次优化，随时可以回滚到稳定版本。

🎉 结语

通过将 Skill 模块化并托管在 GitHub，你不仅是在保存一段提示词（Prompt），而是在构建一个可复用、可协作、可进化的 AI 能力插件。

现在，去创建你的第一个 Skill 仓库吧！

🔗 项目地址 : github.com/your-username/tech-blog-generator

如果你觉得这个教程有帮助，欢迎 Star ⭐️ 我的仓库！

📝 附录：完整的文件内容参考

为了方便大家抄作业，以下是核心文件的简要内容模板（实际内容请参考前文生成的详细代码）：

SKILL.md (片段)

yaml 复制代码

---
name: tech-blog-generator
description: >-
  Generates technical blogs from code. Use when users upload code files 
  and ask for tutorials or explanations.
---
# Role: Senior Staff Engineer
# Constraints: NO pedagogical tone, NO AI fluff...

agents/openai.yaml (片段)

yaml 复制代码

display_name: Tech Blog Generator
short_description: Turn code into high-quality technical blogs instantly.

scripts/validate_yaml.py (逻辑)
检查 frontmatter 是否包含 name/description，长度是否合规。