piazambuja/github-profile-site

Site pessoal no GitHub Pages

Objetivo: um site pessoal rápido e acessível em https://<conta>.github.io/, construído a partir de um único arquivo de conteúdo que o usuário pode editar, publicado pelo GitHub Actions a cada push para main. Sem framework e sem dependências npm, para que possa ser construído em qualquer lugar.

Funciona para qualquer pessoa, em qualquer área. Escreva o site no idioma do usuário.

Regras rígidas

• O repositório deve ser nomeado exatamente <conta>.github.io, onde <conta> é o nome de usuário do GitHub (ou organização) que o possui, em minúsculas. Apenas esse nome publica na raiz (https://<conta>.github.io/). Qualquer outro nome publica em um subcaminho (https://<conta>.github.io/<repo>/), e um erro de digitação ou um proprietário diferente significa que a URL raiz continua com erro 404. Cada conta tem um desses sites.
• Nunca invente conteúdo. Sem empregadores, datas, cargos, métricas, projetos ou links inventados. Fatos ausentes se tornam um placeholder visível como [ano que você começou] e uma pergunta ao usuário.
• Dados pessoais são públicos uma vez enviados, inclusive no histórico do git. Pergunte antes de publicar número de telefone, endereço residencial, e-mail pessoal ou data de nascimento; prefira cidade/região, um link de contato e LinkedIn. Nunca faça commit de segredos ou arquivos .env.
• Execute comandos que criam ou alteram coisas no GitHub (criar repositório, habilitar Pages, enviar) apenas depois de mostrar ao usuário o que eles farão, na primeira vez. Todo o resto pode seguir em frente.

Pré-requisitos

O GitHub CLI, instalado e logado. Verifique primeiro e corrija o que falhar:

gh --version                        # instalação: https://cli.github.com
gh auth status                      # logado? qual conta? quais escopos?
gh auth login -h github.com -p https -w          # se não estiver logado (fluxo do navegador)
gh auth refresh -h github.com -s workflow        # enviar .github/workflows/* precisa do escopo workflow
gh api user --jq .login             # o nome da conta: o repositório é <isto>.github.io
git --version
node --version                      # 18+; necessário apenas para executar a construção localmente

Se o site pertencer a uma organização, <conta> é o nome da organização e o usuário precisa de permissão para criar repositórios nela (gh repo create <org>/<org>.github.io).

Passo 1: verifique o ponto de partida

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 "o repositório ainda não existe"
gh api "repos/$ACCOUNT/$REPO/pages" 2>/dev/null || echo "Pages não habilitado"

• Repositório existe com um site: pergunte se deve substituí-lo, mantê-lo ou migrar seu conteúdo. Nunca sobrescreva sem um sim.
• Repositório existe com um nome diferente (ex.: portfolio, MyName.github.io em outra conta): ofereça renomeá-lo (gh repo rename <conta>.github.io -R <dono>/<antigo>) em vez de criar um segundo.
• Em um plano gratuito, o repositório deve ser público para que o Pages funcione.

Passo 2: colete o conteúdo (pergunte apenas o que falta, em uma única mensagem)

1. Nome, cargo ou manchete, cidade/região (opcional) e o idioma do site.
2. Duas ou três frases sobre o que fazem e para quem, depois um "sobre" mais longo se quiserem.
3. Experiência ou projetos: título, organização, período, uma ou duas linhas cada. Um currículo, exportação do LinkedIn ou página existente é a fonte mais rápida.
4. Links: GitHub (preenchido automaticamente), LinkedIn, e-mail ou formulário de contato, outros perfis.
5. Aparência em poucas palavras e o que evitar. Sem preferência, use o padrão básico em assets/style.css.

Coloque as respostas em content/profile.json (formato em assets/profile.example.json). Mostre o JSON ao usuário antes de construir e marque cada placeholder.

Passo 3: crie o projeto

Estrutura recomendada (o mesmo layout funciona para qualquer gerador estático):

<conta>.github.io/
  AGENTS.md                    instruções para qualquer agente de código (modelo: assets/AGENTS.md)
  CLAUDE.md -> AGENTS.md       symlink opcional, para o Claude Code ler o mesmo arquivo
  README.md                    como editar, construir e publicar
  content/profile.json         todo o texto do site
  build.mjs                    gerador, apenas Node, sem dependências (assets/build.mjs)
  static/style.css             tokens em :root, modo escuro via prefers-color-scheme
  .github/workflows/deploy.yml construir + fazer deploy para Pages (assets/deploy.yml)
  .gitignore                   dist/ e node_modules/

Copie os arquivos da pasta assets/ desta skill e depois os adapte. scripts/ tem a configuração do repositório usada no passo 4. Mantenha AGENTS.md neutro em relação ao agente: ele descreve o projeto, os comandos e as regras de design, não uma ferramenta específica.

mkdir "$REPO" && cd "$REPO" && git init -b main
mkdir -p content static .github/workflows
# copiar assets/: build.mjs, style.css -> static/, deploy.yml -> .github/workflows/,
#               AGENTS.md, profile.example.json -> content/profile.json
ln -s AGENTS.md CLAUDE.md          # opcional
printf 'dist/\nnode_modules/\n' > .gitignore
node build.mjs && python3 -m http.server 4321 -d dist   # pré-visualizar em http://localhost:4321

Extras opcionais, apenas se o usuário pedir: uma página de projetos, um blog (arquivos Markdown renderizados no momento da construção), um domínio personalizado ou um mercado de plugins/skills no mesmo repositório (.claude-plugin/marketplace.json + plugins/<plugin>/, com o site listando-os; valide com claude plugin validate . quando o Claude Code estiver instalado).

Passo 4: crie o repositório e habilite o Pages

Sempre crie o repositório com gh, nunca digitando o nome na interface web: scripts/create-site-repo.sh pega o nome da conta logada, então é sempre exatamente <conta>.github.io. Execute-o da pasta do site, com --dry-run primeiro e mostre a saída ao usuário:

bash <caminho-da-skill>/scripts/create-site-repo.sh --dry-run      # verifica gh, login, escopos; imprime o que fará
bash <caminho-da-skill>/scripts/create-site-repo.sh                # cria o repositório público, habilita Pages (Actions), define origin
# site de organização:       ... --org <org>
# repositório já existe:     ... --existing   (apenas após verificar com o usuário o que há nele)

Ele para se gh estiver ausente ou não logado, avisa quando o token não tem o escopo workflow e se recusa a tocar em um repositório existente sem --existing. Os mesmos passos manualmente:

gh repo create "$ACCOUNT/$REPO" --public --description "Site pessoal"
gh api -X POST "repos/$ACCOUNT/$REPO/pages" -f build_type=workflow   # PUT se o Pages já existir
git remote add origin "https://github.com/$ACCOUNT/$REPO.git"
gh api "repos/$ACCOUNT/$REPO/pages" --jq '{url: .html_url, source: .build_type}'

A configuração do Pages também está na interface web em Configurações → Pages → Construir e implantar → Origem: GitHub Actions.

Passo 5: faça o deploy

git add -A && git commit -m "Site pessoal"
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      # espere HTTP/2 200; o primeiro deploy pode levar um ou dois minutos

A partir daí, todo push para main reconstrói e publica. gh workflow run deploy.yml faz o deploy sem um commit.

Passo 6: verifique antes de finalizar

• Abra a URL ao vivo, não apenas a pré-visualização local. Links funcionam, sem erro 404 em CSS ou páginas.
• Tire capturas de tela com 1280px e 390px de largura, modo claro e escuro. Sem rolagem horizontal em 390px.
• Teclado: Tab alcança cada link com um anel de foco visível. O contraste do texto atende WCAG AA em ambos os temas.
• <title>, meta description e lang estão definidos; imagens têm alt.
• Nenhum placeholder como [ano] deixado na página publicada, a menos que o usuário tenha optado por mantê-lo por enquanto (então liste-os).

Solução de problemas

Sintoma	Causa e correção
https://<conta>.github.io/ retorna 404, site aparece em /<repo>/	O nome do repositório não é exatamente <conta>.github.io para a conta proprietária. Renomeie: gh repo rename <conta>.github.io.
404 em toda parte após uma execução verde	A origem do Pages ainda é "Implantar a partir de um branch", ou repositório privado em plano gratuito. Reexecute a chamada build_type=workflow; torne o repositório público (gh repo edit --visibility public --accept-visibility-change-consequences).
Push rejeitado: "refusing to allow an OAuth App to create or update workflow"	Token não tem o escopo workflow: gh auth refresh -s workflow.
Job de deploy: "Branch is not allowed to deploy to github-pages"	O ambiente github-pages só permite o branch padrão. Faça deploy a partir de main ou adicione o branch em Configurações → Ambientes.
gh api .../pages retorna 409 ou 422	Pages já existe: use -X PUT em vez de -X POST.
CSS ausente apenas no site ao vivo	Caminhos absolutos assumem a raiz. Para um site de projeto (/<repo>/), prefixe os caminhos com a base; assets/build.mjs faz isso a partir de GITHUB_REPOSITORY.
Versão antiga ainda aparecendo	Cache da CDN, até ~10 minutos. Verifique se a execução terminou e faça uma atualização forçada.

Domínio personalizado (opcional)

gh api -X PUT "repos/$ACCOUNT/$REPO/pages" -f cname=www.exemplo.com
# DNS: CNAME www -> <conta>.github.io ; apex: registros A para os IPs do GitHub Pages (consulte a documentação do GitHub)
gh api -X PUT "repos/$ACCOUNT/$REPO/pages" -F https_enforced=true   # assim que o certificado for emitido

Saída

Finalize com: a URL ao vivo, a URL do repositório, qual arquivo editar para cada tipo de alteração (content/profile.json para texto, static/style.css para aparência), a lista de placeholders ainda abertos e o único comando para pré-visualizar localmente.