Communitygithub.com

piazambuja/github-profile-site

GitHub Pages를 이용해 <account>.github.io 주소로 개인 프로필 또는 포트폴리오 사이트를 생성하고 배포합니다. gh CLI를 사용하여 저장소 생성, JSON 파일 기반 콘텐츠 작성, GitHub Actions를 통한 Pages 활성화, 배포 및 검증까지 수행합니다. 사용자가 개인 사이트, 포트폴리오, 온라인 이력서 또는 username.github.io 페이지를 원할 때 사용하세요.

github-profile-site란 무엇인가요?

이 스킬은 사용자가 GitHub Pages에 개인 프로필 또는 포트폴리오 사이트를 빠르고 정확하게 생성하고 배포할 수 있도록 안내합니다. `piazambuja/github-profile-site`는 gh CLI를 활용하여 저장소 생성, 콘텐츠 수집, 사이트 빌드, GitHub Actions 기반 배포 등의 전체 과정을 자동화합니다. 특히 저장소 이름을 반드시 `<account>.github.io`로 지정해야 하며, 사용자가 직접 수정할 수 있는 단일 JSON 파일(`content/profile.json`)을 기반으로 정적 사이트를 생성합니다. Node.js 18+만 있으면 프레임워크나 npm 종속성 없이 로컬에서도 빌드할 수 있어 누구나 쉽게 사용할 수 있습니다. 이 스킬은 Claude Code, Cursor, Codex 등 모든 AI 에이전트와 호환되도록 설계되었으며, `AGENTS.md` 파일을 통해 프로젝트 구조와 명령어, 디자인 규칙을 설명합니다. 개인 데이터를 커밋하기 전에 사용자 동의를 구하고, 가짜 콘텐츠를 절대 생성하지 않으며, 모든 플레이스홀더를 명확히 표시하는 등 안전하고 윤리적인 사용을 강조합니다. 또한, 사용자 선호도에 따라 프로젝트 페이지, 블로그, 커스텀 도메인, 플러그인 마켓플레이스 등을 추가할 수 있는 확장 기능을 제공합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/piazambuja/piazambuja.github.io/tree/main/plugins/career/skills/github-profile-site
원본 보기→모든 스킬 둘러보기

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

문서

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를 반환합니다. 각 계정은 하나의 이러한 사이트만 가질 수 있습니다.
  • 콘텐츠를 절대 지어내지 마세요. 고용주, 날짜, 직함, 지표, 프로젝트 또는 링크를 허위로 만들지 마세요. 누락된 사실은 [시작한 연도]와 같은 보이는 플레이스홀더와 사용자에 대한 질문으로 표시합니다.
  • 개인 데이터는 푸시되는 즉시 공개됩니다. 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             # 계정 이름: 저장소는 <this>.github.io

git --version
node --version                      # 18+; 로컬 빌드에만 필요

사이트가 조직에 속하는 경우, <account>는 조직 이름이며 사용자는 해당 조직 내 저장소를 생성할 권한이 있어야 합니다 (gh repo create <org>/<org>.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 <account>.github.io -R <owner>/<old>).
  • 무료 플랜에서는 Pages가 작동하려면 저장소가 공개여야 합니다.

2단계: 콘텐츠 수집 (누락된 항목만 한 번에 질문)

  1. 이름, 역할 또는 헤드라인, 도시/지역(선택 사항), 사이트 언어.
  2. 그들이 하는 일과 대상에 대한 두세 문장, 그리고 원하는 경우 더 긴 "소개" 문단.
  3. 경험 또는 프로젝트: 제목, 조직, 기간, 각각 한두 줄. 이력서, LinkedIn 내보내기 또는 기존 페이지가 가장 빠른 소스입니다.
  4. 링크: GitHub (자동으로 채워짐), LinkedIn, 이메일 또는 연락처 양식, 기타 프로필.
  5. 몇 단어로 표현한 디자인 선호도와 피해야 할 사항. 선호도가 없으면 assets/style.css의 기본 스타일을 사용하세요.

답변을 content/profile.json에 넣으세요 (형식은 assets/profile.example.json 참조). 빌드하기 전에 사용자에게 JSON을 보여주고 모든 플레이스홀더를 표시하세요.

3단계: 프로젝트 생성

권장 구조 (모든 정적 생성기에서 동일한 레이아웃으로 작동):

<account>.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/\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 .로 검증).

4단계: 저장소 생성 및 Pages 활성화

항상 gh로 저장소를 생성하고, 웹 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), origin 설정
# 조직 사이트:       ... --org <org>
# 저장소가 이미 존재:     ... --existing   (사용자에게 내용을 확인한 후에만)

gh가 없거나 로그인되지 않은 경우 중단되고, 토큰에 workflow 스코프가 없으면 경고하며, --existing 없이 기존 저장소를 건드리지 않습니다. 동일한 단계를 수동으로 수행하는 방법:

gh repo create "$ACCOUNT/$REPO" --public --description "Personal site"
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 설정은 웹 UI에서 Settings → Pages → Build and deployment → Source: GitHub Actions에서도 확인할 수 있습니다.

5단계: 배포

git add -A && git commit -m "Personal site"
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 예상; 첫 배포는 1-2분 소요될 수 있음

이후 main 브랜치에 푸시할 때마다 다시 빌드되고 게시됩니다. gh workflow run deploy.yml 명령으로 커밋 없이 재배포할 수 있습니다.

6단계: 완료 전 확인

  • 로컬 미리보기뿐만 아니라 라이브 URL을 여세요. 링크가 작동하고, CSS나 페이지에서 404가 없어야 합니다.
  • 1280px 및 390px 너비, 라이트 모드 및 다크 모드에서 스크린샷을 찍습니다. 390px에서 가로 스크롤이 없어야 합니다.
  • 키보드: Tab 키로 모든 링크에 도달할 수 있고 포커스 링이 보여야 합니다. 텍스트 대비가 두 테마 모두에서 WCAG AA를 충족해야 합니다.
  • <title>, 메타 설명 및 lang이 설정되어 있어야 합니다. 이미지에는 alt 속성이 있어야 합니다.
  • 게시된 페이지에 [year]와 같은 플레이스홀더가 남아 있지 않아야 합니다. 단, 사용자가 당분간 유지하기로 선택한 경우 목록으로 표시합니다.

문제 해결

증상원인 및 해결 방법
https://<account>.github.io/에서 404, 사이트가 /<repo>/ 아래에 나타남저장소 이름이 소유 계정의 <account>.github.io와 정확히 일치하지 않음. 이름 변경: gh repo rename <account>.github.io.
녹색 실행 후에도 모든 곳에서 404Pages 소스가 여전히 "Deploy from a branch"이거나, 무료 플랜에서 비공개 저장소인 경우. build_type=workflow 호출을 다시 실행하세요. 저장소를 공개로 만드세요 (gh repo edit --visibility public --accept-visibility-change-consequences).
푸시 거부: "refusing to allow an OAuth App to create or update workflow"토큰에 workflow 스코프가 없음: gh auth refresh -s workflow.
배포 작업: "Branch is not allowed to deploy to github-pages"github-pages 환경은 기본 브랜치만 허용함. main에서 배포하거나 Settings → Environments에서 브랜치를 추가하세요.
gh api .../pages가 409 또는 422 반환Pages가 이미 존재함: -X POST 대신 -X PUT을 사용하세요.
라이브 사이트에서만 CSS 누락절대 경로가 루트를 가정함. 프로젝트 사이트(/<repo>/)의 경우 경로에 base를 접두사로 추가하세요. 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 디자인), 아직 해결되지 않은 플레이스홀더 목록, 로컬 미리보기 명령어.

관련 스킬

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