piazambuja/github-profile-site

GitHub Pages 个人站点

目标：一个快速、可访问的个人站点，地址为 https://<account>.github.io/，基于一个用户可编辑的内容文件构建，每次推送到 main 分支时通过 GitHub Actions 发布。无框架且无 npm 依赖，因此可以在任何环境中构建。

适用于任何领域的任何人。使用用户的语言编写站点。

硬性规则

• 仓库名称必须完全为 <account>.github.io，其中 <account> 是拥有该仓库的 GitHub 用户名（或组织名），全小写。只有该名称会在根路径（https://<account>.github.io/）发布。任何其他名称都会在子路径（https://<account>.github.io/<repo>/）发布，而拼写错误或其他所有者意味着根 URL 会返回 404。每个账户只有一个这样的站点。
• 切勿编造内容。 不要编造雇主、日期、职称、指标、项目或链接。缺失的事实将变为可见的占位符，如 [year you started]，并向用户提问。
• 个人数据一旦推送即变为公开，包括在 git 历史中。在发布电话号码、家庭地址、个人邮箱或出生日期前先询问；更倾向于使用城市/地区、联系链接和 LinkedIn。绝不提交密钥或 .env 文件。
• 仅在首次向用户展示将要执行的操作后，才运行在 GitHub 上创建或更改内容（创建仓库、启用 Pages、推送）的命令。其余一切操作可以直接进行。

先决条件

GitHub CLI 已安装并登录。首先检查并修复失败项：

gh --version                        # 安装：https://cli.github.com
gh auth status                      # 是否已登录？哪个账户？哪些作用域？
gh auth login -h github.com -p https -w          # 如果未登录（浏览器流程）
gh auth refresh -h github.com -s workflow        # 推送 .github/workflows/* 需要 worklow 作用域
gh api user --jq .login             # 账户名：仓库名为 <此名称>.github.io
git --version
node --version                      # 18+；仅在本地运行构建时需要

如果站点属于组织，则 <account> 为组织名，用户需要具有在该组织中创建仓库的权限（gh repo create <org>/<org>.github.io）。

第一步：检查出发点

ACCOUNT=$(gh api user --jq .login | tr '[:upper:]' '[:lower:]')
REPO="$ACCOUNT.github.io"
gh repo view "$ACCOUNT/$REPO" --json name,visibility,url 2>/dev/null || echo "仓库尚不存在"
gh api "repos/$ACCOUNT/$REPO/pages" 2>/dev/null || echo "Pages 未启用"

• 仓库存在且包含站点：询问是否替换、保留或迁移其内容。未经确认绝不覆盖。
• 仓库名称不同（例如 portfolio、MyName.github.io 属于其他账户）：建议重命名（gh repo rename <account>.github.io -R <owner>/<old>），而不是创建第二个。
• 在免费计划中，仓库必须公开才能使 Pages 正常工作。

第二步：收集内容（仅询问缺失项，一次性发送）

1. 姓名、职位或标题、城市/地区（可选）以及站点语言。
2. 两到三句话说明他们的工作内容和服务对象，如果需要，再写一段更长的“关于我”。
3. 经历或项目：职位、组织、时间段，每个一两行。简历、LinkedIn 导出或现有页面是最快的来源。
4. 链接：GitHub（自动填写）、LinkedIn、邮箱或联系表单、其他个人主页。
5. 用几句话描述外观风格，以及要避免的内容。若没有偏好，使用 assets/style.css 中的简洁默认样式。

将答案放入 content/profile.json（格式见 assets/profile.example.json）。在构建之前向用户展示 JSON，并标记每个占位符。

第三步：创建项目

推荐结构（相同布局适用于任何静态生成器）：

<account>.github.io/
  AGENTS.md                    coding agent 的说明（模板：assets/AGENTS.md）
  CLAUDE.md -> AGENTS.md       可选软链接，使 Claude Code 读取同一文件
  README.md                    编辑、构建和发布方法
  content/profile.json         站点上所有文本内容
  build.mjs                    生成器，仅需 Node，无依赖（assets/build.mjs）
  static/style.css             在 :root 上设置令牌，通过 prefers-color-scheme 实现深色模式
  .github/workflows/deploy.yml 构建 + 部署到 Pages（assets/deploy.yml）
  .gitignore                   dist/ 和 node_modules/

从本技能的 assets/ 文件夹复制文件，然后进行调整。scripts/ 包含步骤 4 中使用的仓库设置脚本。保持 AGENTS.md 与 agent 无关：它描述项目、命令和设计规则，而非特定工具。

mkdir "$REPO" && cd "$REPO" && git init -b main
mkdir -p content static .github/workflows
# 复制 assets/：build.mjs, style.css -> static/, deploy.yml -> .github/workflows/,
#               AGENTS.md, profile.example.json -> content/profile.json
ln -s AGENTS.md CLAUDE.md          # 可选
printf 'dist/\nnode_modules/\n' > .gitignore
node build.mjs && python3 -m http.server 4321 -d dist   # 在 http://localhost:4321 预览

可选附加功能，仅在用户要求时：项目页面、博客（构建时渲染 Markdown 文件）、自定义域名，或同一仓库中的插件/技能市场（.claude-plugin/marketplace.json + plugins/<plugin>/，站点列出它们；安装 Claude Code 后可使用 claude plugin validate . 验证）。

第四步：创建仓库并启用 Pages

始终使用 gh 创建仓库，切勿在 Web UI 中手动输入名称：scripts/create-site-repo.sh 从登录的账户获取名称，因此它始终是准确的 <account>.github.io。在站点文件夹中运行，首先使用 --dry-run 并向用户显示输出：

bash <skill-dir>/scripts/create-site-repo.sh --dry-run      # 检查 gh、登录、作用域；打印将执行的操作
bash <skill-dir>/scripts/create-site-repo.sh                # 创建公开仓库，启用 Pages (Actions)，设置 remote
# 组织站点：       ... --org <org>
# 仓库已存在：     ... --existing   （仅在向用户确认其中内容后）

如果 gh 缺失或未登录，脚本会停止；如果 token 缺少 workflow 作用域则会发出警告；并且如果没有 --existing 标志，则拒绝操作现有仓库。手动执行相同步骤：

gh repo create "$ACCOUNT/$REPO" --public --description "个人站点"
gh api -X POST "repos/$ACCOUNT/$REPO/pages" -f build_type=workflow   # 如果 Pages 已存在则使用 PUT
git remote add origin "https://github.com/$ACCOUNT/$REPO.git"
gh api "repos/$ACCOUNT/$REPO/pages" --jq '{url: .html_url, source: .build_type}'

Pages 设置也位于 Web UI 的设置 → Pages → 构建和部署 → 来源：GitHub Actions。

第五步：部署

git add -A && git commit -m "个人站点"
git push -u origin main
gh run watch "$(gh run list --workflow deploy.yml --limit 1 --json databaseId --jq '.[0].databaseId')" --exit-status
curl -sI "https://$REPO/" | head -1      # 期望 HTTP/2 200；首次部署可能需要一两分钟

此后，每次推送到 main 分支都会重新构建并发布。gh workflow run deploy.yml 可在不提交的情况下重新部署。

第六步：完成前检查

• 打开实时 URL，而不仅仅是本地预览。链接正常工作，CSS 或页面上没有 404。
• 在 1280px 和 390px 宽度下截图，包括浅色和深色模式。在 390px 宽度下无水平滚动。
• 键盘：Tab 键可到达每个链接，并带有可见的聚焦环。文本对比度在两种主题下均符合 WCAG AA 标准。
• 已设置 <title>、meta 描述和 lang；图片带有 alt 属性。
• 已发布的页面中不留有 [year] 等占位符，除非用户选择暂时保留（此时列出它们）。

故障排除

症状	原因和修复方法
https://<account>.github.io/ 返回 404，站点出现在 /<repo>/ 下	仓库名称不是拥有账户的 <account>.github.io。重命名：gh repo rename <account>.github.io。
绿色运行后到处是 404	Pages 来源仍为“从分支部署”，或免费计划上的私有仓库。重新运行 build_type=workflow 调用；将仓库设为公开（gh repo edit --visibility public --accept-visibility-change-consequences）。
推送被拒绝：“refusing to allow an OAuth App to create or update workflow”	Token 缺少 workflow 作用域：gh auth refresh -s workflow。
部署作业：“Branch is not allowed to deploy to github-pages”	github-pages 环境只允许默认分支。从 main 部署，或在设置 → 环境中添加分支。
gh api .../pages 返回 409 或 422	Pages 已存在：使用 -X PUT 而不是 -X POST。
仅实时站点上缺少 CSS	绝对路径假定根路径。对于项目站点（/<repo>/），为路径添加基础前缀；assets/build.mjs 从 GITHUB_REPOSITORY 处理此问题。
仍显示旧版本	CDN 缓存，最多约 10 分钟。检查运行是否完成并硬刷新。

自定义域名（可选）

gh api -X PUT "repos/$ACCOUNT/$REPO/pages" -f cname=www.example.com
# DNS：CNAME www -> <account>.github.io ; apex：A 记录指向 GitHub Pages IP 地址（参见 GitHub 文档）
gh api -X PUT "repos/$ACCOUNT/$REPO/pages" -F https_enforced=true   # 证书颁发后

输出

最后输出：实时 URL、仓库 URL、每种更改对应的编辑文件（文本修改 content/profile.json，样式修改 static/style.css）、仍然存在的占位符列表，以及本地预览的一条命令。