Skip to content

ValentinNikolaev/agent-skills / agent-plugins/skills/github-pages-create

github-pages-create

Verified

Build or repair GitHub Pages sites from repository evidence. Use for immediate implementation and authorized delivery configuration. Staged proposals and resuming approved GP- IDs belong to github-pages-improve.

GitHub Pages: Create

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

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 when the task requires a content inventory, reader journeys, page hierarchy, navigation labels, documentation copy, or local-search behavior.
  • Use github-pages-design when the task requires visual direction, extension or redesign, tokens, branding, typography, spacing, layout, themes, or responsive implementation. Its direction and redesign reference supplies the brief, change mode, and early preview procedure; keep them inside the authorized scope.
  • Use github-pages-audit for a read-only audit of a rendered production-equivalent Pages build.
  • Use github-pages-improve 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.

Follow the applicable flow

  1. Resolve immediate implementation, staged proposals, audit-only, or a specialist-only task, available tools, and the already authorized scope. Resume approved GP- selections without returning to Phase 1. github-pages-improve retains their IDs and approval state.
  2. Establish repository truth and protected contracts, including supplied or already accessible Wiki material checked against current sources. Wiki access does not authorize Wiki edits.
  3. Apply the content pass and pass its sources, actual copy, gaps, and route/anchor requirements to design and implementation.
  4. Apply the design pass inside the existing system. Show a representative preview with real content early for a material new direction, then continue authorized work.
  5. Implement the smallest sufficient change in the viable existing stack.
  6. Build production output and preview it under the expected Pages base path.
  7. Request the read-only rendered audit for applicable journeys, viewports, themes, and states, with an identified build handoff.
  8. Correct confirmed in-scope defects and repeat affected checks. Stop when the requested outcome and applicable verification are complete.
  9. Return evidence, remaining unknowns, and exact delivery status. Publication requires separate authorization.

For a small change, combine passes in a compact report. Content-only or design-only work does not require an unrelated rebuild. An audit-only request never enters implementation. Missing tooling leaves specific checks not verified, not passed by source inspection.

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;
  • supplied or available Wiki pages, their freshness against current repository sources, and inaccessible evidence gaps;
  • 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 github-pages-design for the visual system and follow the navigation, search, code-copy, callout, and overflow rules in quality-and-deployment.md.
  • Prefer framework-native components over custom client code.
  • Remove filler, demo links, empty pages, unused assets, and stock claims.
  • 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.

Preserve routes during migrations

Before changing frameworks, content roots, slugs, or headings that generate anchors:

  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, request the github-pages-audit rendered audit for 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

Use the shared handoff format. 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.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall