stargazer-atlas-skill

name	stargazer-atlas-skill
description	Build privacy-preserving GitHub stargazer atlas pages and GitHub Pages deployment workflows. Use when Codex needs to create, refresh, redesign, validate, or publish a repository stargazer map/atlas with aggregate city, school, company, and country counts, README links, and static site assets without publishing raw GitHub user lists.

Stargazer Atlas Skill

Workflow

Use this workflow when a user wants a PaperSpine-like or custom stargazer atlas for a GitHub repository.

1. Identify the target repository, destination site repository, public URL path, README files to link, and desired visual direction.
2. Generate aggregate atlas data with scripts/build_stargazer_atlas.py.
3. Publish only aggregate counts. Never commit raw stargazer logins, avatar URLs, profile URLs, profile JSON, or user lists.
4. Copy or adapt assets/static-page-template/ into the destination site path, then customize copy, colors, typography, map center, and layout.
5. Add or extend a GitHub Pages workflow so the atlas data refreshes before the site build and deploy step.
6. Add README links from the source repository to the published atlas URL.
7. Validate locally, build the site, screenshot the atlas, push, wait for Pages deployment, and verify the live URL returns 200.

Data Script

Run the generator from a repository that has a public output path:

GITHUB_TOKEN=$(gh auth token) python3 /path/to/stargazer-atlas-skill/scripts/build_stargazer_atlas.py \
  --repo OWNER/REPO \
  --output public/REPO_NAME/data.js

Useful options:

• --repo owner/name: GitHub repository to analyze.
• --output path: JavaScript output file; the script writes window.ATLAS=...;.
• --generated-date YYYY-MM-DD: pin a build date for tests or reproducible output.
• --profiles-json path: build from fixture profiles instead of GitHub API.

Validate the generated artifact:

python3 /path/to/stargazer-atlas-skill/scripts/validate_atlas_output.py public/REPO_NAME/data.js

Static Page Template

Use assets/static-page-template/ as the starting point for a standalone atlas page.

• Keep index.html and data.js in the same published directory.
• Keep ECharts loaded from a CDN unless the host project already bundles it.
• Replace placeholder title, subtitle, footer notice, and visual style to match the project.
• Make map controls and ranking tabs functional before publishing.

Reference

Read references/atlas-workflow.md when the task includes GitHub Pages automation, README backlinks, deployment verification, or a redesign request.

Validation Checklist

Before claiming completion:

• data.js starts with window.ATLAS= and contains required aggregate fields.
• No raw user identifiers or profile URLs are present in committed atlas data.
• The site builds successfully.
• A browser screenshot shows a nonblank map, visible rankings, and no obvious overlap.
• The live atlas URL returns HTTP 200 after deployment.
• README links point to the live URL.