Repository navigation
docs: add a docs.page setup skill - #555
Closed
claude[bot] wants to merge 9 commits into
Closed
claude[bot] wants to merge 9 commits into
claude[bot] wants to merge 9 commits into
Conversation
Add skills/docs-page-setup/SKILL.md, following the layout documented in skills/README.md (one folder per skill with a SKILL.md entry point). Every step is taken from docs/quickstart.mdx as it stands after #539: scaffold with `npx @docs.page/cli init`, push to a public GitHub repository, then open https://docs.page/{owner}/{repo}. Two additions beyond the quickstart, both useful to a developer and an agent: a note not to author docs.json keys from memory or validate against docs.page/schema.json (it marks 17 defaulted fields as required and omits name/description, so a correct minimal config fails), and an explicit definition of done so an agent verifies the rendered site rather than stopping at "files written". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BgG4JVuadUeZGtry1yFFd5
|
|
|
🚅 Deployed to the docs.page-pr-555 environment in docs.page 2 services not affected by this PR
|
Point agents at the canonical quickstart at runtime instead of inlining the walkthrough, and keep only the agent-specific delta that page cannot carry: the non-interactive `init` invocation, the docs.json schema caveat, a network-free pre-push verification, and a failure table keyed to the CLI's and app's real error strings. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BgG4JVuadUeZGtry1yFFd5
Narrow the description so it stops matching other docs tooling and QA of an existing site, and add an out-of-scope block for the same reason. Correct the CLI facts: pass npx --yes everywhere, describe --docs as explicit intent rather than an enabler (headless init already scaffolds docs/), note that --name also derives description, and drop the hardcoded count of dead starter URLs. Tell the agent to keep the $schema key init writes, for editor autocomplete, while still not validating the config against it, and to make the identifiable edit the quickstart asks for. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BgG4JVuadUeZGtry1yFFd5
The skill walked an agent straight into pushing to the default branch of a public repo, which publishes the docs to the open web immediately and irreversibly. Add a hard-stop gate: commit locally, then show the human the files, the target remote and branch, and the consequence, and push only on an explicit go-ahead. Reword the done conditions so the push is plainly the human's call rather than something the agent does unprompted. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BgG4JVuadUeZGtry1yFFd5
Rework the frontmatter description's push clause so it matches the confirm-before-push gate: the skill commits, and pushes only on the human's go-ahead. Add a final section that fires after the live-site done check and offers Customize (branding, SEO, analytics) and Agents (Ask AI) as a menu, not a walkthrough. Each item points at its canonical doc page and names the real docs.json keys, and the section restates that any choice means another commit and another push. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BgG4JVuadUeZGtry1yFFd5
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BgG4JVuadUeZGtry1yFFd5
Commit locally, confirm with a structured prompt where the host
supports one (chat fallback otherwise), and push to the default
branch only on approval. The prompt names the consequence: a push
publishes the docs immediately at docs.page/{owner}/{repo}.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BgG4JVuadUeZGtry1yFFd5
Restore the confirm-before-push gate on Alex's simplified section, and narrow the declined `--overwrite` path: `--no-docs` writes `docs.json` alone when only `docs/` exists, but is no way forward once `docs.json` itself exists, where `init` errors and writes nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BgG4JVuadUeZGtry1yFFd5
railway-app
Bot
temporarily deployed
to
docs.page / docs.page-pr-555
September 18, 2026 12:34
Destroyed
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Requested by Alex Duke · Slack thread
Summary
The repo had no skill telling an agent how to set up docs.page from cold, so agents improvised or re-derived a walkthrough that already exists.
This adds
skills/docs-page-setup/SKILL.md. It sends the agent to the canonical quickstart and carries only the agent-specific delta: non-interactiveinitflags, commit and, on the human's go-ahead, push to a public repo's default branch, then open the live URL once the config serves. Once live, it offers optional follow-on setup for branding, Ask AI, SEO and analytics, each linking its own docs page.Scope
Type of change
Test plan
Notes for reviewers
Discovery isn't automatic — there is no
.claude/skillsin this repo, so the skill is found only by an agent that opens the file.🤖 Generated with Claude Code
https://claude.ai/code/session_01BgG4JVuadUeZGtry1yFFd5