Name: vale-linter
Rating: 89.4 (1 reviews)
Author: circleci

vale-linter

Run the Vale prose linter on CircleCI documentation files to identify and fix style errors, then create pull requests for review. Use this skill when the user explicitly asks to "run vale", "fix vale errors", "lint docs with vale", or mentions vale linting. This skill processes documentation files, fixes error-level Vale issues, and creates individual PRs per file for easier review.

1.33x

Quality

86%

Does it follow best practices?

Impact

91%

1.33x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Quality

Content

81%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.

The body is highly actionable and well-sequenced with strong validation feedback loops for a batch/PR-creating workflow. Its main weakness is redundancy in the Best Practices section, which restates workflow guidance and could be trimmed.

Suggestions

Collapse or remove the 'Best Practices' section where it duplicates the workflow steps (verify fixes, preserve formatting, stay focused); keep only genuinely new guidance.

Tighten step 4's fix-application bullets ('Preserve AsciiDoc formatting and structure' and 'Maintain existing line breaks and whitespace where possible') into a single concise line.

Consider extracting the long commit-message and PR-body templates into a bundled reference file to shorten the inline body and improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and well-sectioned, but the 'Best Practices' section substantially reiterates guidance already stated in the workflow steps (verify fixes, preserve formatting, stay focused), adding notable redundancy beyond minor trimmable bits.	3 / 5
Actionability	Fully executable guidance throughout — concrete vale/jq/git/gh commands and a copy-paste-ready PR-body heredoc covering the common cases.	5 / 5
Workflow Clarity	A clear 4-step sequence with prerequisites validation and an explicit re-run-Vale feedback loop with error-recovery branching, which is exactly the validation-checkpoint pattern the rubric rewards for batch operations.	5 / 5
Progressive Disclosure	Self-contained and well-organized into clear sections with only external repo paths (no nested skill-bundle references); minor organization gaps keep it just below a 5.	4 / 5
	Total	17 / 20 Passed

Description

92%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.

The description is specific, complete, and well-triggered, clearly stating what the skill does and when to use it with natural user phrases. It could add a few synonyms or file-extension cues to push trigger coverage to fully comprehensive.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — run Vale, identify style errors, fix error-level issues, and create individual PRs per file — giving comprehensive coverage of what the skill does.	5 / 5
Completeness	Explicitly answers both 'what' (lint, fix errors, create per-file PRs) and 'when' via concrete trigger phrases in an explicit 'Use this skill when...' clause.	5 / 5
Trigger Term Quality	Quotes natural user phrases ('run vale', 'fix vale errors', 'lint docs with vale') but omits common synonyms and variants like 'fix the lint job' or '.vale.ini', landing just below comprehensive.	4 / 5
Distinctiveness Conflict Risk	A clear niche (Vale linter on CircleCI docs) with distinctive triggers, minimizing overlap with other skills.	5 / 5
	Total	19 / 20 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: circleci/circleci-docs
Path: skills/vale-linter/SKILL.md
Commit: ae66960

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