Claude Cursor Skill

create-gh-pages-site

Scaffold a working GitHub Pages website from a vetted template and wire it to deploy automatically. Use when the user wants to create, scaffold, or publish a site on GitHub Pages: a reviewable VitePress specification, a static page, an Astro or Eleventy site, a React (Vite) SPA,

LLM Mart · 0 points · 5 views 0 listing impressions 0 install-command copies
Download jongio-skills-skills_create-gh-pages-site-5345f8c.zip · 317 KB

Install

skills CLI npx skills add https://github.com/jongio/skills/tree/main/skills/create-gh-pages-site
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install jongio-skills@llmmart
Git git clone https://github.com/jongio/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole jongio/skills collection as a plugin from our marketplace. Git is the plain clone.

README

create-gh-pages-site

Scaffold a working GitHub Pages website from a vetted template and wire it to deploy automatically — packaged as a GitHub Copilot skill.

Pick a template (static, Astro, React + Vite, Eleventy, Jekyll, or skills catalog); the skill injects the correct base path for your repo, adds the current official GitHub Actions Pages workflow, drops it into your repo (the current repo by default, or a new one), and tells you how to turn Pages on.

It doesn't stop at the template's demo content, either: it digests your repo (README, manifests, entry points, docs) and authors a site that's actually about your project — a CLI reference, an API/usage page, a feature tour, or a catalog of parts — and drops in labeled image placeholders you swap for real art.

Quickstart

1. Install the skill:

npx skills add jongio/skills --skill create-gh-pages-site

2. Reload skills — run /skills reload, or start a new session.

3. Ask Copilot to build a site:

/create-gh-pages-site put this repo on GitHub Pages as an Astro blog

By default the agent scaffolds for the repo you're in — it reads the current repo from git, picks the astro template, sets site/base for it, lays down the deploy workflow, and shows you how to enable Pages. Name a different repo (octocat/blog) only when you want one.

Why this exists

GitHub Pages' hard parts aren't the HTML — they're the deploy plumbing and the base-path trap: a project site lives at https://USER.github.io/REPO/, so a site built for / ships with broken assets and links. Every framework fixes this differently (Astro base, Vite base + 404.html, Eleventy pathPrefix, Jekyll baseurl). This skill gets all of it right, every time.

Templates

Template Use it for Base path Build
static-html landing pages, a few hand-made pages relative URLs (immune) none
astro content sites, blogs, docs, marketing base in astro.config.mjs astro build
react-vite interactive SPAs / dashboards base + 404.html fallback vite build
eleventy data/Markdown-driven sites pathPrefix via env + url filter eleventy
jekyll GitHub-native / existing Jekyll baseurl in _config.yml Jekyll
skills-catalog browsable catalogs for Copilot skills repositories template base helper registry-defined

The built-in registry pin includes skills-catalog. Custom registries require a full --registry-ref, and local checkouts use --templates-dir.

All templates deploy via the GitHub Actions Pages source. Every external action must be pinned to a full commit SHA, checkout must disable persisted credentials, and install steps must disable lifecycle scripts. No gh-pages branch is used. Workflow scanning accepts a conservative block-style YAML subset and rejects quoted keys, tags, anchors, aliases, merge keys, and unsupported flow mappings.

Browse them in the live gallery with previews, hosted from the jongio/gh-pages-templates registry.

Tailored to your repo, not a demo

A stamped template is a skeleton, not the deliverable. After stamping, the skill reads your repo and rewrites the content to match it:

  • scripts/digest-repo.mjs analyzes the repo and classifies it — cli, library, app, action, collection, docs, or site — and pulls out the name, pitch, install commands, README usage examples, badges, docs, existing images, and sub-projects. That drives which kind of site gets built: a command reference for a CLI, an API/usage page for a library, a feature tour for an app, a catalog for a monorepo.
  • scripts/make-placeholder.mjs drops labeled placeholder images (logo, social card, hero, screenshots) into the site plus an IMAGES.md checklist telling you what to supply and at what size. Real images the repo already has are reused instead.
node scripts/digest-repo.mjs --dir . --json          # see what the author sees
node scripts/make-placeholder.mjs --out site/public/images --preset cli --repo octocat/mytool

Use it

Once installed, describe the site you want:

/create-gh-pages-site a docs site with Eleventy in a new repo called octocat/docs
/create-gh-pages-site put this folder of HTML on Pages

You don't have to name the skill — the agent routes to it whenever you ask to create or publish a GitHub Pages site.

Build it yourself (no agent)

The generator stamps the same site the skill uses. Templates are fetched from the jongio/gh-pages-templates registry at an immutable commit, so it needs git + network unless you pass --templates-dir. The built-in registry uses a reviewed pinned commit. A custom registry requires --registry-ref with its full 40-character commit SHA:

Free-form metadata is limited to context-safe text because the same sentinel can appear in HTML, JSON, YAML, and JavaScript. Markup, control characters, and context-breaking quotes are rejected instead of being copied into generated code.

# Scaffold for the CURRENT repo (base path read from its origin remote):
node scripts/new-site.mjs astro

# An Astro site for a specific project repo (base = /blog/):
node scripts/new-site.mjs astro --repo octocat/blog --site-name "Octocat's Blog"

# A React SPA:
node scripts/new-site.mjs react-vite --repo octocat/dashboard

# A user site (served from "/") or a quick local scaffold:
node scripts/new-site.mjs static-html --base / --dir ./site

# Offline, from a local registry checkout:
node scripts/new-site.mjs astro --templates-dir ../gh-pages-templates/templates

# A custom registry is always commit-pinned:
node scripts/new-site.mjs skills-catalog --repo octocat/skills \
  --author "Octo Cat" --marketplace-id octocat-skills --default-branch trunk \
  --registry octocat/templates --registry-ref 0123456789abcdef0123456789abcdef01234567

# List templates:
node scripts/new-site.mjs --list

Safe staging for composition

create-skills-repo and other generators should stage the site instead of writing into their target:

node scripts/new-site.mjs skills-catalog \
  --repo octocat/skills \
  --templates-dir ../gh-pages-templates/templates \
  --staging-dir ./.site-staging \
  --json

The staging contract is fail-closed:

  1. --staging-dir must name a path that does not exist.
  2. It cannot be combined with --dir or --force.
  3. The generator copies and substitutes the template only in that directory.
  4. It validates paths, symlinks, sentinels, and workflows before returning success.
  5. It never reads or writes the consumer's final target. The consumer owns conflict detection and the final merge.
  6. --json returns mode, directory, template, registry identity, and replacements so callers do not need to parse console prose.

Normal generation uses the same staging and validation pipeline internally, then applies the validated tree to --dir. Existing --force behavior remains available only for this explicit apply mode.

Earlier generator versions skipped symbolic links during rewriting. Current versions reject every symbolic link before staging because templates can come from an external registry.

The pinned built-in snapshot already uses immutable action commits. Compatibility normalization remains restricted to that exact reviewed snapshot, rewrites only known legacy forms, and always runs the same validator afterward. Custom registries receive no migration and fail closed.

Then push to main and set Settings → Pages → Source → GitHub Actions. The workflow publishes on every push; the live URL appears in the Actions run. Point the repo's "Website" link at it with gh repo edit OWNER/REPO --homepage <site-url> (the same as checking "Use your GitHub Pages website").

Install options

# Into the current project (.agents/skills/create-gh-pages-site/):
npx skills add jongio/skills --skill create-gh-pages-site

# Pin to a branch or tag:
npx skills add jongio/skills#main --skill create-gh-pages-site

Copilot plugin marketplace:

copilot plugin marketplace add jongio/skills
copilot plugin install create-gh-pages-site@jongio-skills

Local install (no network):

pwsh -File scripts/install-local.ps1

After any install, reload skills with /skills reload or a new session.

A contributable registry

Templates live only in the jongio/gh-pages-templates registry with each template in a folder containing a template.json manifest. The generator fetches the built-in registry at a pinned commit. Override it with both --registry owner/repo and --registry-ref <full-sha>, or scaffold offline with --templates-dir <path>. The browsable gallery + live previews are hosted from the registry too. Adding or fixing a template is a PR to that repo — see its CONTRIBUTING.md. This skill owns the generator + the agent workflow, not the templates.

Run the tests

npm test
# node test/generator.test.mjs && node test/digest.test.mjs

No dependencies are needed. The tests run on bare node (18+) and never use the network. They exercise base-path math, skills-catalog discovery, immutable local registry checkout, staging, traversal and symlink rejection, sentinel validation, workflow policy, repo digestion, and placeholder generation.

Layout

SKILL.md                     The skill (authoring contract + workflow)
scripts/
  new-site.mjs               Generator: fetch, stage, validate, and apply a template
  new-site-cli.mjs           Command-line parsing and machine-readable output
  template-registry.mjs      Immutable registry checkout and verification
  template-security.mjs      Path, symlink, sentinel, and workflow validation
  digest-repo.mjs            Analyze a repo → JSON signals + type classification
  make-placeholder.mjs       Generate placeholder images + an IMAGES.md checklist
  install-local.ps1          Install this skill into $COPILOT_HOME/skills
test/                        Generator and digest tests (bare node, offline fixture)

License

MIT — see LICENSE.

Skill manifest

Create GitHub Pages Site

Scaffold a vetted Pages template with the correct base path and deployment workflow. Replace demo content with repo-derived content.

When to use which template

Pick by what the user is building. If unsure, ask one question (content vs. app) and default to static-html for the simplest ask.

Template Reach for it when… Tier Build
static-html A landing page, a few hand-made pages, "just put this HTML up". No toolchain. static none
astro A content site, blog, docs, or marketing page that should be fast and mostly static. SSG astro build
react-vite An interactive single-page app / dashboard with client-side routing. SPA vite build
eleventy A data/Markdown-driven site (blog, docs) where content is files + structured data. data SSG eleventy
jekyll The user wants the GitHub-native path, or is migrating an existing Jekyll site. native Jekyll
skills-catalog A browsable catalog for a repository of Copilot skills, especially when composing create-skills-repo. catalog registry-defined
spectator A technical specification, RFC, architecture proposal, design proposal, engineering decision, or policy proposal built for structured review. SSG vitepress build docs

The built-in registry pin must include the selected template. A custom registry requires an explicit --registry-ref, and a local checkout uses --templates-dir.

These seven cover the static / SSG / SPA / data / native / catalog / specification quadrants. For richer themes, point the user at upstream galleries (astro.build/themes, jamstackthemes.dev, github.com/topics/github-pages-template) and adapt — don't try to hand-build a theme from scratch.

The base-path trap (the thing to get right)

A GitHub project site is served from a subpath: https://<user>.github.io/<repo>/. A site built assuming root (/) ships with broken CSS, images, and links the moment it's a project site — assets 404 and the page looks blank. A user/org site (<user>.github.io repo) is served from /, so it must NOT carry a subpath prefix.

Each framework fixes this differently. The generator handles all of it from the repo name; you rarely set it by hand:

Template Mechanism Project value User-site value
static-html relative URLs (./assets/...) — (immune) — (immune)
astro base in astro.config.mjs /repo/ /
react-vite base in vite.config.js + basename + 404.html /repo/ /
eleventy pathPrefix via PATH_PREFIX env + url filter /repo/ /
jekyll baseurl in _config.yml + relative_url /repo (no slash) "" (empty)
spectator base in spectator.config.ts and VitePress config /repo/ /

The generator detects the <user>.github.io user-site pattern and uses / automatically. If the user hasn't named the repo yet, scaffold with the repo they intend; if they truly don't know, use --base / and tell them to re-run (or edit the base) once the repo exists.

Deployment model — one consistent flow

Every template deploys via the GitHub Actions Pages source, not from a branch. Every external action reference must use a full commit SHA.

  • static-html, react-vite, eleventy use that chain directly.
  • astro uses the official withastro/action@v6 (it builds + produces the Pages artifact) then actions/deploy-pages@v5.
  • jekyll uses GitHub's official actions/jekyll-build-pages@v1 then deploy-pages.

Every workflow limits top-level permissions to contents: read, grants Pages and identity-token access only to the jobs that need them, uses one Pages concurrency group, and deploys through the github-pages environment. There is no gh-pages branch to manage.

Action versions deprecate aggressively. Update the template registry to a reviewed action commit, then bump this skill's immutable default registry commit.

Interview first — never scaffold on a guess

This skill produces a real repo with a live deploy pipeline, so getting the inputs right matters more than speed. Do not stamp anything until you know (a) which template and (b) the target repo (or an explicit base path). If the prompt is bare ("make me a GitHub Pages site") or names no framework/repo, interview the user — ask only for what's missing, one focused question at a time, using the ask_user tool:

  1. What kind of site? Map the answer to a template:

    • "a landing page / just some HTML / the simplest thing" → static-html
    • "a blog / docs / content / marketing site, fast" → astro (or eleventy if they say Markdown- or data-driven, or jekyll if they want the GitHub-native path or are migrating an existing Jekyll site)
    • "an app / dashboard / interactive / single-page app" → react-vite
    • "a catalog of Copilot skills / create a skills repo" → skills-catalog
    • "a specification / RFC / architecture or design proposal / engineering decision / policy proposal / site like the Eval Authoring Guide" → spectator

    If they're unsure, ask the single discriminating question — content site or interactive app? — and default to static-html for the simplest ask.

  2. Which repo? Assume the current repo by default. The site is for the repo in context unless the user says otherwise — don't ask "current or new." Detect the current repo from git (git remote get-url origin, parsed to owner/name); the generator does the same automatically when you omit --repo. The repo drives the base path, so you must resolve it before stamping:

    • Current repo detected → use it. State the assumption in one line ("Scaffolding into this repo, octocat/blog → base /blog/") and proceed; no question needed.
    • No git context, detached, or no origin → then ask for the owner/name, and whether it's an existing repo or a new one to create.
    • Only treat it as a new/different repo when the user explicitly asks for one. For a user site, confirm the repo is named <user>.github.io (base /); otherwise it's a project site (base /repo/).
  3. Title? Optional — default to the repo name; never block on it.

You usually don't need to ask "what should the site say?" — the content comes from the repo (you digest it after stamping; see "Digest the repo, then author it"). When the target repo is the current/an existing one, run digest-repo.mjs early to confirm the type and let it inform the template choice (e.g. a cli repo is a great fit for astro or static-html with a command reference). If the repo is empty or brand-new, fall back to asking what the site should cover.

Skip any question the prompt already answered: "an Astro blog for octocat/blog" needs no interview (template astro, repo octocat/blog). For a bare "put this on Pages" inside a repo, assume the current repo and ask only for the template. Ask only for the gaps. When you inferred rather than were told, confirm in one line before scaffolding — e.g. "Astro site → octocat/blog (current repo), base /blog/ — go?"

Output location invariant

The user's current working directory is the destination workspace. A repo slug such as octocat/blog determines the Pages base path and URLs; it does not mean the site belongs in /tmp/blog, a sibling directory, or the skill's own directory.

  • If the workspace already contains repo files, scaffold in place with --dir . --force, even when it is not a git checkout and the prompt supplies the repo slug explicitly.
  • Never cd into the skill directory to run the generator. Invoke scripts/new-site.mjs by its absolute path while keeping the workspace as the process working directory.
  • Use another output directory only when the user explicitly asks for a subfolder or a new/different repo.
  • When another generator is composing the result, use --staging-dir instead of --dir. The staging directory is isolated and the consumer owns the final merge.
  • Before reporting completion, confirm the generated config, content, and .github/workflows files exist under the original working directory.

The workflow you follow

  1. Interview / gather context. Resolve the questions above via ask_user. You MUST end up with a chosen template and a target repo (or explicit --base) before stamping. Default the target to the current repo (detect it from git remote get-url origin); only ask when there's no git context or the user wants a different/new repo.
  2. Pick the template from the table above.
  3. Stamp it with the generator (next section). This injects the base path, site URL, and title, and lays down the deploy workflow.
  4. Place it in the repo:
    • Current repo (default): stamp into the repo root (or a subfolder if it's a subdirectory site, adjusting the workflow's upload path). From the original working directory, invoke the generator by absolute path and pass --dir . --force to write in place. Reconcile an existing deploy.yml rather than blindly overwriting it.
    • New repo (only when asked): create it (e.g. gh repo create <name> --public), stamp into it, and push. Match the repo name you used for the base path.
  5. Digest the repo and author the site (see "Digest the repo, then author it" below). This is the step that makes the site real: run the digest, replace every default page/section with repo-derived content of the right kind, add image placeholders + an IMAGES.md, and prompt the user for the real images (they can paste screenshots straight into the chat). Never skip to enabling Pages on the demo content.
  6. Enable Pages. Tell the user (or do it with their approval): Settings → Pages → Source → GitHub Actions. By CLI: gh api -X POST repos/<owner>/<repo>/pages -f build_type=workflow (or PUT to update). After the first push to main, the workflow runs and the live URL appears in the Actions run summary and under Settings → Pages.
  7. Set the repo website link to the Pages URL (the "Website" field in the repo header — same as ticking Settings → "Use your GitHub Pages website"). This is just the repo's homepage; point it at the site URL the generator prints: gh repo edit <owner>/<repo> --homepage <site-url> (or gh api -X PATCH repos/<owner>/<repo> -f homepage=<site-url>). Offer to set the exact URL, or let the user supply a custom domain instead. There's no separate "use Pages" boolean — setting homepage to the Pages URL is the checkbox.
  8. Verify it actually works (see "Validate" below) — don't claim success on a green workflow alone, and don't claim success while template default copy or "Hello, world" demo content is still on the page.

Stamp a site — the generator

node scripts/new-site.mjs <template> --repo <owner/name> [options]
Option Purpose
--repo <owner/name> Target repo. Derives the base path + URLs (and detects user sites). Defaults to the current repo's origin remote when omitted.
--base </path/> Override the base path (e.g. / for a user site or local preview).
--dir <path> Output directory (default: ./<repo-name>).
--site-name "Title" Human title (default: derived from the repo name).
--description "Text" Catalog description (default: derived from the title and repo).
--author "Name" Catalog author (default: repo owner).
--package-name <id> Package identifier (default: repo name).
--marketplace-id <id> Marketplace identifier (default: owner and repo).
--default-branch <id> Repository default branch used by catalog links and deployment triggers (default: main).
--registry <owner/repo> Template registry repo to fetch from (default: jongio/gh-pages-templates; needs git + network).
--registry-ref <sha> Full 40-character commit SHA. Required with a custom registry. Branches and tags are rejected.
--templates-dir <path> Use a local templates/ folder instead of fetching (offline).
--staging-dir <path> Write a validated tree to a new path without applying it to a target.
--force Write into a non-empty directory.
--json Emit a machine-readable result for composition.
--list List available templates.

Templates are not bundled in the skill. The generator fetches the built-in jongio/gh-pages-templates registry at a reviewed, immutable commit. A custom registry requires --registry-ref <full-sha>. Pass --templates-dir <path> to scaffold from a local copy offline.

Examples:

# Run from the target workspace; SKILL_DIR is this skill's absolute directory.
# Scaffold in place for the current repo (base inferred from its origin remote):
node "$SKILL_DIR/scripts/new-site.mjs" astro --dir . --force

# The workspace is an existing project without git metadata; the slug only supplies
# deployment identity and the base path. Output still goes into the workspace:
node "$SKILL_DIR/scripts/new-site.mjs" astro --repo octocat/blog --dir . --force

# Create a subfolder only when the user explicitly requested one:
node "$SKILL_DIR/scripts/new-site.mjs" react-vite --repo octocat/dashboard --dir ./site

# A user site (served from "/") or a quick local scaffold:
node "$SKILL_DIR/scripts/new-site.mjs" static-html --base / --dir . --force

# Safely compose a skills catalog without touching the consumer's target:
node "$SKILL_DIR/scripts/new-site.mjs" skills-catalog \
  --repo octocat/skills \
  --templates-dir ../gh-pages-templates/templates \
  --staging-dir ./.site-staging \
  --json

The generator replaces the shared base and repository sentinels plus the catalog sentinels __SITE_DESCRIPTION__, __REPO_OWNER__, __REPO_NAME__, __AUTHOR_NAME__, and __MARKETPLACE_ID__. Injection is deterministic and the result has no placeholders left. After stamping you may hand-edit content freely. Metadata values must be plain context-safe text. Markup, control characters, and characters that can break JSON, YAML, JavaScript, or HTML attributes are rejected.

Safe staging contract

Use --staging-dir whenever create-skills-repo or another tool will merge the site into a larger output. The path must not exist and the option cannot be combined with --dir or --force. The generator performs replacement and all validation inside staging, returns only after success, and never touches the final target. The consumer must check every destination conflict before copying staged files.

Before either staging success or normal apply, the generator:

  1. verifies an external registry checkout matches the requested full commit SHA;
  2. proves the resolved template path remains inside the registry templates root;
  3. rejects every symlink in the template tree;
  4. rejects unresolved __SENTINEL__ placeholders;
  5. scans .github/workflows/*.yml and .yaml for excess permissions, unsafe triggers, non-SHA action references, persisted checkout credentials, lifecycle-capable installs without script suppression, and direct GitHub context interpolation in shell commands.

Normal --dir generation uses a private staging directory and applies only after all checks pass. This preserves existing template and --force behavior while ensuring an invalid template cannot partially modify the target.

The exact pinned built-in snapshot has a compatibility normalization for its five legacy templates. It upgrades their known action tags to reviewed commit SHAs, disables persisted checkout credentials and lifecycle scripts, and then validates the result. Never apply this normalization to a custom registry.

Digest the repo, then author it (never ship the template defaults)

1. Run the digest

node scripts/digest-repo.mjs --dir <path-to-repo> --json

It returns deterministic signals you build from: name, description (the pitch), repoSlug, license, a type classification (cli | library | app | action | collection | docs | site) with the reasons behind it, suggested install commands, README usageExamples (code fences), badges, docFiles, existing images (with role hints like logo/hero/screenshot), languages, and subProjects (for monorepos/collections). Read the repo's README and key docs yourself too — the digest points you at them; it doesn't replace judgment.

2. Build the right kind of site for the type

Type Tell-tale signals Author the site around…
cli bin, console_scripts, [[bin]], --help in README Install + Quickstart, then a command/flag reference (a section or page per command), copy-paste examples, config/exit codes. Hero = terminal demo.
library main/exports, [lib], import examples Install, an import + usage snippet, an API reference (exported functions/types from the README/docs), examples, badges. Hero = a concept diagram.
app web-framework dep, index.html, src/ A feature tour with screenshots, a "Get started"/live-demo CTA. Hero = an app screenshot.
action action.yml A uses: snippet, an inputs/outputs table, an example workflow.
collection plugin.json/marketplace.json + skills/, workspaces, packages/ A catalog: one card/detail per subProject (its pitch + install), plus a top-level install for the whole thing. Hero = a banner; per-item thumbnails.
docs many Markdown docs, little code A docs nav + content, pulling the existing Markdown in.
site / unknown none of the above A clean landing built from the repo's pitch and links. If the shape is unclear, ask the user what sections they want.

3. Authoring rules

  • Replace every default. No template demo copy survives — not the sample hero, not "Hello, Astro/world", not the example blog posts, not lorem. After building, grep the output for the template's stock phrases; none should remain.
  • Use real values from the digest: the repo's name and description as the title/tagline, the install commands verbatim, the README usageExamples as real code blocks, badges, license, and links to the repo and each subProject. Don't invent features, commands, or APIs you can't see in the repo — if something's unclear, leave a visible TODO for the user rather than fabricate.
  • Fit the template's content model. Use content collections (Astro/Eleventy: one entry per command/skill/post), pages (React/static), etc. Add or rename routes to match the content (e.g. a commands/ or catalog/ section) instead of forcing everything into the demo "blog". Keep the GitHub source link and the base-path-aware internal links the template already wires — never hand-write absolute /... links (use the template's base helper, or it breaks on a project site).
  • Keep Spectator free-form. Do not force a standard specification outline. Derive pages, headings, and navigation from the supplied context. Preserve the Spectator reading and feedback system, but remove every Project Northstar sample page, label, requirement, source, and image reference.
  • Label uncertainty in Spectator. Distinguish verified current behavior, user-approved decisions, proposals, assumptions, risks, and open questions. Do not invent owners, dates, requirements, interfaces, or security claims.

4. Add image placeholders the user can supply

Real sites need art the agent can't produce. Drop in obvious placeholders plus a checklist so the user knows exactly what to provide:

node scripts/make-placeholder.mjs --out <site>/<images-dir> --preset <type> --repo owner/name

--preset is the repo type (cli/library/app/collection/site). It writes labeled SVG placeholders (logo, social card, favicon, hero, and type-specific shots) and an IMAGES.md manifest listing each file's purpose and recommended dimensions. Then:

  • Reference them from the pages you author — hero, top-bar logo, the OG/social meta tag, and per-item thumbnails for a catalog.
  • Reuse real images first. If the digest found an existing logo or screenshot (e.g. a docs/*.png), use it instead of a placeholder.
  • Put images where the template serves static files:
    • astro, react-vite → public/images/ (served at ${BASE_URL}images/…)
    • spectator → docs/public/images/ (VitePress applies its configured base)
    • static-html → assets/images/ (relative ./assets/images/…)
    • eleventy → src/assets/images/ (through the url filter)
    • jekyll → assets/images/ (via relative_url)
  • Leave IMAGES.md in the images dir as the hand-off, and tell the user it's there. A placeholder still deploys fine; it just visibly says "replace me".

Ask for real images

After authoring, ask only for images the site references. Give each role, filename, and recommended dimensions; accept pasted images, file paths, or URLs. Keep unprovided placeholders, update IMAGES.md, and do not block deployment. digest-repo.mjs discovers source material; make-placeholder.mjs creates the placeholder set and handoff manifest.

Per-template notes

  • static-html — Zero build. All links are relative, so it's base-path-proof. Ships index.html, about.html, 404.html, assets/, and a .nojekyll.
  • astro — site = origin, base = /repo/. Internal links use import.meta.env.BASE_URL. public/ is copied verbatim. Node 24 in CI by default.
  • react-vite — base in vite.config.js; React Router basename derived from BASE_URL; copy-404.mjs (a postbuild hook) copies index.html → 404.html so deep-link refreshes work on Pages. Reference public assets as /asset so Vite rewrites them with the base.
  • eleventy — pathPrefix comes from the PATH_PREFIX env the workflow sets; every link/asset uses the url filter. Posts live in src/posts/, listed via collections.posts. Locally it serves at /.
  • jekyll — baseurl (no trailing slash) in _config.yml; links use relative_url. Built in CI by jekyll-build-pages (honors the Gemfile). Local dev needs Ruby + Bundler; CI does not.
  • spectator: VitePress reads base from spectator.config.ts. Content is free-form Markdown under docs/; navigation is explicit in the shared config. Preserve local search, page outlines, light/dark appearance, plain-language callouts, page feedback, selected-text feedback, and GitHub edit links. Run npm test, npm run build, and npm run test:e2e.

Current repo vs. new repo

  • Current repo (the default): assume the site is for the repo in context. The generator infers the base path from its origin remote when you omit --repo. Put the site at the root for a whole-repo site, or in a subfolder and point the workflow's upload-pages-artifact path: at it. If a deploy.yml already exists, reconcile — don't blindly overwrite.
  • New repo (only when asked): create with gh repo create, stamp, push to main. For a user site, the repo MUST be named <user>.github.io and the base is / — the generator handles the base when you pass that repo name.

Custom domains (documented, not automated)

For a custom domain: add a CNAME file (for static/Jekyll, at the served root; for Astro, public/CNAME), set DNS at the registrar, and in Astro set site to the domain and drop base. Don't automate DNS — explain the steps.

Template registry & contributing

Templates live in one place: the jongio/gh-pages-templates registry. The skill does not bundle its own copy — the generator fetches templates from the registry at runtime (override with --registry <owner/repo>, or scaffold offline from a local checkout with --templates-dir <path>):

node scripts/new-site.mjs astro --repo octocat/blog            # pinned default registry
node scripts/new-site.mjs skills-catalog --repo octocat/skills \
  --registry octocat/templates --registry-ref 0123456789abcdef0123456789abcdef01234567
node scripts/new-site.mjs astro --templates-dir ../gh-pages-templates/templates

Each template is a folder with a template.json manifest, a deploy workflow, base-path handling via the sentinels, and a README.md. The registry also renders the browsable gallery (live previews of every template) at https://jongio.github.io/gh-pages-templates/ — the single home for browsing and previewing. Point users there to browse, and to the registry's CONTRIBUTING.md to submit a new template. Template changes (add/fix a template, bump an action version) land in the registry, not here.

Validate — don't claim done on a green check

  1. Content check first. Confirm the site is about the repo, not the template: the title/tagline, install commands, and examples are the repo's real values, and no template demo copy survives (grep the built output for the template's stock phrases — "Hello", "islands", "lorem", the sample post titles — and for leftover __…__ sentinels). The page kind matches the repo type (CLI ref / API ref / feature tour / catalog). Image placeholders exist and IMAGES.md is present.
  2. Build it. For astro/react-vite/eleventy/spectator, run npm ci --ignore-scripts --no-audit --no-fund then npm run build and confirm both exit 0 and emit the output dir (dist / _site). For jekyll, bundle exec jekyll build if Ruby is present.
  3. Check the base path. Open the built output and confirm asset/link URLs carry the project prefix (/repo/...) — not bare /.... This is the failure mode that "looks deployed but renders blank."
  4. After deploy, load the live page_url from the Actions run; click an internal link and (for the SPA) refresh a sub-route to confirm the 404.html fallback works.
  5. Only then report it as working.

Run the skill's own tests with npm test (the generator + the repo-digest and placeholder checks, offline via a fixture). Template/workflow validation lives in the jongio/gh-pages-templates registry.

Footguns

  • Never ship a project site built for / — assets 404. Set the base path (the generator does this; verify it).
  • Never put a subpath base on a user site (<user>.github.io) — it must be / (Jekyll: baseurl: "").
  • Never use actions/upload-artifact for Pages — it's upload-pages-artifact.
  • Never reach for peaceiris/actions-gh-pages or a gh-pages branch — use the first-party Actions flow these templates ship.
  • Never forget to set Source → GitHub Actions in Settings → Pages; the workflow can't publish until Pages is enabled for Actions.
  • Don't leave the repo "Website" link blank — set homepage to the Pages URL (gh repo edit --homepage) so visitors find the site; it's the same as the "Use your GitHub Pages website" checkbox.
  • Never claim success because the workflow is green — load the URL and check an asset and an internal link actually resolve.
  • Never ship the template's demo content. A stamped template that still says "Hello, Astro", lists sample blog posts, or contains Project Northstar is a failure. Digest the repo and author real content of the right kind.
  • Never fabricate features, commands, or APIs to fill the page. Author only what the repo actually shows; leave a visible TODO when unsure.
  • Don't leave bare image references with nothing behind them — add the placeholders + IMAGES.md, or reuse the repo's existing images.
  • Don't ship placeholders silently — tell the user which real images the site needs and that they can paste a screenshot into the chat to fill each one.
  • Don't hand-roll a base-path setup when the generator + sentinels already do it correctly per framework.
  • Never pass a branch or tag as --registry-ref. Only a full commit SHA is immutable enough to validate.
  • Never compose directly into another generator's target. Stage first, check conflicts, then merge.
Files (skills)
  • evals
    • create-gh-pages-site
      • fixtures
        • astro-cli
          • package.json 153 B
            Loading…
          • README.md 154 B
            Loading…
        • skills-catalog
          • deploy.yml 392 B
            Loading…
          • index.html 435 B · in bundle
          • template.json 152 B
            Loading…
        • skills-repo
          • alpha-skill.md 82 B
            Loading…
          • do-not-overwrite.txt 15 B
            Loading…
          • README.md 53 B
            Loading…
        • spectator
          • .github
            • workflows
              • deploy.yml 1.1 KB
                Loading…
          • docs
            • .vitepress
              • theme
                • FeedbackPrompt.vue 111 B · in bundle
                • index.ts 391 B
                  Loading…
                • SelectionActions.vue 352 B · in bundle
              • config.mts 219 B · in bundle
            • index.md 137 B
              Loading…
            • proposal.md 155 B
              Loading…
            • system-shape.md 148 B
              Loading…
          • package.json 136 B
            Loading…
          • spectator.config.ts 146 B
            Loading…
          • template.json 135 B
            Loading…
        • spectator-repo
          • proposal-notes.md 413 B
            Loading…
          • README.md 330 B
            Loading…
        • static-library
          • package.json 150 B
            Loading…
          • README.md 208 B
            Loading…
      • eval.yaml 19.6 KB
        Loading…
    • README.md 2 KB
      Loading…
  • scripts
    • digest-repo.mjs 17.6 KB · in bundle
    • install-local.ps1 1.2 KB · in bundle
    • make-placeholder.mjs 7.8 KB · in bundle
    • new-site-cli.mjs 6.4 KB · in bundle
    • new-site.mjs 17.8 KB · in bundle
    • template-registry.mjs 4.4 KB · in bundle
    • template-security.mjs 20.3 KB · in bundle
  • test
    • digest.test.mjs 8.7 KB · in bundle
    • generator.test.mjs 32.2 KB · in bundle
  • .gitignore 345 B · in bundle
  • .npmrc 18 B · in bundle
  • .vally.yaml 672 B
    Loading…
  • CONTRIBUTING.md 4 KB
    Loading…
  • LICENSE 1 KB · in bundle
  • package-lock.json 108.1 KB
    Loading…
  • package.json 840 B
    Loading…
  • README.md 10.2 KB
    # create-gh-pages-site
    
    Scaffold a working **GitHub Pages** website from a vetted template and wire it to
    deploy automatically — packaged as a GitHub Copilot skill.
    
    Pick a template (static, Astro, React + Vite, Eleventy, Jekyll, or skills catalog); the skill
    injects the correct **base path** for your repo, adds the current official GitHub
    Actions Pages workflow, drops it into your repo (the **current repo by default**, or
    a new one), and tells you how to turn Pages on.
    
    It doesn't stop at the template's demo content, either: it **digests your repo**
    (README, manifests, entry points, docs) and authors a site that's actually about
    your project — a CLI reference, an API/usage page, a feature tour, or a catalog of
    parts — and drops in labeled image placeholders you swap for real art.
    
    ## Quickstart
    
    **1. Install the skill**:
    
    ```sh
    npx skills add jongio/skills --skill create-gh-pages-site
    ```
    
    **2. Reload skills** — run `/skills reload`, or start a new session.
    
    **3. Ask Copilot to build a site:**
    
    ```text
    /create-gh-pages-site put this repo on GitHub Pages as an Astro blog
    ```
    
    By default the agent scaffolds for the **repo you're in** — it reads the current
    repo from git, picks the `astro` template, sets `site`/`base` for it, lays down the
    deploy workflow, and shows you how to enable Pages. Name a different repo
    (`octocat/blog`) only when you want one.
    
    ## Why this exists
    
    GitHub Pages' hard parts aren't the HTML — they're the deploy plumbing and the
    **base-path trap**: a project site lives at `https://USER.github.io/REPO/`, so a
    site built for `/` ships with broken assets and links. Every framework fixes this
    differently (Astro `base`, Vite `base` + `404.html`, Eleventy `pathPrefix`, Jekyll
    `baseurl`). This skill gets all of it right, every time.
    
    ## Templates
    
    | Template | Use it for | Base path | Build |
    | --- | --- | --- | --- |
    | `static-html` | landing pages, a few hand-made pages | relative URLs (immune) | none |
    | `astro` | content sites, blogs, docs, marketing | `base` in `astro.config.mjs` | `astro build` |
    | `react-vite` | interactive SPAs / dashboards | `base` + `404.html` fallback | `vite build` |
    | `eleventy` | data/Markdown-driven sites | `pathPrefix` via env + `url` filter | `eleventy` |
    | `jekyll` | GitHub-native / existing Jekyll | `baseurl` in `_config.yml` | Jekyll |
    | `skills-catalog` | browsable catalogs for Copilot skills repositories | template base helper | registry-defined |
    
    The built-in registry pin includes `skills-catalog`. Custom registries require a
    full `--registry-ref`, and local checkouts use `--templates-dir`.
    
    All templates deploy via the **GitHub Actions** Pages source. Every external action
    must be pinned to a full commit SHA, checkout must disable persisted credentials,
    and install steps must disable lifecycle scripts. No `gh-pages` branch is used.
    Workflow scanning accepts a conservative block-style YAML subset and rejects
    quoted keys, tags, anchors, aliases, merge keys, and unsupported flow mappings.
    
    Browse them in the live [gallery with previews](https://jongio.github.io/gh-pages-templates/),
    hosted from the [`jongio/gh-pages-templates`](https://github.com/jongio/gh-pages-templates) registry.
    
    ## Tailored to your repo, not a demo
    
    A stamped template is a skeleton, not the deliverable. After stamping, the skill
    reads your repo and rewrites the content to match it:
    
    - **`scripts/digest-repo.mjs`** analyzes the repo and classifies it — `cli`,
      `library`, `app`, `action`, `collection`, `docs`, or `site` — and pulls out the
      name, pitch, install commands, README usage examples, badges, docs, existing
      images, and sub-projects. That drives *which* kind of site gets built: a command
      reference for a CLI, an API/usage page for a library, a feature tour for an app, a
      catalog for a monorepo.
    - **`scripts/make-placeholder.mjs`** drops labeled placeholder images (logo, social
      card, hero, screenshots) into the site plus an `IMAGES.md` checklist telling you
      what to supply and at what size. Real images the repo already has are reused
      instead.
    
    ```sh
    node scripts/digest-repo.mjs --dir . --json          # see what the author sees
    node scripts/make-placeholder.mjs --out site/public/images --preset cli --repo octocat/mytool
    ```
    
    ## Use it
    
    Once installed, describe the site you want:
    
    ```text
    /create-gh-pages-site a docs site with Eleventy in a new repo called octocat/docs
    ```
    
    ```text
    /create-gh-pages-site put this folder of HTML on Pages
    ```
    
    You don't have to name the skill — the agent routes to it whenever you ask to
    create or publish a GitHub Pages site.
    
    ## Build it yourself (no agent)
    
    The generator stamps the same site the skill uses. Templates are fetched from the
    [`jongio/gh-pages-templates`](https://github.com/jongio/gh-pages-templates) registry
    at an immutable commit, so it needs git + network unless you pass `--templates-dir`.
    The built-in registry uses a reviewed pinned commit. A custom registry requires
    `--registry-ref` with its full 40-character commit SHA:
    
    Free-form metadata is limited to context-safe text because the same sentinel can
    appear in HTML, JSON, YAML, and JavaScript. Markup, control characters, and
    context-breaking quotes are rejected instead of being copied into generated code.
    
    ```sh
    # Scaffold for the CURRENT repo (base path read from its origin remote):
    node scripts/new-site.mjs astro
    
    # An Astro site for a specific project repo (base = /blog/):
    node scripts/new-site.mjs astro --repo octocat/blog --site-name "Octocat's Blog"
    
    # A React SPA:
    node scripts/new-site.mjs react-vite --repo octocat/dashboard
    
    # A user site (served from "/") or a quick local scaffold:
    node scripts/new-site.mjs static-html --base / --dir ./site
    
    # Offline, from a local registry checkout:
    node scripts/new-site.mjs astro --templates-dir ../gh-pages-templates/templates
    
    # A custom registry is always commit-pinned:
    node scripts/new-site.mjs skills-catalog --repo octocat/skills \
      --author "Octo Cat" --marketplace-id octocat-skills --default-branch trunk \
      --registry octocat/templates --registry-ref 0123456789abcdef0123456789abcdef01234567
    
    # List templates:
    node scripts/new-site.mjs --list
    ```
    
    ## Safe staging for composition
    
    `create-skills-repo` and other generators should stage the site instead of writing
    into their target:
    
    ```sh
    node scripts/new-site.mjs skills-catalog \
      --repo octocat/skills \
      --templates-dir ../gh-pages-templates/templates \
      --staging-dir ./.site-staging \
      --json
    ```
    
    The staging contract is fail-closed:
    
    1. `--staging-dir` must name a path that does not exist.
    2. It cannot be combined with `--dir` or `--force`.
    3. The generator copies and substitutes the template only in that directory.
    4. It validates paths, symlinks, sentinels, and workflows before returning success.
    5. It never reads or writes the consumer's final target. The consumer owns conflict
       detection and the final merge.
    6. `--json` returns `mode`, `directory`, `template`, registry identity, and
       replacements so callers do not need to parse console prose.
    
    Normal generation uses the same staging and validation pipeline internally, then
    applies the validated tree to `--dir`. Existing `--force` behavior remains
    available only for this explicit apply mode.
    
    Earlier generator versions skipped symbolic links during rewriting. Current
    versions reject every symbolic link before staging because templates can come from
    an external registry.
    
    The pinned built-in snapshot already uses immutable action commits. Compatibility
    normalization remains restricted to that exact reviewed snapshot, rewrites only
    known legacy forms, and always runs the same validator afterward. Custom registries
    receive no migration and fail closed.
    
    Then push to `main` and set **Settings → Pages → Source → GitHub Actions**. The
    workflow publishes on every push; the live URL appears in the Actions run. Point
    the repo's "Website" link at it with `gh repo edit OWNER/REPO --homepage <site-url>`
    (the same as checking *"Use your GitHub Pages website"*).
    
    ## Install options
    
    ```sh
    # Into the current project (.agents/skills/create-gh-pages-site/):
    npx skills add jongio/skills --skill create-gh-pages-site
    
    # Pin to a branch or tag:
    npx skills add jongio/skills#main --skill create-gh-pages-site
    ```
    
    **Copilot plugin marketplace:**
    
    ```sh
    copilot plugin marketplace add jongio/skills
    copilot plugin install create-gh-pages-site@jongio-skills
    ```
    
    **Local install (no network):**
    
    ```sh
    pwsh -File scripts/install-local.ps1
    ```
    
    After any install, reload skills with `/skills reload` or a new session.
    
    ## A contributable registry
    
    Templates live **only** in the
    [`jongio/gh-pages-templates`](https://github.com/jongio/gh-pages-templates) registry
    with each template in a folder containing a `template.json` manifest. The generator
    fetches the built-in registry at a pinned commit. Override it with both
    `--registry owner/repo` and `--registry-ref <full-sha>`, or scaffold offline with
    `--templates-dir <path>`. The browsable gallery + live previews are hosted from the
    registry too. Adding or fixing a template is a PR to that repo — see its
    `CONTRIBUTING.md`. This skill owns the generator + the agent workflow, not the
    templates.
    
    ## Run the tests
    
    ```sh
    npm test
    # node test/generator.test.mjs && node test/digest.test.mjs
    ```
    
    No dependencies are needed. The tests run on bare `node` (18+) and never use the
    network. They exercise base-path math, skills-catalog discovery, immutable local
    registry checkout, staging, traversal and symlink rejection, sentinel validation,
    workflow policy, repo digestion, and placeholder generation.
    
    ## Layout
    
    ```text
    SKILL.md                     The skill (authoring contract + workflow)
    scripts/
      new-site.mjs               Generator: fetch, stage, validate, and apply a template
      new-site-cli.mjs           Command-line parsing and machine-readable output
      template-registry.mjs      Immutable registry checkout and verification
      template-security.mjs      Path, symlink, sentinel, and workflow validation
      digest-repo.mjs            Analyze a repo → JSON signals + type classification
      make-placeholder.mjs       Generate placeholder images + an IMAGES.md checklist
      install-local.ps1          Install this skill into $COPILOT_HOME/skills
    test/                        Generator and digest tests (bare node, offline fixture)
    ```
    
    ## License
    
    MIT — see [LICENSE](./LICENSE).
    
  • SKILL.md 28.8 KB
    ---
    name: create-gh-pages-site
    description: >-
      Scaffold a working GitHub Pages website from a vetted template and wire it to
      deploy automatically. Use when the user wants to create, scaffold, or publish a
      site on GitHub Pages: a reviewable VitePress specification, a static page, an
      Astro or Eleventy site, a React (Vite) SPA, or a Jekyll site. Picks the right
      template, injects the correct base path
      for the target repo (the #1 thing people get wrong), adds the official GitHub
      Actions Pages deploy workflow, and sets it up in the user's current repo by
      default or a new one if asked. Does not stop at demo content: it digests the
      target repo (README, manifests, entry points, docs) and authors a site about
      that repo (CLI reference, API/usage page, feature tour, or catalog) with labeled
      image placeholders the user swaps in. Do NOT use for non-Pages hosting
      (Vercel/Netlify/Azure), deploying an existing app without a Pages target, or
      plain web pages unrelated to GitHub Pages.
    metadata:
      version: "1.1.0"
    ---
    
    # Create GitHub Pages Site
    
    Scaffold a vetted Pages template with the correct base path and deployment workflow.
    Replace demo content with repo-derived content.
    
    ## When to use which template
    
    Pick by what the user is building. If unsure, ask one question (content vs. app)
    and default to `static-html` for the simplest ask.
    
    | Template | Reach for it when… | Tier | Build |
    | --- | --- | --- | --- |
    | `static-html` | A landing page, a few hand-made pages, "just put this HTML up". No toolchain. | static | none |
    | `astro` | A content site, blog, docs, or marketing page that should be fast and mostly static. | SSG | `astro build` |
    | `react-vite` | An interactive single-page app / dashboard with client-side routing. | SPA | `vite build` |
    | `eleventy` | A data/Markdown-driven site (blog, docs) where content is files + structured data. | data SSG | `eleventy` |
    | `jekyll` | The user wants the GitHub-native path, or is migrating an existing Jekyll site. | native | Jekyll |
    | `skills-catalog` | A browsable catalog for a repository of Copilot skills, especially when composing `create-skills-repo`. | catalog | registry-defined |
    | `spectator` | A technical specification, RFC, architecture proposal, design proposal, engineering decision, or policy proposal built for structured review. | SSG | `vitepress build docs` |
    
    The built-in registry pin must include the selected template. A custom registry
    requires an explicit `--registry-ref`, and a local checkout uses
    `--templates-dir`.
    
    These seven cover the static / SSG / SPA / data / native / catalog / specification
    quadrants. For richer
    *themes*, point the user at upstream galleries (astro.build/themes,
    jamstackthemes.dev, github.com/topics/github-pages-template) and adapt — don't try
    to hand-build a theme from scratch.
    
    ## The base-path trap (the thing to get right)
    
    A GitHub **project** site is served from a subpath:
    `https://<user>.github.io/<repo>/`. A site built assuming root (`/`) ships with
    broken CSS, images, and links the moment it's a project site — assets 404 and the
    page looks blank. A **user/org** site (`<user>.github.io` repo) *is* served from
    `/`, so it must NOT carry a subpath prefix.
    
    Each framework fixes this differently. The generator handles all of it from the
    repo name; you rarely set it by hand:
    
    | Template | Mechanism | Project value | User-site value |
    | --- | --- | --- | --- |
    | `static-html` | relative URLs (`./assets/...`) | — (immune) | — (immune) |
    | `astro` | `base` in `astro.config.mjs` | `/repo/` | `/` |
    | `react-vite` | `base` in `vite.config.js` + `basename` + `404.html` | `/repo/` | `/` |
    | `eleventy` | `pathPrefix` via `PATH_PREFIX` env + `url` filter | `/repo/` | `/` |
    | `jekyll` | `baseurl` in `_config.yml` + `relative_url` | `/repo` (no slash) | `""` (empty) |
    | `spectator` | `base` in `spectator.config.ts` and VitePress config | `/repo/` | `/` |
    
    **The generator detects the `<user>.github.io` user-site pattern and uses `/`
    automatically.** If the user hasn't named the repo yet, scaffold with the repo
    they intend; if they truly don't know, use `--base /` and tell them to re-run (or
    edit the base) once the repo exists.
    
    ## Deployment model — one consistent flow
    
    Every template deploys via the **GitHub Actions** Pages source, not from a branch.
    Every external action reference must use a full commit SHA.
    
    - `static-html`, `react-vite`, `eleventy` use that chain directly.
    - `astro` uses the official `withastro/action@v6` (it builds + produces the Pages
      artifact) then `actions/deploy-pages@v5`.
    - `jekyll` uses GitHub's official `actions/jekyll-build-pages@v1` then `deploy-pages`.
    
    Every workflow limits top-level permissions to `contents: read`, grants Pages and
    identity-token access only to the jobs that need them, uses one Pages concurrency
    group, and deploys through the `github-pages` environment. There is **no
    `gh-pages` branch** to manage.
    
    > Action versions deprecate aggressively. Update the template registry to a reviewed
    > action commit, then bump this skill's immutable default registry commit.
    
    ## Interview first — never scaffold on a guess
    
    This skill produces a real repo with a live deploy pipeline, so getting the inputs
    right matters more than speed. **Do not stamp anything until you know (a) which
    template and (b) the target repo (or an explicit base path).** If the prompt is bare
    ("make me a GitHub Pages site") or names no framework/repo, interview the user — ask
    only for what's missing, one focused question at a time, using the `ask_user` tool:
    
    1. **What kind of site?** Map the answer to a template:
       - "a landing page / just some HTML / the simplest thing" → `static-html`
       - "a blog / docs / content / marketing site, fast" → `astro` (or `eleventy` if
         they say Markdown- or data-driven, or `jekyll` if they want the GitHub-native
         path or are migrating an existing Jekyll site)
       - "an app / dashboard / interactive / single-page app" → `react-vite`
       - "a catalog of Copilot skills / create a skills repo" → `skills-catalog`
       - "a specification / RFC / architecture or design proposal / engineering
         decision / policy proposal / site like the Eval Authoring Guide" →
         `spectator`
    
       If they're unsure, ask the single discriminating question — *content site or
       interactive app?* — and default to `static-html` for the simplest ask.
    2. **Which repo? Assume the current repo by default.** The site is for the repo in
       context unless the user says otherwise — don't ask "current or new." Detect the
       current repo from git (`git remote get-url origin`, parsed to `owner/name`); the
       generator does the same automatically when you omit `--repo`. The repo drives the
       base path, so you must resolve it before stamping:
       - **Current repo detected** → use it. State the assumption in one line
         (*"Scaffolding into this repo, octocat/blog → base `/blog/`"*) and proceed; no
         question needed.
       - **No git context, detached, or no `origin`** → then ask for the `owner/name`,
         and whether it's an existing repo or a **new** one to create.
       - Only treat it as a **new/different** repo when the user explicitly asks for one.
         For a user site, confirm the repo is named `<user>.github.io` (base `/`);
         otherwise it's a project site (base `/repo/`).
    3. **Title?** Optional — default to the repo name; never block on it.
    
    You usually don't need to ask "what should the site say?" — the **content comes from
    the repo** (you digest it after stamping; see "Digest the repo, then author it").
    When the target repo is the current/an existing one, run `digest-repo.mjs` early to
    confirm the type and let it inform the template choice (e.g. a `cli` repo is a great
    fit for `astro` or `static-html` with a command reference). If the repo is empty or
    brand-new, fall back to asking what the site should cover.
    
    Skip any question the prompt already answered: *"an Astro blog for octocat/blog"*
    needs no interview (template `astro`, repo `octocat/blog`). For a bare *"put this on
    Pages"* inside a repo, assume the current repo and ask only for the template. Ask
    only for the gaps. When you **inferred** rather than were told, confirm in one line
    before scaffolding — e.g. *"Astro site → octocat/blog (current repo), base `/blog/` —
    go?"*
    
    ## Output location invariant
    
    **The user's current working directory is the destination workspace.** A repo slug
    such as `octocat/blog` determines the Pages base path and URLs; it does not mean the
    site belongs in `/tmp/blog`, a sibling directory, or the skill's own directory.
    
    - If the workspace already contains repo files, scaffold in place with
      `--dir . --force`, even when it is not a git checkout and the prompt supplies the
      repo slug explicitly.
    - Never `cd` into the skill directory to run the generator. Invoke
      `scripts/new-site.mjs` by its absolute path while keeping the workspace as the
      process working directory.
    - Use another output directory only when the user explicitly asks for a subfolder
      or a new/different repo.
    - When another generator is composing the result, use `--staging-dir` instead of
      `--dir`. The staging directory is isolated and the consumer owns the final merge.
    - Before reporting completion, confirm the generated config, content, and
      `.github/workflows` files exist under the original working directory.
    
    ## The workflow you follow
    
    1. **Interview / gather context.** Resolve the questions above via `ask_user`. You
       MUST end up with a chosen template and a target repo (or explicit `--base`) before
       stamping. **Default the target to the current repo** (detect it from
       `git remote get-url origin`); only ask when there's no git context or the user
       wants a different/new repo.
    2. **Pick the template** from the table above.
    3. **Stamp it** with the generator (next section). This injects the base path,
       site URL, and title, and lays down the deploy workflow.
    4. **Place it in the repo:**
       - *Current repo (default)*: stamp into the repo root (or a subfolder if it's a
         subdirectory site, adjusting the workflow's upload path). From the original
         working directory, invoke the generator by absolute path and pass `--dir .`
         `--force` to write in place. Reconcile an existing `deploy.yml` rather than
         blindly overwriting it.
       - *New repo (only when asked)*: create it (e.g. `gh repo create <name> --public`),
         stamp into it, and push. Match the repo name you used for the base path.
    5. **Digest the repo and author the site** (see "Digest the repo, then author it"
       below). This is the step that makes the site *real*: run the digest, replace
       every default page/section with repo-derived content of the right kind, add
       image placeholders + an `IMAGES.md`, and **prompt the user for the real images**
       (they can paste screenshots straight into the chat). Never skip to enabling Pages
       on the demo content.
    6. **Enable Pages.** Tell the user (or do it with their approval):
       **Settings → Pages → Source → GitHub Actions**. By CLI:
       `gh api -X POST repos/<owner>/<repo>/pages -f build_type=workflow` (or PUT to
       update). After the first push to `main`, the workflow runs and the live URL
       appears in the Actions run summary and under Settings → Pages.
    7. **Set the repo website link** to the Pages URL (the "Website" field in the repo
       header — same as ticking *Settings → "Use your GitHub Pages website"*). This is
       just the repo's `homepage`; point it at the site URL the generator prints:
       `gh repo edit <owner>/<repo> --homepage <site-url>` (or
       `gh api -X PATCH repos/<owner>/<repo> -f homepage=<site-url>`). Offer to set the
       exact URL, or let the user supply a custom domain instead. There's no separate
       "use Pages" boolean — setting `homepage` to the Pages URL *is* the checkbox.
    8. **Verify it actually works** (see "Validate" below) — don't claim success on a
       green workflow alone, and don't claim success while template default copy or
       "Hello, world" demo content is still on the page.
    
    ## Stamp a site — the generator
    
    ```sh
    node scripts/new-site.mjs <template> --repo <owner/name> [options]
    ```
    
    | Option | Purpose |
    | --- | --- |
    | `--repo <owner/name>` | Target repo. Derives the base path + URLs (and detects user sites). **Defaults to the current repo's `origin` remote when omitted.** |
    | `--base </path/>` | Override the base path (e.g. `/` for a user site or local preview). |
    | `--dir <path>` | Output directory (default: `./<repo-name>`). |
    | `--site-name "Title"` | Human title (default: derived from the repo name). |
    | `--description "Text"` | Catalog description (default: derived from the title and repo). |
    | `--author "Name"` | Catalog author (default: repo owner). |
    | `--package-name <id>` | Package identifier (default: repo name). |
    | `--marketplace-id <id>` | Marketplace identifier (default: owner and repo). |
    | `--default-branch <id>` | Repository default branch used by catalog links and deployment triggers (default: `main`). |
    | `--registry <owner/repo>` | Template registry repo to fetch from (default: `jongio/gh-pages-templates`; needs git + network). |
    | `--registry-ref <sha>` | Full 40-character commit SHA. Required with a custom registry. Branches and tags are rejected. |
    | `--templates-dir <path>` | Use a local `templates/` folder instead of fetching (offline). |
    | `--staging-dir <path>` | Write a validated tree to a new path without applying it to a target. |
    | `--force` | Write into a non-empty directory. |
    | `--json` | Emit a machine-readable result for composition. |
    | `--list` | List available templates. |
    
    Templates are **not bundled in the skill**. The generator fetches the built-in
    `jongio/gh-pages-templates` registry at a reviewed, immutable commit. A custom
    registry requires `--registry-ref <full-sha>`. Pass `--templates-dir <path>` to
    scaffold from a local copy offline.
    
    Examples:
    
    ```sh
    # Run from the target workspace; SKILL_DIR is this skill's absolute directory.
    # Scaffold in place for the current repo (base inferred from its origin remote):
    node "$SKILL_DIR/scripts/new-site.mjs" astro --dir . --force
    
    # The workspace is an existing project without git metadata; the slug only supplies
    # deployment identity and the base path. Output still goes into the workspace:
    node "$SKILL_DIR/scripts/new-site.mjs" astro --repo octocat/blog --dir . --force
    
    # Create a subfolder only when the user explicitly requested one:
    node "$SKILL_DIR/scripts/new-site.mjs" react-vite --repo octocat/dashboard --dir ./site
    
    # A user site (served from "/") or a quick local scaffold:
    node "$SKILL_DIR/scripts/new-site.mjs" static-html --base / --dir . --force
    
    # Safely compose a skills catalog without touching the consumer's target:
    node "$SKILL_DIR/scripts/new-site.mjs" skills-catalog \
      --repo octocat/skills \
      --templates-dir ../gh-pages-templates/templates \
      --staging-dir ./.site-staging \
      --json
    ```
    
    The generator replaces the shared base and repository sentinels plus the catalog
    sentinels `__SITE_DESCRIPTION__`, `__REPO_OWNER__`, `__REPO_NAME__`,
    `__AUTHOR_NAME__`, and `__MARKETPLACE_ID__`. Injection is deterministic and the
    result has no placeholders left. After stamping you may hand-edit content freely.
    Metadata values must be plain context-safe text. Markup, control characters, and
    characters that can break JSON, YAML, JavaScript, or HTML attributes are rejected.
    
    ### Safe staging contract
    
    Use `--staging-dir` whenever `create-skills-repo` or another tool will merge the
    site into a larger output. The path must not exist and the option cannot be
    combined with `--dir` or `--force`. The generator performs replacement and all
    validation inside staging, returns only after success, and never touches the final
    target. The consumer must check every destination conflict before copying staged
    files.
    
    Before either staging success or normal apply, the generator:
    
    1. verifies an external registry checkout matches the requested full commit SHA;
    2. proves the resolved template path remains inside the registry templates root;
    3. rejects every symlink in the template tree;
    4. rejects unresolved `__SENTINEL__` placeholders;
    5. scans `.github/workflows/*.yml` and `.yaml` for excess permissions, unsafe
       triggers, non-SHA action references, persisted checkout credentials,
       lifecycle-capable installs without script suppression, and direct GitHub
       context interpolation in shell commands.
    
    Normal `--dir` generation uses a private staging directory and applies only after
    all checks pass. This preserves existing template and `--force` behavior while
    ensuring an invalid template cannot partially modify the target.
    
    The exact pinned built-in snapshot has a compatibility normalization for its five
    legacy templates. It upgrades their known action tags to reviewed commit SHAs,
    disables persisted checkout credentials and lifecycle scripts, and then validates
    the result. Never apply this normalization to a custom registry.
    
    ## Digest the repo, then author it (never ship the template defaults)
    
    ### 1. Run the digest
    
    ```sh
    node scripts/digest-repo.mjs --dir <path-to-repo> --json
    ```
    
    It returns deterministic signals you build from: `name`, `description` (the pitch),
    `repoSlug`, `license`, a `type` classification (`cli` | `library` | `app` |
    `action` | `collection` | `docs` | `site`) with the reasons behind it, suggested
    `install` commands, README `usageExamples` (code fences), `badges`, `docFiles`,
    existing `images` (with role hints like `logo`/`hero`/`screenshot`), `languages`,
    and `subProjects` (for monorepos/collections). Read the repo's README and key docs
    yourself too — the digest points you at them; it doesn't replace judgment.
    
    ### 2. Build the right *kind* of site for the type
    
    | Type | Tell-tale signals | Author the site around… |
    | --- | --- | --- |
    | `cli` | `bin`, console_scripts, `[[bin]]`, `--help` in README | Install + Quickstart, then a **command/flag reference** (a section or page per command), copy-paste examples, config/exit codes. Hero = terminal demo. |
    | `library` | `main`/`exports`, `[lib]`, import examples | Install, an **import + usage** snippet, an **API reference** (exported functions/types from the README/docs), examples, badges. Hero = a concept diagram. |
    | `app` | web-framework dep, `index.html`, `src/` | A **feature tour** with screenshots, a "Get started"/live-demo CTA. Hero = an app screenshot. |
    | `action` | `action.yml` | A `uses:` snippet, an **inputs/outputs table**, an example workflow. |
    | `collection` | `plugin.json`/`marketplace.json` + `skills/`, workspaces, `packages/` | A **catalog**: one card/detail per `subProject` (its pitch + install), plus a top-level install for the whole thing. Hero = a banner; per-item thumbnails. |
    | `docs` | many Markdown docs, little code | A **docs nav + content**, pulling the existing Markdown in. |
    | `site` / unknown | none of the above | A clean landing built from the repo's pitch and links. If the shape is unclear, ask the user what sections they want. |
    
    ### 3. Authoring rules
    
    - **Replace every default.** No template demo copy survives — not the sample hero,
      not "Hello, Astro/world", not the example blog posts, not lorem. After building,
      grep the output for the template's stock phrases; none should remain.
    - **Use real values from the digest:** the repo's name and `description` as the
      title/tagline, the `install` commands verbatim, the README `usageExamples` as
      real code blocks, `badges`, `license`, and links to the repo and each
      `subProject`. **Don't invent** features, commands, or APIs you can't see in the
      repo — if something's unclear, leave a visible `TODO` for the user rather than
      fabricate.
    - **Fit the template's content model.** Use content collections (Astro/Eleventy:
      one entry per command/skill/post), pages (React/static), etc. Add or rename
      routes to match the content (e.g. a `commands/` or `catalog/` section) instead of
      forcing everything into the demo "blog". Keep the GitHub source link and the
      base-path-aware internal links the template already wires — never hand-write
      absolute `/...` links (use the template's base helper, or it breaks on a project
      site).
    - **Keep Spectator free-form.** Do not force a standard specification outline.
      Derive pages, headings, and navigation from the supplied context. Preserve the
      Spectator reading and feedback system, but remove every Project Northstar sample
      page, label, requirement, source, and image reference.
    - **Label uncertainty in Spectator.** Distinguish verified current behavior,
      user-approved decisions, proposals, assumptions, risks, and open questions.
      Do not invent owners, dates, requirements, interfaces, or security claims.
    
    ### 4. Add image placeholders the user can supply
    
    Real sites need art the agent can't produce. Drop in **obvious placeholders** plus
    a checklist so the user knows exactly what to provide:
    
    ```sh
    node scripts/make-placeholder.mjs --out <site>/<images-dir> --preset <type> --repo owner/name
    ```
    
    `--preset` is the repo type (`cli`/`library`/`app`/`collection`/`site`). It writes
    labeled SVG placeholders (logo, social card, favicon, hero, and type-specific
    shots) and an `IMAGES.md` manifest listing each file's purpose and recommended
    dimensions. Then:
    
    - **Reference them** from the pages you author — hero, top-bar logo, the OG/social
      meta tag, and per-item thumbnails for a catalog.
    - **Reuse real images first.** If the digest found an existing logo or screenshot
      (e.g. a `docs/*.png`), use it instead of a placeholder.
    - **Put images where the template serves static files:**
      - `astro`, `react-vite` → `public/images/` (served at `${BASE_URL}images/…`)
      - `spectator` → `docs/public/images/` (VitePress applies its configured base)
      - `static-html` → `assets/images/` (relative `./assets/images/…`)
      - `eleventy` → `src/assets/images/` (through the `url` filter)
      - `jekyll` → `assets/images/` (via `relative_url`)
    - **Leave `IMAGES.md` in the images dir** as the hand-off, and tell the user it's
      there. A placeholder still deploys fine; it just visibly says "replace me".
    
    ### Ask for real images
    
    After authoring, ask only for images the site references. Give each role, filename,
    and recommended dimensions; accept pasted images, file paths, or URLs. Keep
    unprovided placeholders, update `IMAGES.md`, and do not block deployment.
    `digest-repo.mjs` discovers source material; `make-placeholder.mjs` creates the
    placeholder set and handoff manifest.
    
    ## Per-template notes
    
    - **static-html** — Zero build. All links are relative, so it's base-path-proof.
      Ships `index.html`, `about.html`, `404.html`, `assets/`, and a `.nojekyll`.
    - **astro** — `site` = origin, `base` = `/repo/`. Internal links use
      `import.meta.env.BASE_URL`. `public/` is copied verbatim. Node 24 in CI by default.
    - **react-vite** — `base` in `vite.config.js`; React Router `basename` derived from
      `BASE_URL`; `copy-404.mjs` (a `postbuild` hook) copies `index.html` → `404.html`
      so deep-link refreshes work on Pages. Reference public assets as `/asset` so Vite
      rewrites them with the base.
    - **eleventy** — `pathPrefix` comes from the `PATH_PREFIX` env the workflow sets;
      every link/asset uses the `url` filter. Posts live in `src/posts/`, listed via
      `collections.posts`. Locally it serves at `/`.
    - **jekyll** — `baseurl` (no trailing slash) in `_config.yml`; links use
      `relative_url`. Built in CI by `jekyll-build-pages` (honors the `Gemfile`). Local
      dev needs Ruby + Bundler; CI does not.
    - **spectator**: VitePress reads `base` from `spectator.config.ts`. Content is
      free-form Markdown under `docs/`; navigation is explicit in the shared config.
      Preserve local search, page outlines, light/dark appearance, plain-language
      callouts, page feedback, selected-text feedback, and GitHub edit links. Run
      `npm test`, `npm run build`, and `npm run test:e2e`.
    
    ## Current repo vs. new repo
    - **Current repo (the default)**: assume the site is for the repo in context. The
      generator infers the base path from its `origin` remote when you omit `--repo`.
      Put the site at the root for a whole-repo site, or in a subfolder and point the
      workflow's `upload-pages-artifact` `path:` at it. If a `deploy.yml` already exists,
      reconcile — don't blindly overwrite.
    - **New repo (only when asked)**: create with `gh repo create`, stamp, push to
      `main`. For a **user site**, the repo MUST be named `<user>.github.io` and the base
      is `/` — the generator handles the base when you pass that repo name.
    
    ## Custom domains (documented, not automated)
    For a custom domain: add a `CNAME` file (for static/Jekyll, at the served root;
    for Astro, `public/CNAME`), set DNS at the registrar, and in Astro set `site` to
    the domain and drop `base`. Don't automate DNS — explain the steps.
    
    ## Template registry & contributing
    Templates live in **one** place: the
    **[`jongio/gh-pages-templates`](https://github.com/jongio/gh-pages-templates)**
    registry. The skill does **not** bundle its own copy — the generator fetches
    templates from the registry at runtime (override with `--registry <owner/repo>`, or
    scaffold offline from a local checkout with `--templates-dir <path>`):
    
    ```sh
    node scripts/new-site.mjs astro --repo octocat/blog            # pinned default registry
    node scripts/new-site.mjs skills-catalog --repo octocat/skills \
      --registry octocat/templates --registry-ref 0123456789abcdef0123456789abcdef01234567
    node scripts/new-site.mjs astro --templates-dir ../gh-pages-templates/templates
    ```
    
    Each template is a folder with a `template.json` manifest, a deploy workflow,
    base-path handling via the sentinels, and a `README.md`. The registry also renders
    the browsable gallery (live previews of every template) at
    **https://jongio.github.io/gh-pages-templates/** — the single home for browsing and
    previewing. Point users there to browse, and to the registry's `CONTRIBUTING.md` to
    submit a new template. Template changes (add/fix a template, bump an action version)
    land in the registry, not here.
    
    ## Validate — don't claim done on a green check
    
    1. **Content check first.** Confirm the site is about the repo, not the template:
       the title/tagline, install commands, and examples are the repo's real values, and
       **no template demo copy survives** (grep the built output for the template's stock
       phrases — "Hello", "islands", "lorem", the sample post titles — and for leftover
       `__…__` sentinels). The page kind matches the repo type (CLI ref / API ref /
       feature tour / catalog). Image placeholders exist and `IMAGES.md` is present.
    2. **Build it.** For `astro`/`react-vite`/`eleventy`/`spectator`, run
       `npm ci --ignore-scripts --no-audit --no-fund` then `npm run build` and confirm
       both exit 0 and emit the output dir
       (`dist` / `_site`). For `jekyll`, `bundle exec jekyll build` if Ruby is present.
    3. **Check the base path.** Open the built output and confirm asset/link URLs carry
       the project prefix (`/repo/...`) — not bare `/...`. This is the failure mode that
       "looks deployed but renders blank."
    4. **After deploy**, load the live `page_url` from the Actions run; click an
       internal link and (for the SPA) refresh a sub-route to confirm the `404.html`
       fallback works.
    5. Only then report it as working.
    
    Run the skill's own tests with `npm test` (the generator + the repo-digest and
    placeholder checks, offline via a fixture). Template/workflow validation lives in
    the `jongio/gh-pages-templates` registry.
    
    ## Footguns
    - **Never** ship a project site built for `/` — assets 404. Set the base path (the generator does this; verify it).
    - **Never** put a subpath base on a **user site** (`<user>.github.io`) — it must be `/` (Jekyll: `baseurl: ""`).
    - **Never** use `actions/upload-artifact` for Pages — it's `upload-pages-artifact`.
    - **Never** reach for `peaceiris/actions-gh-pages` or a `gh-pages` branch — use the first-party Actions flow these templates ship.
    - **Never** forget to set **Source → GitHub Actions** in Settings → Pages; the workflow can't publish until Pages is enabled for Actions.
    - **Don't** leave the repo "Website" link blank — set `homepage` to the Pages URL (`gh repo edit --homepage`) so visitors find the site; it's the same as the "Use your GitHub Pages website" checkbox.
    - **Never** claim success because the workflow is green — load the URL and check an asset and an internal link actually resolve.
    - **Never** ship the template's demo content. A stamped template that still says
      "Hello, Astro", lists sample blog posts, or contains Project Northstar is a
      failure. Digest the repo and author real content of the right kind.
    - **Never** fabricate features, commands, or APIs to fill the page. Author only what
      the repo actually shows; leave a visible `TODO` when unsure.
    - **Don't** leave bare image references with nothing behind them — add the placeholders + `IMAGES.md`, or reuse the repo's existing images.
    - **Don't** ship placeholders silently — tell the user which real images the site needs and that they can paste a screenshot into the chat to fill each one.
    - **Don't** hand-roll a base-path setup when the generator + sentinels already do it correctly per framework.
    - **Never** pass a branch or tag as `--registry-ref`. Only a full commit SHA is
      immutable enough to validate.
    - **Never** compose directly into another generator's target. Stage first, check conflicts, then merge.
    
  • thumbnail.png 243.8 KB · in bundle

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.