pb-docs-site
Publish a project's docs as a static HTML manual on GitHub Pages: check that Pages is enabled, bring the wiki up to date, list the doc gaps, build the site, preview it locally and push it after GO. Us
SKILL.mdskills/playbooks/pb-docs-site/SKILL.md
GitHubPublish a docs site
What you get: the project's docs as a static HTML manual on GitHub Pages, pushed only after your GO.
Inputs
- repo — the local checkout, default the current directory;
<owner/repo>comes fromgit -C <repo> remote get-url origin - source — where the content lives: OpenWiki pages, the README, or
docs/
Steps
- Preflight —
gh auth status, thengh api repos/<owner>/<repo>/pages→ run log header — gh missing, unauthenticated or no GitHub remote → log it, give thegh auth login/ remote hint, stop; 404 → stop with "Pages not enabled: enable it in repo settings", this playbook does not enable Pages; a private repo whose Pages call is refused for plan reasons → stop with "Pages on a private repo needs a paid plan", and never change the repo's visibility. Then openwiki-skill — wiki refreshed or confirmed current → log line — Pages answered and the wiki is current - readme and documentation —
sourceagainst the code → list of doc gaps in the run log — stops for approval - bdbhtmlmanueldocs — approved content → site files in
docs/(or the Pages source path the step 1 response names) — files written, nothing committed; the skill's Pages build-type switch (gh api -X PUT .../pages) and its Pages deploy workflow are NOT run here, only the site files are written - Preview — a local preview link or the path to the built
index.htmlin the run log — link or path given - [GO] git push — the site files committed to the branch and path the step 1 response names as the Pages source; the WAITING FOR GO line names the branch and the file list. The WAITING FOR GO line also says: a Pages site of a private repo is public. The run stops here until the human types GO. Where the hook runs, it covers
git push; it does not covergh apisettings writes, so no Pages setting or workflow is changed in this playbook. - github —
gh api repos/<owner>/<repo>/pages -q .statusequalsbuilt(poll, at most 5 minutes), thencurl -sI <pages_url>→ status line in the run log — returns 200
Run log: production_artifacts/pb-docs-site-<date>.md in the start directory, never committed
Rules
- Anything other than the literal GO (case-insensitive) is not a GO; a GO covers only that one step, one time.
- GO is by contract in every harness. The go-gate hook is only a backstop on Claude Code, OpenCode and agy (Codex: unverified; Cursor, Kimi: none). A missing hook is never permission to proceed.
- A failed check stops the run: write the failure into the run log and report. No silent retries.
- Write one run-log line per step as it completes (
N. done|skipped|failed — artifact — check result) andWAITING FOR GO: <step>at each gate.