create-gh-pages-site

Files (44)

• .gitignore
• .npmrc
• .vally.yaml
• CONTRIBUTING.md
• LICENSE
• README.md
• SKILL.md
• README.md · evals/
• eval.yaml · evals/create-gh-pages-site/
• README.md · evals/create-gh-pages-site/fixtures/astro-cli/
• package.json · evals/create-gh-pages-site/fixtures/astro-cli/
• deploy.yml · evals/create-gh-pages-site/fixtures/skills-catalog/
• index.html · evals/create-gh-pages-site/fixtures/skills-catalog/
• template.json · evals/create-gh-pages-site/fixtures/skills-catalog/
• README.md · evals/create-gh-pages-site/fixtures/skills-repo/
• alpha-skill.md · evals/create-gh-pages-site/fixtures/skills-repo/
• do-not-overwrite.txt · evals/create-gh-pages-site/fixtures/skills-repo/
• README.md · evals/create-gh-pages-site/fixtures/spectator-repo/
• proposal-notes.md · evals/create-gh-pages-site/fixtures/spectator-repo/
• deploy.yml · evals/create-gh-pages-site/fixtures/spectator/.github/workflows/
• config.mts · evals/create-gh-pages-site/fixtures/spectator/docs/.vitepress/
• FeedbackPrompt.vue · evals/create-gh-pages-site/fixtures/spectator/docs/.vitepress/theme/
• SelectionActions.vue · evals/create-gh-pages-site/fixtures/spectator/docs/.vitepress/theme/
• index.ts · evals/create-gh-pages-site/fixtures/spectator/docs/.vitepress/theme/
• index.md · evals/create-gh-pages-site/fixtures/spectator/docs/
• proposal.md · evals/create-gh-pages-site/fixtures/spectator/docs/
• system-shape.md · evals/create-gh-pages-site/fixtures/spectator/docs/
• package.json · evals/create-gh-pages-site/fixtures/spectator/
• spectator.config.ts · evals/create-gh-pages-site/fixtures/spectator/
• template.json · evals/create-gh-pages-site/fixtures/spectator/
• README.md · evals/create-gh-pages-site/fixtures/static-library/
• package.json · evals/create-gh-pages-site/fixtures/static-library/
• package-lock.json
• package.json
• digest-repo.mjs · scripts/
• install-local.ps1 · scripts/
• make-placeholder.mjs · scripts/
• new-site-cli.mjs · scripts/
• new-site.mjs · scripts/
• template-registry.mjs · scripts/
• template-security.mjs · scripts/
• digest.test.mjs · test/
• generator.test.mjs · test/
• thumbnail.png

SKILL.md (first lines)

# 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

From jongio/skills, MIT.

More from jongio/skills