One prompt takes a repository from no Vale to a reviewed baseline, and twelve more skills cover the rest: a written style guide turned into tested rules, a guide written from the config, the backlog, CI, commit messages, and a hook that holds the agent to the result.
Last week’s post ended on a claim: the hard part of a linter was configuring it, and that is the part a model has made cheap. This post is the walkthrough. It starts with one prompt, in a repository with docs and no Vale, that comes back as a pull request the team can review. Then it covers the rest of what the agent can do: enforce a written style guide, write one, tune a choice, work down a backlog, and keep itself to the rules it set up.
The example is Vale’s own documentation, vale-cli/docs: 41 Markdown pages and 16 MDX pages under website/. Everything quoted below is from that run.
Any other agent that can run a shell can follow the same instructions without the plugin:
Copy
Clone https://github.com/vale-cli/agent-tools into a temp directory, thenfollow skills/onboard/SKILL.md to set up Vale in this repository.
If Vale isn’t installed, the agent installs it: through Homebrew, pacman, or snap where one is available, otherwise the release binary, checksum-verified. On Windows a PowerShell installer does the same with winget, Scoop, or Chocolatey.
The usual way to set up a linter is a questionnaire. Which style guide? Which directory? Should CI fail? Those are hard to answer about a tool you haven’t seen run on your own files, so the skill asks none of them. It reads the repository instead.
In a temp directory · nothing in the repository changes
1 Look
Where the prose is, what CI already lints, word lists to carry over
2 Preview
Each package against the docs, with a real alert per blocking rule
3 Draft
A vocabulary, a decision per blocking rule, the style choices
4 Propose
One message, with the counts before and after
one yes
In the repository, on a branch
5 Apply
Config, vocabulary, overrides with reasons, the CI change
6 Verify
The preview again, against the real config, line for line
7 Pull request
One commit on a branch; the proposal is the description
The seven steps of the skill. Everything above the line happens in a temp directory; the repository is touched only after the proposal is accepted.
A survey script reports where the prose is, whether a CI job already lints a path, what other tools hold decisions worth carrying over, and whether the docs are translated. A word list kept for another spell checker becomes the start of the vocabulary. A workflow that already runs Vale gets updated; a second one isn’t added.
Then it tries the candidate packages against the docs, in a temp directory, with a throwaway config:
Microsoft427 alerts
54 errors106 warnings267 suggestions
Google598 alerts
68 errors223 warnings307 suggestions
errors
warnings
suggestions
Output of preview.sh -p Microsoft -p Google website: both packages on the same 41 Markdown and 16 MDX files, on one scale.
Microsoft is quieter here, so it becomes the default. The same script then prints that package in full: the busiest rules, and for every error-level rule one real alert with its file and line. That is the raw material for every decision that follows, and it takes seconds. Nothing in the repository has changed.
Fifty-four errors is not a baseline. A job that blocks on them would be red on its first run, and a job that is red on its first run teaches a team to ignore it. So the agent drafts the rest, still in temp files: a vocabulary for the names spell check doesn’t know, a decision for each error-level rule, and the style choices the docs already make. It previews again with all of that applied:
Blocking errors
54→ 5
before a file is written
Errors · block a merge54 → 5
Warnings · raised in review106 → 73
Suggestions · advice267 → 275
first run
with the baseline
Microsoft as shipped against Microsoft with the drafted baseline. Suggestions rise by eight because the eight contraction alerts moved down from errors to advice.
Then it shows one message. This is what it wrote, sixty seconds after the prompt:
/vale:onboard
Vale baseline for website/ (41 .md, 16 .mdx) — nothing written yet
total errors warnings suggestions
First run 427 54 106 267
With baseline 353 5 73 275
What it found, in your files
"VSCode" in creating-plugin.md:16 — the product is "VS Code" (4 uses)
"Intellij" in intellij.md:10 — the product is "IntelliJ"
"e.g.," in core.md:19 → "for example"
Package: Microsoft (Google: 598 alerts, 68 errors — say so to switch)
trigger gains pull_request, `debug: true` and the explicit
GITHUB_TOKEN go. `files: website` stays.
Still errors: 5 — "VSCode" (4) and "Intellij" (1), the spellings above. Real
findings; I'd leave them for a follow-up fix.
Not included — say the word for any of these
Blocking CI 5 errors would fail it today; fix those first
One-click fixes suggested changes on pull requests (not from forks)
Code comments 5 .jsx, 3 .js, 1 .tsx, 1 .py files
One spelling 79 American, 1 British ("centre") — enforce American
Commit messages closest to the "seven rules": 1 of your last 2 pass
A written guide generated from this config, for contributors
In your editor alerts as you type
The reasons in the config are what I observed, for you to replace with yours.
Apply this as a pull request? Or tell me what to change.
The proposal, as the agent wrote it. Nothing has been written to the repository at this point.
Three things about it are deliberate.
It leads with findings. VSCode on line 16 of a named file, in docs that elsewhere write “VS Code,” is a mistake anyone on the team would agree is one. A count of 427 convinces nobody; a typo in a page they wrote does.
Every choice comes with its evidence. The docs say “we” 52 times, so the rule against “we” is off, and the line says why. Contractions were blocking with 8 hits; now they are advice. Each default is read from what the docs already do, and each is one line to change: “use Google” or “keep the We rule” re-runs the preview with that line swapped and nothing else re-asked.
The five errors that remain are left as errors. The agent could have reached zero by accepting VSCode into the vocabulary, and the skill forbids that in so many words: the count that matters is the one nobody had to hide. So CI starts advisory, and “Blocking CI” sits in the list of things not included, with the reason.
.vale.ini, with the package, the path, and the vocabulary
the accepted terms, in accept.txt
each override, with its reason as a comment above it
a small house style for the preferred terms, with test cases that vale test runs
the CI change, generated by a script, not written from memory
The reasons are in the config because an unexplained NO looks the same as someone silencing a rule to get a build through. Two of the choices above, as they land:
ini
Copy
# 52 uses; the docs speak as "we" throughout.Microsoft.We = NO# 9 hits, right rule. Advisory until they're fixed.Microsoft.Quotes = warning
Then the agent checks its own work. The preview script runs once more, this time against the real config, and its report has to match the proposal’s line for line. If it doesn’t, a glob or an override isn’t matching, and the agent finds out which before it reports anything.
The result is one commit on a branch and a pull request whose description is the proposal. A baseline is a set of editorial decisions, and the person at the keyboard is rarely the only one they affect. The rest of the team approves the same table, the same findings, and the same reasons. The agent doesn’t merge it, and it doesn’t touch the prose: a setup pull request that also rewrites forty pages won’t get reviewed.
Onboarding is one of thirteen skills. The rest of this post is the other twelve, and each can be asked for in plain words:
Onboarding starts from a package, because a package is what a repository with no opinions yet can adopt. Most teams have opinions. They are in a document called the style guide, and the usual fate of that document is that nobody checks anything against it.
/vale:from-guide reads the guide and sorts every statement in it into one of four piles:
Already covered. “Use sentence case” is a package rule. It gets a level, not a new rule.
A rule. “Write ‘sign in,’ not ‘log in’” becomes one, with tests.
Vocabulary. “Our product is Zentrix, capital Z” goes in accept.txt.
Not checkable. “Be warm” and “write for a busy reader” are listed in the report as needing a person.
The fourth pile is the important one. A rule that pretends to check tone fires on the wrong sentences, and then the team switches the whole style off. So the agent proposes the sort as a table, with counts at the top, before it writes anything.
Use "sign in" for the action. Don't use "log in."A ruleAcme.SignIn·3 tests
Don't tell the reader a task is trivial.A ruleAcme.Filler·3 tests
Write "email," never "e-mail."A ruleAcme.Email·2 tests
Keep sentences to 30 words or fewer.A ruleAcme.SentenceLength·2 tests
Use sentence case.Already covereda package rule's level
Don't end a heading with a period or a colon.A ruleAcme.HeadingPunctuation·3 tests
Write for a busy reader. Be warm, and never condescending.Needs a personlisted as not enforced
The skill's worked example: a short guide, sorted. Seven statements become five rules with thirteen tests, one level on a package rule, and one line in the report.
Each rule then links to the section it came from, and its tests are the guide’s own examples. A “don’t” has to be flagged and a “do” has to pass. This one is from the skill’s worked example, a short guide that turns into five rules and thirteen tests:
yaml
Copy
# Guide: Words > Sign inextends: substitutionmessage: "Use '%s' instead of '%s'."link: style-guide.md#sign-inlevel: warningignorecase: trueswap: 'log in|log on': sign in 'login': sign-intests: - name: the guide's "don't" example is flagged input: Log in to your account. contains: "Use 'sign in' instead of 'Log in'." - name: the guide's "do" example passes input: Sign in to your account. want: '' - name: the noun form is flagged too input: Open the login page. contains: "'sign-in'"
vale test --coverage runs the cases and fails any rule that no case exercises, since a rule that matches nothing passes every negative test. Then the agent counts each rule against the real docs and reads ten hits of anything busy. The tests show the rule does what was meant; the corpus shows whether what was meant was right. Nothing new starts at error.
/vale:write-guide goes the other way. A team that started from a package has a house style too, and it lives in .vale.ini and YAML that most writers never open. The skill writes the page a new contributor can read: what blocks a merge, the style choices and the reason the config gives for each, the words the project uses. The facts come from a script that lists every rule at the level it actually runs at, and the table it produces sits between markers so it can be regenerated without touching the prose. It writes Markdown, MDX, AsciiDoc, reStructuredText, Org, or HTML. A choice with no reason in the config is reported as a gap, not given an invented one.
Three skills cover the changes a team makes after the baseline, each sized to the request.
/vale:tune takes a preference in plain words. “Use title case headings,” “allow contractions,” “it should be VS Code.” It maps the sentence to the rule, counts what the change would flag before writing it, and puts the line in the config with its reason. The count is a check on the choice itself: on one docs set, sentence case flagged 10 headings and title case 75, so the corpus had already decided. For the choices no package covers, such as title case, no contractions, preferred terms, and one regional spelling, it ships templates with their tests already written.
/vale:rule writes one rule for a house convention. It asks for a sentence that breaks the convention and one that must not, because the second is the one that finds false positives. Both become test cases. The rule runs alone on the corpus before it is enabled, and the report says how many alerts it raised and how many of the ones read were wrong.
/vale:ignore is for the opposite problem, a rule that is right in general and wrong about text that isn’t prose: a shortcode, a template variable, a generated block, one quotation. It picks the narrowest tool that works, a path, a TokenIgnores pattern, a BlockIgnores pattern, or a comment naming one rule around one passage. Then it checks that the alert count fell by exactly the number it targeted. A pattern that removed more is ignoring prose.
A first run on a large corpus is thousands of alerts. Three skills work it down.
/vale:triage turns the run into a decision per rule: fix, keep, downgrade, or switch off, each written into .vale.ini with its reason. /vale:fix clears error-level alerts a file at a time, applying the replacement each rule defines, one pull request per file. It leaves warnings and suggestions for a person. /vale:vocab handles spelling, which is usually the largest source of first-run errors and almost entirely names. It imports a word list kept for another spell checker, says whether the docs lean American or British, and installs dictionaries for other languages.
/vale:setup is the first step of onboarding on its own, for a team that wants a config and an honest first run and will make the decisions itself. It also covers two things the baseline leaves out: translated docs, and the comments in source code.
A config that only runs when someone remembers to type vale isn’t adopted. /vale:ci looks at what the repository already has and generates the GitHub Actions workflow or the pre-commit entry from a script. It asks three things: what a pull request check looks at (the lines it adds, the files it touches, or everything), what it reports, and when it fails. The default is advisory and new lines only, so the backlog lands on nobody.
/vale:commits does the same for the log, with the Commits package. It doesn’t ask which convention you want. It scores the history against each one first. This is its read of the agent-tools repository’s own last twenty commits:
SevenRules
17 of 20 pass
Conventional
1 of 20 pass
Go
1 of 20 pass
Gitmoji0 of 20 pass
Kernel0 of 20 pass
Jira0 of 20 pass
Output of history.sh -n 20 on the agent-tools repository, as commits that pass. All twenty pass the core every convention shares. The script's verdict: closest is SevenRules, and enforcing it confirms what the team does.
Then it sets up the convention the history already follows, with the hook and the CI check.
The plugin installs a hook, and it is the piece that keeps the baseline from eroding. Each time the agent writes or edits a file Vale lints, the hook lints that one file and hands back the alerts in the same turn. That includes source files, when the config has a section for them: a typo in a doc comment is caught the same way. A second hook does this for commit messages, after the agent commits, when the config has a commit section.
By default only errors reach the agent. Warnings and suggestions are advisory by the project’s own choice, and reporting them on every edit is how people end up turning a linter off. A setting raises that to warnings or to everything, for a style that is advisory on purpose.
The agent that set the rules up is held to them from then on, with the same message at the same line a person would get.
The most common reason Vale “stops working” is a fresh clone where the styles were never synced. /vale:doctor checks the setup end to end and gives the command that fixes each broken thing:
/vale:doctor
ok vale 3.27.0 at /usr/local/bin/vale
ok configuration loads: .vale.ini
FAIL styles named in the configuration are not on disk: Microsoft
→ vale sync
ok vocabulary Docs: 12 terms accepted
ok the vocabulary is tracked by git
FAIL vale could not lint README.md: .vale.ini:8:E201:Style 'Microsoft' isn't on the StylesPath
ok a POSIX shell is available for the edit hook
ok the edit hook reports 'error' and above; it stays silent on a file with none
2 thing(s) to fix, marked FAIL above.
The doctor report on a fresh clone. Both failures have one cause, and the fix is printed under the first.
Three more plugins ship in the same marketplace, all marked experimental. vale-onboard draws the proposal as a pane beside the chat, with a button per package and per rule, and every press re-runs the preview. vale-tools gives the agent lint and test as tools it calls without a shell, so it can check a draft before writing it. vale-lsp connects Vale’s language server, so alerts arrive as diagnostics; use it or the edit hook, not both.
None of this is tied to one agent. skills/ is a plain directory of instructions and POSIX shell scripts, so most clients read it as it is. For a setup with no skill support, AGENTS.md covers the same ground as prose.
That is the split from last week, in practice. The model spends its attention on judgment: which package, which words are names, which statements in a guide a rule can check and which need a person. What it leaves behind is a config, a directory of tested rules, and a pull request. From there the checking costs nothing.
The onboarding run is /vale:onboard on a clone of vale-cli/docs with Vale 3.27.0. The proposal and the doctor report are reproduced as the agent and the script wrote them, with one long line cut short, and the charts are drawn from the preview and history scripts’ output; the agent-tools README has each as an image. Every figure’s numbers are in onboard.ts. The sign-in rule is SignIn.yml from the from-guide example.