docs-review
Reviews documentation PRs and provides GitHub PR suggestions. Load when asked to review, suggest changes, or provide feedback on docs content. Covers MDX, frontmatter, style guide, components, and content accuracy.
87
84%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
Quality
Discovery
92%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description that clearly communicates its purpose, lists concrete capabilities, and includes explicit trigger guidance with a 'Load when...' clause. The description covers specific technical areas (MDX, frontmatter, style guide) which helps differentiate it, though there is some potential overlap with general code review or writing feedback skills. The third-person voice is used correctly throughout.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Reviews documentation PRs', 'provides GitHub PR suggestions', and covers specific areas like 'MDX, frontmatter, style guide, components, and content accuracy'. | 3 / 3 |
Completeness | Clearly answers both what ('Reviews documentation PRs and provides GitHub PR suggestions') and when ('Load when asked to review, suggest changes, or provide feedback on docs content') with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would say: 'review', 'suggest changes', 'feedback', 'docs', 'PR', 'documentation'. Also includes technical but relevant terms like 'MDX', 'frontmatter' that documentation authors would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Fairly specific to documentation PRs, but could overlap with general code review skills or generic PR review skills. The mention of 'MDX, frontmatter' helps narrow the niche, but 'provide feedback on docs content' is broad enough to potentially conflict with general writing or editing skills. | 2 / 3 |
Total | 11 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, highly actionable skill that provides clear decision logic for when to suggest vs. edit, complete executable examples for posting GitHub suggestions via the gh CLI, and a well-structured review process with severity-based prioritization. Its main weakness is length — some content is slightly redundant (overlapping decision tables) and the detailed API examples could be offloaded to a reference file. The output format section is particularly well-crafted with clear anti-patterns.
Suggestions
Consider moving the detailed GitHub suggestion API examples (single-line, multi-line, batching) into a separate reference file like `references/gh-suggestions.md` to keep the main skill more concise.
The decision logic section has both a numbered list and a quick reference table that overlap — consolidate into just the table to reduce redundancy.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is generally well-written and avoids explaining basic concepts, but it's quite long. Some sections like the decision logic table and quick reference table overlap significantly, and the content review principles section restates things that could be more compressed. However, most content is domain-specific and earns its place. | 2 / 3 |
Actionability | Excellent actionability throughout. Every GitHub suggestion workflow includes complete, copy-paste-ready bash commands with correct gh CLI syntax. The review checklist has specific rules with concrete examples, and the decision logic table maps exact phrases to exact actions. | 3 / 3 |
Workflow Clarity | The review process is clearly sequenced (read diff → check rules → assess what to flag → prioritize by severity). The suggest-vs-edit decision logic includes explicit branching conditions. The severity ordering (build breakers → incorrect content → missing best practices → style) provides a clear prioritization framework with implicit validation checkpoints. | 3 / 3 |
Progressive Disclosure | The skill references external files like `references/content-rules.md`, `AGENTS.md`, and the style guide at `src/content/docs/style-guide/`, which is good. However, no bundle files are provided to verify these exist, and the skill itself is quite long — the detailed GitHub API suggestion examples and the full rules tables could potentially be split into reference files to keep the main skill leaner. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- cloudflare/cloudflare-docs
- Commit
9a170b9
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.