Tighten agent instructions and add docs workflow skills - #1076
Merged
Conversation
Add "Document current behavior" section (docs are not a changelog, prefer positive statements, scoped exception for breaking changes), jargon-translation guidance, and admonition redundancy rules to AGENTS.md and STYLE-GUIDE.md. Add four LLM-pattern rows to the docs-review skill and fix its placeholder guidance to match the example.com convention. Add "write the end state" discipline to the upstream-release-docs skill. Rewrite the auto-generated content instruction with rationale and the complete path list. Refs #1074 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The agent format predates skills. Convert to a skill for consistency with the other docs workflows, fix the broken STYLE_GUIDE.md reference, and rescope the framing: guides get the server working with ToolHive, keeping upstream details to a line with a link. Refs #1075 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Defer to the AGENTS.md word list as the single source of truth for product names instead of maintaining a divergent copy. Drop the unsanctioned "ToolHive Portal" and "ToolHive Gateway" entries and replace "Desktop UI" with ToolHive UI. Refs #1075 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
move-page encodes the five coupled steps of relocating a docs page (file move, sidebars.ts, inbound link sweep, vercel.json redirect, build verification), validated by an end-to-end test run in an isolated worktree. review-docs-pr wraps PR review mechanics (head-ref reads, thread resolution checks, body-level draft for approval) around the docs-review editorial criteria. Refs #1075 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR tightens the standing authoring/review instructions for ToolHive docs and expands the .claude/skills workflow tooling, aiming to reduce recurring editorial issues in agent-generated docs changes and to codify common docs-maintenance workflows.
Changes:
- Adds “Document current behavior” guidance (avoid changelog framing, prefer positive statements, scoped breaking-change exception) to AGENTS.md and STYLE-GUIDE.md, plus stricter admonition redundancy rules.
- Updates the
docs-review,upstream-release-docs, andweekly-product-updatesskills to align with the new guidance and the AGENTS.md word list. - Introduces new workflow skills (
move-page,review-docs-pr) and converts the priormcp-guide-writeragent into a skill.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| STYLE-GUIDE.md | Adds “Document current behavior” guidance and strengthens admonition usage rules. |
| AGENTS.md | Strengthens “Auto-generated content” rules and adds “Document current behavior” guidance. |
| .claude/skills/docs-review/SKILL.md | Extends editorial review criteria to catch changelog framing, redundant admonitions, and PR jargon leakage. |
| .claude/skills/upstream-release-docs/SKILL.md | Adds explicit “end state, not transition” instruction and jargon-translation guidance for release-driven doc edits. |
| .claude/skills/weekly-product-updates/SKILL.md | Aligns terminology guidance to AGENTS.md word list and updates UI naming. |
| .claude/skills/review-docs-pr/SKILL.md | Adds a PR-review workflow skill (head-ref reads, thread checks, body-level draft review). |
| .claude/skills/move-page/SKILL.md | Adds a page move/rename workflow skill (sidebar updates, link sweep, redirects, build verification). |
| .claude/skills/mcp-guide-writer/SKILL.md | Introduces mcp-guide-writer as a skill with a clearer scope and updated style guide reference. |
| .claude/agents/mcp-guide-writer.md | Removes the legacy agent definition now replaced by the skill. |
Comments suppressed due to low confidence (2)
STYLE-GUIDE.md:105
- Same accessibility concern as above: emoji shortcodes in the Yes/No example pair add nonessential screen-reader noise. Prefer plain "Yes:" / "No:" labels.
:white_check_mark: Yes: The Cloud UI uses the registry policy's `server_api_url`
value.\
:x: No: The Cloud UI reads `server_api_url`, not `api_url`.
.claude/skills/weekly-product-updates/SKILL.md:230
- Same repo URL mismatch as the summary-format section: this Cloud UI link points to
stacklok/toolhive-cloudbut the repo list namesstacklok/toolhive-cloud-ui. Align the URL.
- [ToolHive Cloud UI](https://github.com/stacklok/toolhive-cloud/releases)
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
danbarr
enabled auto-merge (squash)
July 30, 2026 16:49
rdimitrov
approved these changes
Jul 30, 2026
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.
Description
Codifies the recurring editorial failure patterns from agent-generated docs PRs into the standing instructions and skills, and adds two new workflow skills.
Style codification (AGENTS.md, STYLE-GUIDE.md, docs-review, upstream-release-docs): new "Document current behavior" section (docs are not a changelog; prefer positive statements; scoped exception for breaking or silently-behavioral changes as clearly labeled versioned admonitions), jargon-translation guidance, admonition redundancy rules, four new LLM-pattern rows in docs-review, and a corrected placeholder convention (
example.com,<ALL_CAPS>). The auto-generated content instruction is rewritten with the rationale, the upstream-fix alternative, and the previously missing CRD paths, prompted by the hand-edited CLI reference files on #1065.Skill updates: converts the pre-skills mcp-guide-writer agent to a skill (fixing a broken style guide reference and over-scoped framing) and aligns weekly-product-updates terminology to defer to the AGENTS.md word list.
New skills: move-page (file move, sidebars, inbound link sweep, redirect, build verification; validated end-to-end in an isolated worktree) and review-docs-pr (head-ref reads, thread-resolution checks, body-level draft-for-approval review flow).
Motivating examples: the review discussion on #1069 and the follow-up trims on #1065.
Type of change
Related issues/PRs
Submitter checklist
Content and formatting
Reviewer checklist
Content
🤖 Generated with Claude Code