doc-pr

Orchestrate an editorial review for pull requests targeting dev. Reviews changed markdown files and posts a structured comment to the PR. Vale and Dale issues are auto-fixed separately by the vale-autofix workflow. Use this skill whenever a PR involves markdown files in docs/ and targets the dev branch — triggered automatically by the doc-pr GitHub Actions workflow on PR open, sync, or when invoked manually via /doc-pr.

1.92x

Quality

88%

Does it follow best practices?

Impact

77%

1.92x

Average score across 3 eval scenarios

Securityby

—

The risk profile of this skill

Quality

Content

88%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-crafted operational skill: commands, paths, templates, and failure paths are all concrete, and the workflow is sequenced with real error-recovery loops. The only quality levers are small: reduce repetition of the Vale/Dale boundary and consider extracting the output template.

Suggestions

State the Vale/Dale separation once (e.g. in the opening paragraph) and drop the repetition in Behavioral Notes.

Move the mandatory review-comment template into a reference file (e.g. references/review-template.md) and point to it, trimming the body's token footprint.

Dimension	Reasoning	Score
Conciseness	The body is lean and directive — no concept explanations Claude already knows, and every section drives execution. Minor trimmable redundancy: the Vale/Dale separation is stated three times (opening, output template, Behavioral Notes) and lines like 'the review is useless if it is not posted' are emphasis padding, so it sits at 4 rather than 5.	4 / 5
Actionability	Fully executable guidance throughout: exact commands ('gh pr comment $DOC_PR_NUMBER --repo $DOC_PR_REPO --body-file /tmp/doc-pr-review.md', env var inspection), exact file paths (/tmp/pr-diff.txt), an explicit input fallback chain, and a complete copy-paste review-comment template. Not lower because no step relies on vague direction.	5 / 5
Workflow Clarity	The sequence is explicit (inputs → KB exclusion → diff → full-file read → analyze added lines → write file → post comment) with genuine error-recovery loops: empty env vars fall back to positional args then 'gh pr view'/'gh pr diff', a KB-only file list exits with a posted note, and a failed 'gh pr comment' must be reported rather than silently dropped. The skill is read-only, so the destructive-operation validation cap does not apply.	5 / 5
Progressive Disclosure	No bundle files exist, and the body is well-sectioned with a clean one-level external reference ('Read docs/CLAUDE.md before starting'). The ~30-line mandatory output template is inlined where it is used, which is defensible but is the kind of content that could live in a reference file — a minor organization gap that keeps it at 4 rather than 5.	4 / 5
	Total	18 / 20 Passed

Description

87%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: third-person, concrete about actions, and with an explicit 'Use this skill whenever...' trigger clause that clearly delimits its scope. Minor room to broaden natural trigger phrasing and to hint at what the editorial review covers.

Suggestions

Add one or two natural synonyms to the trigger clause (e.g. 'documentation review' or 'docs changes') so users phrasing the need differently still match.

Briefly name the editorial dimensions checked (structure, clarity, completeness) so the 'what' is fully self-contained.

Dimension	Reasoning	Score
Specificity	The description lists several concrete actions — 'Orchestrate an editorial review', 'Reviews changed markdown files', 'posts a structured comment to the PR' — with only minor gaps (it does not enumerate what the editorial review actually checks). Not 5 because coverage of capabilities is not comprehensive; not 3 because more than 1-2 specific actions are named.	4 / 5
Completeness	It clearly answers both questions: what ('Orchestrate an editorial review... Reviews changed markdown files and posts a structured comment') and when ('Use this skill whenever a PR involves markdown files in docs/ and targets the dev branch'), with concrete trigger conditions (PR open, sync, manual /doc-pr). Matches the 5 anchor exactly; a 4 would require the 'when' to be less explicit.	5 / 5
Trigger Term Quality	Good natural keyword coverage: 'pull requests', 'PR', 'markdown files', 'docs/', 'dev branch', '/doc-pr'. A few natural phrasings users might say are missing (e.g. 'documentation review', 'docs changes'), keeping it below the comprehensive-with-synonyms level of 5.	4 / 5
Distinctiveness Conflict Risk	A clear niche — editorial review of markdown changes in docs/ on PRs targeting dev — with explicit boundary separation from the vale-autofix workflow ('Vale and Dale issues are auto-fixed separately'), so it is unlikely to trigger for the wrong skill.	5 / 5
	Total	18 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: netwrix/docs
Path: .claude/skills/doc-pr/SKILL.md
Commit: 5844ab3

Reviewed: 12 hours ago

Table of Contents

Discovery Implementation Validation

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.