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

---

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

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

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

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

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

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

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

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 缓存或敏感配置：

__pycache__/
*.pyc
.env
.DS_Store

---

🛠️ 2. 在 GitHub 创建仓库

第一步：登录并新建仓库

1. 访问 GitHub.com 并登录，访问不上或者不会注册请搜索相关教程，这里不扩展。
2. 点击右上角的 + 号，选择 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：网页直接拖拽 (最简单，适合首次上传)

1. 在创建好的仓库页面，找到 “uploading an existing file” 链接。

   

   

2. 打开你本地的 tech-blog-generator 文件夹。

3. 全选 所有文件和文件夹 (SKILL.md, agents, references, scripts 等)。

4. 将它们直接拖拽到 GitHub 的上传区域。

   

5. 等待上传进度条完成。

6. 在底部的 Commit changes 区域：

   • Commit message: 建议输入 Initial commit: Add full skill structure with scripts and references。其中文意思是：初始提交：添加完整的技能结构，包括脚本和引用
   • 点击绿色按钮 Commit changes。
   • 

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

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

# 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 等）：

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 在某些场景下表现不佳，或者想增加新的编程语言支持时：

1. 本地修改：编辑 SKILL.md 中的指令，或在 references/ 中补充新知识。
2. 测试脚本：运行本地脚本验证格式。

   python scripts/validate_yaml.py .
   

3. 提交更新：

   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 (片段)

---
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 (片段)

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

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