Communitygithub.com

piazambuja/github-profile-site

建立並發佈個人簡介或作品集網站到 GitHub Pages 的 <account>.github.io，使用 gh CLI 管理儲存庫、從 JSON 檔案產生內容、透過 GitHub Actions 部署與檢查。當使用者想要個人網站、作品集、線上履歷或 username.github.io 頁面時使用。

github-profile-site 是什麼？

這項技能的作用是為使用者在 GitHub Pages 上快速建立並發佈一個個人網站，網址為 `https://<帳號>.github.io/`。它從一個 JSON 內容檔案（`content/profile.json`）產生靜態網站，並透過 GitHub Actions 在每次推送至 `main` 分支時自動建置與部署，過程中不需任何框架或 npm 相依性。該技能支援 GitHub CLI（gh）進行儲存庫建立、Pages 啟用與推播，並包含詳細的步驟：檢查起始狀態、收集使用者內容、建立專案結構、建立儲存庫並啟用 Pages，以及最終部署與檢查。此外，它還明確要求儲存庫名稱必須完全符合 `<帳號>.github.io`，並嚴格禁止編造任何內容，以確保網站正確發佈於根路徑，同時保護使用者隱私。這項技能特別適合想要快速建立個人簡介、作品集或線上履歷的開發者或任何領域的使用者。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/piazambuja/piazambuja.github.io/tree/main/plugins/career/skills/github-profile-site
查看原文→瀏覽所有技能

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

說明文件

GitHub Pages 個人網站

目標：一個快速、易於存取的個人網站，位於 https://<帳號>.github.io/，由一個使用者可編輯的內容檔案建置，每次推送至 main 分支時由 GitHub Actions 自動發佈。無需框架或 npm 相依性，因此可在任何環境建置。

適用於任何人、任何領域。以使用者的語言編寫網站。

嚴格規則

  • 儲存庫名稱必須完全符合 <帳號>.github.io，其中 <帳號> 是擁有該儲存庫的 GitHub 使用者名稱（或組織名稱），並使用小寫。只有這個名稱才能在根路徑 (https://<帳號>.github.io/) 發佈。任何其他名稱都會在子路徑 (https://<帳號>.github.io/<儲存庫>/) 下發佈，而拼寫錯誤或不同的擁有者會導致根 URL 顯示 404。每個帳號只能有一個這樣的網站。
  • 絕不虛構內容。 不得編造雇主、日期、職稱、指標、專案或連結。遺漏的事實應顯示為可見的佔位符號，例如 [您開始的年份]，並向使用者提問。
  • 個人資料一旦推送即為公開，包括在 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/* 需要 workflow 權限範圍
gh api user --jq .login             # 帳號名稱：儲存庫名稱為 <此名稱>.github.io
git --version
node --version                      # 18+；僅需用於在本機執行建置

如果網站屬於某個組織，則 <帳號> 為組織名稱，且使用者需要有在該組織中建立儲存庫的權限 (gh repo create <組織>/<組織>.github.io)。

步驟 1：檢查起始點

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 <帳號>.github.io -R <擁有者>/<舊名稱>) 而非建立第二個儲存庫。
  • 在免費方案中，儲存庫必須設為公開才能使用 Pages。

步驟 2：收集內容（僅詢問缺少的部分，在單一訊息中完成）

  1. 姓名、職稱或標題、城市/地區（選填），以及網站語言。
  2. 兩到三句話說明他們的工作內容和服務對象，如果他們想要，再加一段較長的「關於我」。
  3. 經歷或專案：職稱、組織、期間，每個一到兩行。履歷、LinkedIn 匯出或現有頁面是最快的來源。
  4. 連結：GitHub（自動填入）、LinkedIn、電子郵件或聯絡表單、其他個人檔案。
  5. 用幾個詞描述外觀風格，以及任何要避免的設計。若無偏好，則使用 assets/style.css 中的樸素預設樣式。

將答案放入 content/profile.json 中（結構請見 assets/profile.example.json）。在建置前向使用者展示 JSON，並標記所有佔位符號。

步驟 3：建立專案

建議的結構（相同佈局適用於任何靜態產生器）：

<帳號>.github.io/
  AGENTS.md                    給任何程式碼代理的說明（模板：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 的代理中立性：它描述的是專案、指令和設計規則，而非特定工具。

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/
node_modules/
' > .gitignore
node build.mjs && python3 -m http.server 4321 -d dist   # 預覽於 http://localhost:4321

選擇性額外功能，僅在使用者要求時加入：專案頁面、部落格（在構建時渲染 Markdown 檔案）、自訂網域，或同一個儲存庫中的外掛/技能市集 (.claude-plugin/marketplace.json + plugins/<外掛>/，由網站列出這些外掛；安裝 Claude Code 時，可使用 claude plugin validate . 進行驗證)。

步驟 4：建立儲存庫並啟用 Pages

務必使用 gh 建立儲存庫，切勿在網頁介面中手動輸入名稱：scripts/create-site-repo.sh 會從已登入的帳號取得名稱，因此它永遠會是正確的 <帳號>.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）、設定 origin
# 組織網站：       ... --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 設定也位於網頁介面的 設定 → Pages → 建置與部署 → 來源：GitHub Actions。

步驟 5：部署

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 可在不提交新變更的情況下重新部署。

步驟 6：完成前檢查

  • 開啟正式上線的 URL，而不僅是本機預覽。連結可正常運作，CSS 或頁面無 404 錯誤。
  • 分別在 1280px 和 390px 寬度下、淺色和深色模式下截圖。在 390px 寬度下無水平捲動。
  • 鍵盤：Tab 鍵可到達每個連結，並帶有可見的焦點環。兩種主題下的文字對比度皆符合 WCAG AA 標準。
  • 已設定 <title>、meta 描述和 lang 屬性；圖片附有 alt 屬性。
  • 發佈的頁面中沒有遺留像 [year] 這樣的佔位符號，除非使用者選擇暫時保留（此時請列出這些佔位符號）。

疑難排解

症狀原因與解決方案
https://<帳號>.github.io/ 顯示 404，網站出現在 /<儲存庫>/ 下對於擁有該儲存庫的帳號而言，儲存庫名稱並非完全符合 <帳號>.github.io。重新命名：gh repo rename <帳號>.github.io。
綠燈通過後仍處處 404Pages 來源仍為「從分支部署」，或是免費方案下的私有儲存庫。重新執行 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 或 422Pages 已存在：使用 -X PUT 而非 -X POST。
僅在正式上線網站中 CSS 遺失絕對路徑假設網站位於根目錄。對於專案網站 (/<儲存庫>/)，需為路徑加上基底前綴；assets/build.mjs 會從 GITHUB_REPOSITORY 自動處理此問題。
仍顯示舊版本CDN 快取，最多約 10 分鐘。確認工作流程執行完畢後，進行強制重新整理。

自訂網域（選擇性）

gh api -X PUT "repos/$ACCOUNT/$REPO/pages" -f cname=www.example.com
# DNS：CNAME www -> <帳號>.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）、仍開放的佔位符號清單，以及本機預覽的單一指令。

相關技能

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community