create-github-pages

name

create-github-pages

description

Create, modernize, or repair a repository-grounded GitHub Pages site, documentation portal, wiki, or landing page. Use when the user asks to build or improve a Pages site from repository content, or explicitly requests commit-driven Pages deployment. Preserve documentation, branding, public routes, and user changes; verify claims, build output, links, responsive UX, accessibility basics, dependencies, and any requested deployment configuration. Add deployment or AI-authored refresh automation only when the user requests it.

Create GitHub Pages

Build a useful, maintainable site from repository evidence.

Operating contract

• Inspect repository instructions, current changes, documentation, manifests, source, site files, Pages workflows, CNAME, and branding before editing.
• Preserve user work, canonical documentation, branding, and public URLs. Prefer improving a viable site over replacing it.
• Derive commands, examples, compatibility, API behavior, status, and other project claims from current repository evidence.
• Mark unknowns as unknown. Never invent metrics, testimonials, roadmaps, examples, or support claims.
• Keep one canonical source for each fact. Import or generate from existing Markdown when possible; avoid unsynchronized copies.
• Keep dependencies proportionate to the site.
• Do not commit, push, publish, change repository settings, buy a domain, or create credentials without explicit authorization.

Read the references

• Read references/framework-selection.md before choosing or changing the stack.
• Read references/quality-and-deployment.md before implementation and during final verification.

Coordinate the Pages specialists

Keep repository truth, framework choice, routes, build behavior, and deployment in this orchestrator. Apply the bundled specialist whose deliverable matches the work:

• Use github-pages-content-architecture when the task requires a content inventory, reader journeys, page hierarchy, navigation labels, documentation copy, or local-search behavior.
• Use github-pages-visual-system when the task requires visual tokens, branding, typography, spacing, layout, themes, or responsive implementation.
• Use audit-github-pages-ux for a read-only audit of a rendered production-equivalent Pages build.
• Use improve-github-pages when an existing site needs a staged audit, approval menu, and full or partial remediation rather than immediate implementation.

For a full site build, apply content architecture before visual implementation and run the rendered audit after the production build. Do not copy specialist instructions into this skill or move deployment ownership into a specialist.

Establish repository truth

Record:

• project type, languages, package manager, build system, and supported versions;
• intended readers and their first successful task;
• README, docs, examples, API references, changelog, contribution, security, license, screenshots, logos, and diagrams;
• current site stack, package scripts, workflow, Pages clues, custom domain, routes, and public URL assumptions;
• default branch, remote-derived owner/repository when available, and user/organization-site versus project-site base path;
• uncommitted changes and protected files.

Use commit history only to understand active areas or drift. Corroborate public claims against the current tree.

Define the smallest useful site

Choose an information architecture that supports real reader journeys. Include only evidence-backed sections such as:

1. home and primary action;
2. prerequisites, installation, and a minimal successful example;
3. task-oriented guides;
4. API, CLI, configuration, schema, or concept reference;
5. contribution, security, license, changelog, and support links.

Omit empty pages. Prefer one excellent page over a sparse multi-page site.

Select implementation and dependencies

Apply the framework reference. Preserve a healthy existing stack. Before adding or upgrading a framework, action, plugin, stylesheet, or runtime:

1. consult current official documentation and maintained-status evidence;
2. verify compatibility with the repository runtime and package manager;
3. inspect the lockfile and avoid introducing a second package manager;
4. prefer frozen or lockfile-honoring installs;
5. assess license, provenance, install scripts, external requests, and maintenance cost;
6. explain material dependency or migration cost before broad changes.

State the chosen stack, content root, build command, output directory, base path, dependency changes, and delivery plan before broad restructuring.

Design and implement

• Reuse suitable repository logos, screenshots, colors, and terminology.
• Apply the Pages visual-system specialist for accessible tokens, readable type, consistent spacing, visible focus, and coherent light/dark behavior.
• Prefer framework-native components over custom client code.
• Remove filler, demo links, empty pages, unused assets, and stock claims.
• Keep global navigation concise; use sidebars or page tables of contents for detail.
• Use one H1 per page and a logical heading hierarchy.
• Add sticky navigation or a table of contents only when content length warrants it.
• Add client-side search and accessible code-copy controls for multi-page technical docs when the selected stack supports them.
• Render callouts with text or icons as well as color.
• Prevent table, code, navigation, and media overflow at narrow widths.
• Avoid autoplay, scroll hijacking, and nonessential motion.

Preserve routes during migrations

Before changing frameworks, content roots, or slugs:

1. inventory existing public routes, anchors, assets, and CNAME behavior;
2. map each old route to a preserved route, redirect, or documented intentional removal;
3. keep a reviewable route/redirect manifest in the site configuration or project documentation when migration is material;
4. test representative legacy deep links under the production base path.

Do not claim URL preservation without this comparison.

Configure delivery only when requested

Create or change a GitHub Pages workflow only when the user asks for deployment, commit-driven updates, CI repair, or delivery configuration. If site authoring alone was requested, leave deployment unchanged and explain the available next step.

When requested, preserve a working workflow and follow the current official Pages custom-workflow pattern. Use the committed lockfile, least privileges, the real output directory, correct base path, one production owner, manual recovery, and safe concurrency.

Create scheduled or commit-triggered AI authoring only when explicitly requested. Keep generation separate from deployment, constrain secrets and writable paths, prevent loops, control spend, validate output deterministically, and create reviewable changes instead of direct production writes.

Verify in two layers

Static and build verification

Always run every applicable check that the environment supports:

• production build, type/configuration checks, and link checks;
• output directory, base-path assets, anchors, nested routes, not-found behavior, and legacy routes;
• dependency and lockfile consistency;
• workflow syntax, trigger, permissions, artifact path, environment, and custom-domain preservation when delivery changed;
• final diff for placeholders, secrets, local paths, caches, unrelated churn, or overwritten user changes.

Rendered browser and accessibility verification

When browser or accessibility tooling is available, apply the rendered Pages UX audit to representative desktop and narrow mobile journeys.

Do not claim rendered, interactive, or accessibility verification from source inspection alone. If the environment lacks rendering, browser control, dependency installation, or an audit tool, list the exact unverified checks and commands for completing them.

Handoff

Report the selected stack and evidence, pages and source material, dependency changes, preserved and redirected routes, build and preview commands, static verification, rendered verification, delivery status, expected base path, repository-setting steps, and remaining limitations.

Do not claim the site is live unless publication was authorized and confirmed.