将本地项目发布到 GitHub：Skills 仓库 publish-project-to-github 技能全流程实战指南-平芜编程栈

【免费下载链接】Skills

Agent skills for designers and builders using Codex, Claude, Cursor, and other AI coding agents

项目地址：https://gitcode.com/gh_mirrors/skills48/Skills

导读

本文围绕 Skills 仓库（面向 Codex、Claude、Cursor 等 AI 编码 Agent 的 Agent skills 集合）中的publish-project-to-github技能，完整讲解如何把一个已完成的本机 HTML/CSS/JavaScript 实验或小型 Web 项目，打包成意图明确的 Git 仓库、创建公开或私有的 GitHub 仓库、编写有说服力的 README 与真实预览图、安全推送、为兼容项目配置 GitHub Pages 公开站点，并在推送与部署之后回读验证外部状态。读完本文，你将掌握一套可复用的"发布前审计 → 本地验证 → 安全推送 → Pages 配置 → 外部状态回读"的发布管线，并理解其底层审计脚本与 Pages 参考文档的实现细节。

该技能在仓库中的位置为 agent-skills/codex/publish-project-to-github/SKILL.md，配套资源包括审计脚本、GitHub Pages 参考文档、README 模板以及 Agent 接口定义。

技能定位与核心原则

publish-project-to-github的触发场景非常明确：当用户提出上传、发布、开源、分享，或把一个本地 HTML/CSS/JavaScript 实验转成带在线演示的 GitHub 仓库时，Agent 应加载并使用本技能。其description字段明确定义了使用边界——面向"已完成"的本地小项目，输出物是"带文档与实时演示的 GitHub 仓库"。

本技能最核心的设计理念是一条总纲：

把仓库创建、公开可见性和部署当作三扇相互独立的门：一次成功的git push并不能证明公开站点可用。

也就是说，"推送成功"、"Pages 已配置"、"Pages 构建成功"、"线上站点已核验"是四个层次不同的状态，任何一步都不能被上一步的结果替代。技能要求 Agent 在交付时明确区分这四种状态，绝不把它们折叠成一个笼统的"发布成功"。

另一个贯穿全文的准则是最小权限：创建公开仓库必须得到用户明确授权（用户明确提出公开分享、公开 URL、开源或等价表述）；未获明确授权时，默认使用--private；严禁 force-push、覆盖既有远程、擅自更改仓库可见性或替换已有 Pages 配置。

第 1 步：确定范围与权限

发布前不要急于写代码，先检查本地项目、仓库状态、远程与本地指令，确认或谨慎推断以下事项：

确切的项目目录与预期纳入的文件清单；
仓库名称（Repository）与所有者（Owner）；
目标是公开还是私有；
是更新既有仓库，还是新建仓库；
用户想要的是在线网站、仅源码托管，还是两者都要。

技能同时给出两条不可逾越的红线：

只有用户明确要求公开分享、公开 URL 或开源时，才允许创建公开仓库；否则在创建前必须先询问可见性偏好；
未经确切授权，绝不 force-push、绝不覆盖既有远程、绝不更改仓库可见性、绝不替换已有 Pages 配置。

第 2 步：发布前审计（Audit）

运行捆绑审计脚本

在项目根目录运行仓库捆绑的审计脚本，命令为：

bash agent-skills/codex/publish-project-to-github/scripts/audit_public_project.sh .

注意原文档使用/path/to/publish-project-to-github/scripts/audit_public_project.sh作为占位路径，在 Skills 仓库中该脚本的实际相对路径为 scripts/audit_public_project.sh。脚本接受一个可选参数作为项目目录（默认为.），因此从项目根目录运行时传.即可。

技能强调：脚本是辅助而非替代判断。运行后必须人工检查其输出，而不是把脚本退出码当作唯一依据。

审计脚本的源码级实现

阅读 audit_public_project.sh 的源码可以发现，它是一段set -euo pipefail的严格 Bash 脚本，依赖ripgrep（rg）完成文件扫描，整个审计分五个维度：

1. 入口点识别。若根目录存在index.html，判定入口点为静态首页；若存在package.json，判定为框架构建项目并提示"验证构建产物与宿主兼容性"；两者都不存在时输出 WARNING。

2. 敏感文件扫描。脚本用 ripgrep 枚举全部隐藏文件（排除.git），匹配以下模式即为 ERROR：

(^|/)(\.env($|\.)|\.npmrc$|\.pypirc$|id_(rsa|dsa|ecdsa|ed25519)$|.*\.(pem|p12|pfx|key)$)

即.env系列、.npmrc、.pypirc、SSH 私钥（id_rsa、id_dsa、id_ecdsa、id_ed25519）以及.pem、.p12、.pfx、.key证书密钥文件，命中即要求移除或明确审查。

3. 凭据内容扫描。对文件内容做正则匹配，排除.git、*.lock、package-lock.json、pnpm-lock.yaml、yarn.lock等锁文件：

(sk-[A-Za-z0-9_-]{20,}|gh[pousr]_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|-----BEGIN (RSA |OPENSSH |EC |DSA )?PRIVATE KEY-----)

该模式覆盖 OpenAI 风格sk-密钥、GitHub 个人访问令牌（ghp_/gho_/ghu_/ghs_/ghr_前缀）、AWSAKIA访问密钥 ID 以及 PEM 私钥块，任何命中都会使审计计为 ERROR。

4. 个人路径扫描。匹配绝对用户路径（/Users/...、/home/...、WindowsC:\Users\...），命中输出 WARNING 要求审查。

5. Git 状态检查。若目录已在 Git 工作树内，进一步检查项目是否嵌套在更大的仓库根目录中（此时提示 WARNING）、列出git status --short、读取origin远程 URL；未初始化则提示 "Git state: not initialized"。

脚本末尾汇总Issues与Warnings计数：Issues > 0时输出RESULT: blocked并以退出码 1 终止发布；否则输出RESULT: review warnings, then continue，提示先人工复核警告项再继续。

人工审查清单

即便脚本通过，技能仍要求人工把关以下发布阻断项：

API 密钥、令牌、私钥、密码或.env文件；
个人数据或私密客户信息；
运行期依赖的绝对本地文件系统路径；
未授权或无许可证的素材（assets）；
缺失的运行期文件；
对已存在仓库名的所有权不明确。

此外，需逐一审查所有外部运行时 URL 与生成素材，并在 README 中如实声明项目所需的网络依赖。

许可证检查

发布前检查既有许可证。若用户明确希望他人复用或修改该项目且项目尚无许可证，应询问用户选择哪种许可证，而不是替用户发明一个；若目标仅是公开浏览，缺少许可证不阻断部署，但必须在报告中说明"复用权利未被显式授予"。

第 3 步：选择打包模型

技能针对三种典型场景给出不同的打包策略：

干净既有仓库（Clean existing repository）：当既有 checkout 的远程、历史与被跟踪文件与目标公开项目一致时，直接复用该 checkout，只暂存（stage）请求的文件。

混杂或不相关的 workspace（Mixed or unrelated workspace）：当源工作区含有无关实验、删除、私有文件或历史时，创建一个干净的项目目录或同级 checkout，只拷贝预期的运行文件，绝不为图方便把整个混杂文件夹一并发布。

既有公开仓库（Existing public repository）：改动前先检查其默认分支、Pages 来源、README、许可证与远程状态；拉取或审慎协调分歧，绝不用 force push 掩盖分歧。

对于静态单文件实验，技能给出了一个推荐的极简目录形态：

project-name/ ├── index.html ├── README.md ├── PROMPT.md # optional ├── assets/ # optional previews or runtime assets └── .gitignore

第 4 步：构建仓库展示（README 与预览）

README 必须从真实项目出发编写，而不是套模板。技能提供了 assets/README-template.md 作为起始结构而非最终成稿，模板中所有占位符（PROJECT_NAME、ONE_SENTENCE_DESCRIPTION、PUBLIC_URL、REPOSITORY_URL、PROJECT_PREVIEW.jpg等）都必须基于项目证据逐一改写。

一份合格的 README 应包含：

项目名称 + 一句具体描述体验的话；
顶部附近放在线演示链接，在 GitHub 之外有用时再放仓库源码链接；
从实际运行项目截取的截图或短 GIF；
关键交互或特性；
对架构与非常规实现选择的简洁解释；
准确可运行的本地运行说明；
项目结构；
运行时依赖与网络要求；
当作品受参考启发时，注明原创性、署名或非关联声明。

针对 Agent 构建的项目，可选用官方链接与可移植的构建/混搭 prompt，展示如何用相关编码 Agent 重建或改造成该项目——但发布前必须核验官方 URL 仍有效。

模板中## How it is made一节要求用两三个短段落讲清真实架构：运行时、主要依赖、非常规实现选择、事实来源在哪里；## Build or remix it一节在有用时链接可移植 prompt；## Run locally一节必须给出确切的运行命令、所需版本、安装步骤、环境变量与网络依赖，且绝不包含真实密钥；## Design and attribution一节要求准确署名依赖、参考与素材，若项目研究了某个可识别的产品或发行方，应说明实现是原创且独立的，而非暗示隶属关系。

写作基调上，技能明确要求避免空洞宣传词（如 "cutting-edge"、"stunning"、"production-ready"），优先用具体工艺与行为说话。

第 5 步：本地验证（Verify locally）

启动真实运行时

使用项目的真实运行时而非直接从磁盘打开基于模块的站点（即不要用file://打开，这无法证明 Pages 兼容性）。对静态站点，技能给出的命令是：

python3 -m http.server 4173 --bind 127.0.0.1

验证清单

启动后在浏览器中逐项检查：

初始渲染；
主要交互路径；
主要交互的返回、关闭或恢复路径；
常规桌面视口，以及当项目为响应式时，约390 × 844的窄视口；
README 中的每一条运行命令；
缺失文件与 404；
控制台错误与警告；
仓库子路径下的相对 URL，例如/project-name/。

使用的浏览器以用户要求或仓库指令为准，README 预览图必须从该已验证的运行时截取。

第 6 步：提交并创建仓库

前置检查：GitHub CLI

要求已安装 GitHub CLI（gh）并完成认证：

gh --version gh auth status

名称可用性检查

创建前先检查目标名称是否已被占用：

gh repo view OWNER/REPOSITORY

初始化与提交

只初始化并提交预期打包内容：

git init -b main git add -- README.md index.html .gitignore git diff --cached --check git commit -m "Publish PROJECT_NAME"

git diff --cached --check用于检查暂存区是否存在空白错误。可选文件应显式追加到git add命令中，而不是在混杂目录树里用git add -A取而代之。

创建并推送

审计与本地验证全部通过后，才允许创建并推送：

gh repo create OWNER/REPOSITORY \ --public \ --source=. \ --remote=origin \ --push \ --description "CONCRETE_DESCRIPTION"

要点：

未获公开授权时使用--private；
仓库已存在时，应显式配置其远程并直接推送，而不是重新创建；
--description必须填具体描述，而不是空泛口号。

第 7 步：配置公开站点（GitHub Pages）

按项目类型分类

启用 Pages 前先对项目分类，四类情况对应四种处理：

静态根目录（Static root）：发布main分支与/目录；
静态 docs 目录（Static docs folder）：发布main分支与/docs目录；
框架构建（Framework build）：使用框架官方支持的 Pages 产物形态与当前官方 GitHub Actions 指南；
服务端、数据库或私有运行时：GitHub Pages 不兼容——必须说明阻塞原因，且只有获得用户授权才能改用其他托管方案。

改动 Pages 设置之前，先阅读 references/github-pages.md。配置完成后，将仓库 homepage 设为最终公开 URL，并添加一组小而准确的发现话题（topics）。

Pages 参考文档的源码级细节

github-pages.md 给出了直接用gh api操作 Pages 的完整命令序列。

新建静态根部署：

project_repo="OWNER/REPOSITORY" project_branch="main" gh api --method POST "repos/${project_repo}/pages" \ -f "source[branch]=${project_branch}" \ -f 'source[path]=/'

在将括号视为 glob 的 shell 中，必须为source[...]参数加引号。

部署到/docs（仅当该目录包含完整可部署站点时）：

gh api --method POST "repos/${project_repo}/pages" \ -f "source[branch]=${project_branch}" \ -f 'source[path]=/docs'

Pages 已存在时：先读取当前配置，仅当用户授权更改来源时才使用 PUT 更新端点：

gh api "repos/${project_repo}/pages" gh api --method PUT "repos/${project_repo}/pages" \ -f "source[branch]=${project_branch}" \ -f 'source[path]=/'

仓库元数据：Pages 接受配置后，把公开 URL 设为仓库 homepage，并只添加准确的 topics——六个聚焦的 topics 远比一长串泛泛标签有用：

project_url="https://OWNER.github.io/REPOSITORY/" gh repo edit "${project_repo}" --homepage "${project_url}"

构建状态回读：

gh api "repos/${project_repo}/pages/builds/latest" \ --jq '{status,commit,updated_at,error}'

轮询应采用短且有界的时间间隔，在built、errored或canceled状态时停止，绝不让无限循环空转。built之后还要核验部署的 commit 与本地预期 commit 一致。

仓库子路径陷阱：项目站点从https://OWNER.github.io/REPOSITORY/提供服务，而非域名根。因此必须优先使用相对资源 URL：

<link rel="stylesheet" href="./styles.css"> <script type="module" src="./app.js"></script> <img src="./assets/preview.jpg" alt="">

而根相对 URL（如/assets/preview.jpg）会解析到OWNER.github.io根，在项目站点上几乎必然失效。深链、模块导入、worker、manifest、字体与 fetch 请求都可能存在同样的 base-path 问题，需逐一测试。

框架项目：不要粘贴一份过时的通用 Actions workflow。先识别框架，再对照其当前的官方 Pages 部署指南，至少核验：正确的构建命令、产物输出目录、仓库子路径或 base URL 配置、官方 Pages artifact action 版本，以及是否需要 SPA fallback 路由。对 Next.js、Astro、Vite 等框架，使用其支持的静态导出或 Pages adapter；若应用需要服务端函数、数据库、认证回调或密钥级运行时变量，Pages 就不是兼容的部署目标。

常见故障排查（参考文档专列四类）：

配置后立即 404：等待最新构建达到终态；确认配置的源目录中存在index.html；确认配置的分支存在于远程；确认仓库可见性与账号的 Pages 可用性。
HTML 能加载但资源失败：检查网络与控制台错误；将根相对路径替换为仓库感知的相对路径；精确核对大小写（GitHub 主机大小写敏感）；确认大文件或生成资产已被提交并推送。
模块 MIME 或 import 错误：确认被引用文件存在于部署 URL；不要 import 本地文件系统路径；使用浏览器兼容的 ES modules，而非需要打包器的包名。
自定义域名问题：未经明确授权不得添加或更改自定义域名；按当前官方文档核验 DNS 归属；域名验证通过后保持强制 HTTPS 开启。

第 8 步：验证外部状态（Read back）

推送与部署都是外部写入，不能用 CLI 成功退出码作为唯一验证手段。技能要求回读所有外部变更：

gh repo view OWNER/REPOSITORY \ --json nameWithOwner,url,visibility,description,homepageUrl,defaultBranchRef gh api repos/OWNER/REPOSITORY/pages gh api repos/OWNER/REPOSITORY/pages/builds/latest

等到 Pages 构建报告built或具体地失败之后，打开公开 URL 核验：

最终 HTTPS URL 上 HTTP 导航成功；
预期的项目 UI 出现；
一个代表性交互能改变主应用状态并干净地返回或关闭；
资产在仓库子路径下正确解析；
无浏览器错误或警告；
README 中的链接均可解析。

若公开页面是用户要求的交付物，应保持页面打开供用户查看。

第 9 步：交付精确结果

交付时需明确返回：

仓库 URL；
公开站点 URL（若已创建）；
commit 与分支；
Pages 构建状态；
实际运行过的检查项；
仍存在的依赖、许可或部署限制。

核心要求是区分四种状态："已推送"（pushed）、"Pages 已配置"（Pages configured）、"Pages 已构建"（Pages built）、"线上站点已核验"（live site verified），绝不把它们合并成一个笼统的成功声明。

失败规则（Failure rules）

技能以一组硬性失败规则收束边界，Agent 在整条管线中必须遵守：

保留无关的脏工作与历史，不因发布而破坏；
不发布密钥；若密钥已被提交，任何推送前必须先将其从历史中移除；
当本地上下文无法确定 GitHub owner 或既有仓库目标时，不臆测；
不用file://预览来声称 Pages 兼容性；
不用 CLI 成功退出码作为外部写入的唯一验证；
当 Pages 不兼容时，不静默改用其他宿主。

资源清单与总结

publish-project-to-github技能文件夹在仓库中的结构如下：

agent-skills/codex/publish-project-to-github/ ├── SKILL.md # 技能主文档（frontmatter + 九步流程 + 失败规则） ├── agents/openai.yaml # Agent 接口定义（display_name、short_description、default_prompt） ├── scripts/audit_public_project.sh # 发布前审计脚本 ├── references/github-pages.md # GitHub Pages 配置与排障参考 └── assets/README-template.md # README 起始模板

三条核心用法：

打包或发布前先运行 scripts/audit_public_project.sh；
配置或排查 Pages 前先读 references/github-pages.md；
从 assets/README-template.md 拷贝结构，并用项目证据重写每一个占位符。

本技能与 Skills 仓库的整体哲学一脉相承：技能是"操作规程"（operating procedures）——明确何时使用、先做什么、采用什么默认值、避免哪些错误。publish-project-to-github正是这一哲学的落地：把"打包 → 审计 → 本地验证 → 推送 → 部署 → 回读核验"这条极易出错的发布路径固化成可复用的九步流程，让 Agent 在每次发布时都能稳定产出干净、安全、可验证的公开交付物。对设计师与开发者而言，它把"发布一个开源项目"从一次性冒险，变成了一道带审计门禁、带部署核验的标准流水线。