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

vale-linter

Run the Vale prose linter on CircleCI documentation files to identify and fix style errors. Use this skill when the user explicitly asks to "run vale", "fix vale errors", "lint docs with vale", or mentions vale linting. Always clarifies scope and delivery method with the user before making changes — it does not assume per-file PRs.

1.87x

Quality

88%

Does it follow best practices?

Impact

77%

1.87x

Average score across 1 eval scenario

Securityby

Passed

No findings from the security scan

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 highly actionable, well-sequenced skill with executable commands and explicit validation loops for a batch-fix plus git-delivery workflow. The main improvements are trimming repeated notes and moving the Vale error catalog into a reference file.

Suggestions

State the "only error-level issues; warnings and suggestions are left for human review" rule once (e.g., in Step 2) and drop the repetitions in the Path B PR body and Notes section.

Move the "Common Vale Errors and How to Fix Them" catalog to references/vale-rules.md, keeping 2-3 of the most common rules inline with a pointer, to slim the SKILL.md body.

Trim the "Edge Cases and Error Handling" section where it restates the Prerequisites checks (Vale installed, .vale.ini exists) to a cross-reference.

Dimension	Reasoning	Score
Conciseness	The body is command-first and efficient, but "only error-level issues / leave warnings for humans" is repeated in Step 2, the Path B PR body, and Notes, and the Edge Cases section partially restates Prerequisites. These are minor instances of over-explanation that could be trimmed, matching the anchor 4 rather than the lean anchor 5.	4 / 5
Actionability	Fully executable guidance throughout: the jq-filtered Vale JSON command, git stage/commit/push heredocs, a complete gh pr create invocation with PR body, and a concrete summary-report template. Not 4 because the commands are copy-paste ready and cover the common cases per path.	5 / 5
Workflow Clarity	A clear five-step sequence gated by prerequisites, with an explicit validation feedback loop ("Re-run Vale on the fixed file to verify errors are resolved… If errors remain, attempt additional fixes") and per-path delivery checklists — essential for a batch-edit plus git-push skill. Not 4 because validation checkpoints are explicit, not merely implied.	5 / 5
Progressive Disclosure	Well-organized single file with clear section headers and no buried or nested references (no bundle files exist). It falls short of anchor 5 because the ~65-line "Common Vale Errors and How to Fix Them" catalog is detail that could be split into a one-level-deep reference file, but structure and navigation are good.	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: concrete actions, an explicit 'Use when…' clause with natural trigger phrases, and a clearly distinct niche. The only gaps are a few missing trigger synonyms that live in the body but not the description.

Dimension	Reasoning	Score
Specificity	Quotes concrete actions ("Run the Vale prose linter… to identify and fix style errors") and a behavioral constraint ("does not assume per-file PRs"), matching the anchor for several specific actions with minor gaps in coverage. It is not 5 because capabilities like severity filtering or delivery paths are not enumerated, and not 3 because it goes beyond 1-2 generic actions.	4 / 5
Completeness	Explicitly answers both questions: what ("Run the Vale prose linter on CircleCI documentation files to identify and fix style errors") and when ("Use this skill when the user explicitly asks to…" with concrete trigger phrases). This matches the top anchor exactly.	5 / 5
Trigger Term Quality	Includes natural trigger phrases users would actually say: "run vale", "fix vale errors", "lint docs with vale", "mentions vale linting". Good coverage, but common variations ("fix the lint job", "make the linter happy", "linter") appear only in the body, not the description, so it falls short of the comprehensive-synonyms anchor.	4 / 5
Distinctiveness Conflict Risk	"Vale prose linter" on "CircleCI documentation files" is a clear niche with tool-specific triggers, giving minimal overlap risk with other linting or docs skills.	5 / 5
	Total	18 / 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: 5c19307

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