agentleFS
vale-clivale-cli/agent-tools/skills/fix/SKILL.md

fix

Skill8 starsChanged 3 months agoMITView on GitHub

Run Vale, fix error-level alerts, and open a pull request per file. Use when the user says "run vale", "fix vale errors", "lint the docs", "fix the linter", or "make vale pass". Fixes errors only; leaves warnings and suggestions for a person.

90 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use genie-hacks, workfly and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • automagik-devSkill

    genie-hacks

    Browse, search, and contribute community hacks — real-world patterns for provider switching, teams, skills, hooks, cost optimization, and more.

    Also in 3 projects that use this

  • automagik-devSkill

    workfly

    Discover a procedure and build its saved workflow — dynamic discovery, drafted script, adversarial verification, landed in the catalog.

    Also in 3 projects that use this

  • bradtraversySkill

    feature

    Manage current feature workflow - start, review, explain or complete

    Also in 10 projects that use this

  • GoogleSkill

    pr-creator

    Also in 4 projects that use this

  • chendongqiSkill

    frontend-code-review

    Trigger when the user requests a review of frontend files (e.g., `.tsx`, `.ts`, `.js`). Support both pending-change reviews and focused file reviews while applying the checklist rules.

    Also in 4 projects that use this

  • vbrevikSkill

    work

    Use when the user says 'plan', 'todo', 'copy plan', 'append plan', 'resume plan', 'priorities', or 'what's next'.

    Also in 5 projects that use this

  • +4 more from automagik-dev

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 83 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not trigger on prose edits alone.

    line 12
  2. Distinctive:

    Check these before doing any work, and stop with a plain message if one fails:

    line 18
  3. Very specific:

    Only error sets a non-zero exit code, so this is also what makes a lint job pass.

    line 37
  4. Distinctive:

    If nothing is left, say so and stop.

    line 56

“Common” is measured: kept by at least 6 in 10 of the 83 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Fix Vale alerts

When to use this

The user asks to run Vale, fix its output, or make a lint job pass.

Do not trigger on prose edits alone. Editing a Markdown file is not a request to lint the repository, and an unasked-for wave of style changes buried in someone else's pull request is worse than the alerts.

Prerequisites

Check these before doing any work, and stop with a plain message if one fails:

  1. vale --version succeeds. If not, use the setup skill.
  2. A config exists — vale ls-config resolves without error.
  3. The working tree is clean, or the user has said it is fine to branch from what is there.
  4. You know which files to process. Ask if the user did not say.

Scope

Fix error level only, unless asked otherwise. Vale's three levels are a decision the project already made:

levelmeaningthis skill
errorthe project decided this must not shipfix
warningworth a look in reviewleave, report the count
suggestionadvisoryleave, report the count

Only error sets a non-zero exit code, so this is also what makes a lint job pass. Say at the start which level you are working at.

Workflow

1. Get the alerts as data.

vale --output=JSON <path> > /tmp/vale.json

The default CLI output is aligned for reading and is not stable to parse.

2. Keep only the errors.

jq 'map_values(map(select(.Severity == "error"))) | with_entries(select(.value | length > 0))' /tmp/vale.json

If nothing is left, say so and stop. Do not go looking for warnings to fix instead.

3. Take each file on its own branch.

git switch -c vale-fix-<file-stem>-<short-hash>

4. Apply the fix the rule intends. Each alert carries Check, Message, Line, Span, and often Action.Name with Action.Params — the replacement the rule itself defines. Prefer that over inventing wording from the message.

Preserve the markup exactly: AsciiDoc attributes, MDX expressions, reference links, code fences, existing line breaks. Never reflow a paragraph to fix one word.

5. Verify.

vale --output=JSON <file>

The error count should be zero and nothing new should appear. If an alert cannot be fixed without changing meaning, leave it and say so in the pull request.

6. Commit and open one pull request per file, following the repository's own commit conventions. A hundred prose edits in one branch cannot be reviewed; ten small ones can. In the body, list each fix as line — rule — what changed, and note anything left unfixed and why.

7. Report.

Vale fix summary
================
Files processed:      3
Pull requests:        2
Clean already:        1
Errors fixed:         8
Left for a human:     2 (meaning would change)
Untouched by design:  14 warnings, 51 suggestions

Fixing guidance

Most rules name their own replacement; these are the shapes that need judgment:

  • Wordiness — "in order to" → "to", "utilize" → "use". Safe.
  • Passive voice — "the button is clicked by the user" → "click the button". Check the actor is actually known before rewriting.
  • Heading punctuation, link text, capitalization — mechanical, low risk.
  • Gendered terms — "he/she" → "they". Safe, and check surrounding agreement.
  • Contractions — whichever direction the project's style goes; do not switch a document's register halfway through.
  • Spelling — a flagged product name is not a misspelling. Use the vocab skill instead of editing the word.

Do not

  • Do not silence a rule to make a run pass. Turning off Vale.Spelling because it flags a product name is the wrong fix; so is disabling a rule the team chose. Changing the config is their decision, not yours.
  • Do not edit anything under StylesPath. vale sync overwrites it.
  • Do not change what a sentence means to satisfy a style rule. Technical accuracy wins; report the alert instead.
  • Do not fix warnings or suggestions unless asked. They are advisory by the project's own choice.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.