writing-guidelines

Review or write docs/prose for Writing Guidelines compliance. Use when asked to "review my docs", "check writing style", "audit prose", "review docs voice and tone", "check this page against the writing handbook" — and proactively whenever writing or editing content under docs/src/content/docs/, since that's this repo's default docs style.

Quality

89%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

85%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 tight, highly actionable skill body that rewards Claude's competence with repo-specific rules and an explicit verification loop for its riskiest operation. The only soft spots are a few trimmable rationale parentheticals and a missing example of the review-mode output format.

Suggestions

Show a one-line example of the `file:line` review output format so the review-mode instruction is copy-paste concrete.

Trim rationale parentheticals in the house-style bullets (e.g., "called out here because…") to tighten conciseness without losing the rule.

Dimension	Reasoning	Score
Conciseness	Dense, high-signal bullets each carrying a distinct hard-won rule with no basic-concept padding; a few parenthetical justifications ("called out here because…", "since that's this repo's default docs style") could be trimmed to reach fully lean.	4 / 5
Actionability	Concrete, specific commands throughout (`pnpm --filter cva build`, `dist/index.mjs`, exact import forms, exact file paths) with a clear fetch-fallback; minor gap is the absent literal example of the promised `file:line` review output format.	4 / 5
Workflow Clarity	Two clear numbered sequences (How It Works, Reviewing) plus an explicit verify-before-commit feedback loop for the highest-value bug class — build the package and run examples verbatim to capture real output — satisfying the destructive/batch validation checkpoint.	5 / 5
Progressive Disclosure	Sub-50-line body with well-organized sections and only one-level-deep, clearly signaled references (`#cva-house-style`, `/AGENTS.md`, one fetch URL); no bundle files and no nested references.	5 / 5
	Total	18 / 20 Passed

Description

95%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, specific description with a clear what/when pair and abundant natural trigger phrases. The only minor gap is that the action verbs (review, write) are fewer than the comprehensive set a 5-level specificity anchor calls for.

Suggestions

Add one or two more concrete actions (e.g., 'fixes violations', 'rewrites prose') to push specificity toward comprehensive coverage.

Consider naming a file extension or output artifact type to mirror the trigger-term breadth of the best examples.

Dimension	Reasoning	Score
Specificity	"Review or write docs/prose for Writing Guidelines compliance" names the domain plus several concrete actions (review, write, compliance-check); short of the comprehensive multi-action coverage of a 5.	4 / 5
Completeness	Explicitly states what it does (review/write docs/prose for Writing Guidelines compliance) and when to use it (quoted trigger phrases plus the proactive docs-path trigger), matching the 5 anchor.	5 / 5
Trigger Term Quality	Quotes many natural user phrases verbatim — "review my docs", "check writing style", "audit prose", "review docs voice and tone", "check this page against the writing handbook" — plus a proactive trigger, giving comprehensive synonym coverage.	5 / 5
Distinctiveness Conflict Risk	Tightly scoped to Writing Guidelines compliance for this repo's docs path with distinct, niche-specific triggers; minimal conflict risk with other skills.	5 / 5
	Total	19 / 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
relative_links	Relative link issues: 2 suspicious	Warning

	Total	15 / 16 Passed

Repository: joe-bell/cva
Path: .agents/skills/writing-guidelines/SKILL.md
Commit: b06a7c8

Reviewed: 7 days 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.