Name: vale-linter
Rating: 91 (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

—

Does it follow best practices?

Impact

91%

1.33x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Quality

Content

77%

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 with a clear, validated workflow for linting, fixing, and PR-ing files. Its weaknesses are verbosity (repeated guidance and heavy boilerplate templates) and inlining of reference/template material that a leaner SKILL.md could offload to bundle files.

Suggestions

Tighten conciseness by stating the Vale severity-level handling once and trimming the fabricated summary-report example and verbose PR/commit message templates to essential structure only.

Move the "Common Vale Errors and How to Fix Them" catalog and the PR/commit message templates into reference files (e.g. references/error-fixes.md, references/pr-templates.md) and link to them, improving progressive disclosure and reducing SKILL.md length.

Consolidate the repeated "only fix error-level issues" reminders into a single prominent note so the guidance is not restated across multiple sections.

Dimension	Reasoning	Score
Conciseness	Mostly efficient but padded in places — Vale severity levels are explained twice, the "Only process error-level issues" guidance is restated, and the full PR-body/commit-message/summary templates with fabricated example URLs add length Claude largely does not need. It is tighter than a conceptual wall of text but not lean enough for the top anchor.	2 / 3
Actionability	Provides fully executable, copy-paste-ready guidance — `vale --output=JSON`, a `jq` filter for errors, `git checkout -b vale-fix-...`, and a complete `gh pr create` template — with concrete examples throughout.	3 / 3
Workflow Clarity	A clear 4-step sequence with an explicit validation feedback loop (re-run Vale on the fixed file; if errors remain, attempt additional fixes) covering the batch/destructive git and PR operations, matching the anchor for clear sequencing with checkpoints.	3 / 3
Progressive Disclosure	The skill is a single file with no bundle references, and content that could live separately (the Common Vale Errors catalog, PR/commit templates, summary template) is inlined into a ~245-line body. Sections are clearly organized, but the inline reference and template material keeps it below the well-split top anchor.	2 / 3
	Total	10 / 12 Passed

Description

100%

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, trigger-rich, and complete, clearly stating both capabilities and explicit use-conditions with natural user phrasing. It is a strong, low-conflict description that requires no changes.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "run the Vale prose linter", "identify and fix style errors", "create pull requests", "fixes error-level Vale issues", and "creates individual PRs per file" — matching the anchor for listing several specific concrete actions.	3 / 3
Completeness	Explicitly answers both what the skill does (run Vale, fix errors, create PRs) and when to use it via an explicit "Use this skill when..." trigger clause, matching the top anchor.	3 / 3
Trigger Term Quality	Quotes natural phrases a user would actually say — "run vale", "fix vale errors", "lint docs with vale" — giving good coverage of natural trigger terms rather than technical jargon.	3 / 3
Distinctiveness Conflict Risk	Occupies a clear niche (Vale prose linting on CircleCI docs) with distinctive triggers ("run vale", "fix vale errors"), making it unlikely to fire for the wrong skill.	3 / 3
	Total	12 / 12 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
Commit: 65ff472

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