Skills/docs authoring orchestrator#3452
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
mschristensen
force-pushed
the
skills/docs-authoring-orchestrator
branch
from
c541579 to
95d78b9
Compare
…docs Express the docs-writing guidance as folder-level AGENTS.md so it auto-loads when editing pages, instead of a skill-vendored rulebook: - src/pages/docs/AGENTS.md — structure/IA principles, feature-page tiers, page-type templates, the API-reference standard, code-accuracy workflow, and verification checks. - src/pages/docs/ai-transport/AGENTS.md — AI Transport positioning + terminology. Removes the 506-line .claude/skills/write-docs/SKILL.md monolith; its content now lives with the content it governs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
mschristensen
force-pushed
the
skills/docs-authoring-orchestrator
branch
from
95d78b9 to
1da3837
Compare
Given an SDK release/tag, PR(s), commits, or local changes (resolved via the shared code-resolve-changes skill over the Ably MCP), or a task, docs-plan writes docs-plan.md of single-purpose page units. Plans; docs-write builds. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drafts each page applying the folder AGENTS.md guidance, then runs the docs-review-* concerns and iterates to PASS, coordinating subagents like code-review-all. The write half of the write -> review loop. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…erns docs-review-all fans out five read-only concerns across subagents and synthesises one verdict (the docs analogue of code-review-all): docs-review-style, -structure, -code-accuracy, -terminology, -links. Each loads the shared review-conventions contract via the Ably MCP and checks against the folder AGENTS.md guidance. Concerns derive from the last 2 months of docs PR feedback. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
mschristensen
force-pushed
the
skills/docs-authoring-orchestrator
branch
from
1da3837 to
861ef3d
Compare
rainbowFi
left a comment
rainbowFi
left a comment
There was a problem hiding this comment.
Everything seems reasonable apart from the review-structure skill, which is (currently) specific to the AIT docs so should probably be AIT-only.
@m-hulbert will wait for your review and then make the changes to get this merged.
2 participants
What
Brings the plan → write → review-loop orchestrator pattern to the docs,
decomposes the
write-docsmonolith, and moves the docs-writing guidance intofolder
AGENTS.mdfiles. Skill names mirrorably-ai-transport-js(
docs-review-all+docs-review-*, likecode-review-all+code-review-*).The shared review contract (
review-conventions) and change resolver(
code-resolve-changes) load from ably-os over the Ably MCP (ably/ably-os#1608).Guidance → folder AGENTS.md
The 506-line
write-docs/SKILL.mdis retired; its guidance now lives with thecontent it governs and auto-loads when an agent edits those pages:
src/pages/docs/AGENTS.md— structure/IA principles, feature-page tiers,page-type templates, the API-reference standard, code-accuracy, verification.
src/pages/docs/ai-transport/AGENTS.md— AI Transport positioning + terminology.Skills no longer vendor guidance;
docs-writeapplies the folderAGENTS.md, andthe
docs-review-*concerns read it to check against.Skills
docs-plancode-resolve-changes) →docs-plan.mdof single-purpose page unitsdocs-writeAGENTS.md→ review loop → PASSdocs-review-allcode-review-all)docs-review-{style,structure,code-accuracy,terminology,links}review-conventionsvia MCPThe concerns derive from the last 2 months of docs PR feedback: de-claudeify
(
style), mechanism-first / concept-ordering / diagram-type (structure), SDKdrift + pre-release (
code-accuracy),root→object & barge-in vs interruption(
terminology), error-code searchability (links).Removed
.claude/skills/write-docs/SKILL.md— content relocated to theAGENTS.mdfiles.