Skip to content

Correct and refine the docs-review skill #657

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
danbarr merged 1 commit into from
Mar 31, 2026
Merged

Correct and refine the docs-review skill #657

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .claude/skills/docs-review/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,8 @@ The docs follow a product-area-based information architecture under `docs/toolhi
- **Self-contained sections**: Product-specific content belongs in its product section (`docs/toolhive/guides-ui/`, `guides-cli/`, `guides-k8s/`, `guides-vmcp/`, `guides-registry/`), not in a shared section.
- **Quickstarts in product sections**: Quickstarts live inside their product section, not in a separate top-level section.
- **Integration placement**: Third-party integration guides (ngrok, Vault, OpenTelemetry, Okta, etc.) belong in `integrations/`, not in a product section.
- **Next steps section**: Every how-to guide and tutorial page must end with a "Next steps" section containing 1-3 forward links. Missing "Next steps" is a primary issue.
- **Page ending pattern**: How-to guides and tutorials follow this closing pattern: Next steps > Related information > Troubleshooting (if applicable). "Next steps" contains 1-3 forward links to the next logical pages. Missing "Next steps" is a primary issue.
Copy link

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "Page ending pattern" bullet asserts a strict section ordering (Next steps > Related information > Troubleshooting), but this doesn’t appear to be a consistently followed convention in the repo and it may conflict with the style guide’s guidance. For example, STYLE-GUIDE.md:169 says pages "end with" a "## Next steps" section, while some existing how-to guides place Troubleshooting before Next steps (e.g., docs/toolhive/guides-ui/playground.mdx:204-267). Consider rewording this as a preferred/common pattern (or aligning it explicitly with STYLE-GUIDE.md) rather than a requirement reviewers should enforce.

Suggested change
- **Page ending pattern**: How-to guides and tutorials follow this closing pattern: Next steps > Related information > Troubleshooting (if applicable). "Next steps" contains 1-3 forward links to the next logical pages. Missing "Next steps" is a primary issue.
- **Page ending pattern**: Per the style guide, pages should end with a **Next steps** section that links to 1–3 logical follow-on pages. A common closing pattern for how-to guides and tutorials is: Next steps, then Related information, and optionally Troubleshooting. Treat this as a preferred pattern (when it fits), but always flag missing **Next steps** as a primary issue.

Copilot uses AI. Check for mistakes.
- **Inbound link coverage for new pages**: When a PR adds a new page, check that it is reachable beyond just the sidebar. New pages need inbound links from related pages (overviews, intros, feature lists, related how-to guides). A page with no inbound links is isolated in the user journey. For major new features, also check whether top-level intro/overview pages should mention the capability.
- **Introduction pages**: Each product section should have an Introduction as the first sidebar child. New sections must follow this pattern.
- **Progressive disclosure**: Core workflows should appear before advanced topics. Check that advanced content isn't mixed in with beginner-facing pages.
- **Forward navigation path**: A reader should be able to follow "Next steps" links from the quickstart through core workflows without relying on the sidebar.
Expand Down Expand Up @@ -147,6 +148,7 @@ Structure your review as:
Before finalizing your review, verify:

- [ ] Did you check related documents for duplication or misplaced content?
- [ ] For new pages: did you check for sufficient inbound links from related pages (intros, overviews, feature lists)?
- [ ] Did you verify content belongs in the right document?
- [ ] Did you check for a project style guide?
- [ ] Are your recommendations actionable (not just "this is bad")?
Expand Down
Loading