AI & agents
Vale for AI and agents
Hold what a model writes, and what you write for one, to a standard.
A writing skill in a prompt is a list of constraints the model is asked to remember. As Vale rules, they are checked on every draft instead. Voices covers hedging, puffery, and throat clearing, with voices like Direct and Simple on top; AiTells flags the patterns of AI-written prose; and Prompts lints the instruction files themselves: AGENTS.md, CLAUDE.md, and SKILL.md.
Start with this config
A voice for what the model writes, and the Prompts rules for the files that instruct it.
.vale.ini
StylesPath = styles
Packages = Voices, Prompts
[*.md]
BasedOnStyles = Voices, Direct
[{AGENTS,CLAUDE,SKILL}.md]
BasedOnStyles = Prompts Then download the packages it names and run Vale over the project:
$ vale sync
$ vale . Packages
Published styles to start from. A package in the Explorer installs by name with Packages and vale sync, one published elsewhere by its release URL, and every rule in either can be turned off or changed in your own config.
Voices
Writing voices as Vale rules: a shared core against hedging, puffery, weasel words, and throat clearing, and voices such as Direct, Simple, and Human that set how the prose should sound.
34 rules 14.4K downloads
AiTells
Flags the tells of AI-written prose: em-dash habits, epigrams, abstract-noun triads, clichés, and 13 more benchmarked rules.
17 rules 18.1K downloads
Prompts
Lints instruction files such as AGENTS.md, CLAUDE.md, and SKILL.md: advice in place of commands, vague verbs, contradictions, too much emphasis, and files too long to read on every turn.
13 rules 47 downloads
Readability
Readability scores: Automated Readability Index, Coleman-Liau, Flesch-Kincaid, Flesch reading ease, Gunning fog, LIX, and SMOG, with a rule that names the polysyllables behind them.
8 rules 288K downloads
Where it runs
Where agents write: Promptless runs Vale on every draft its agent makes, the language server reports to any LSP client, and VS Code covers Cursor and Windsurf. CI holds what an agent opens to the same rules.
- Promptless Lints every draft it writes
- Language server Any LSP-capable editor
- VS Code VS Code, Cursor, Windsurf
- GitHub Actions vale-cli/vale-action
- pre-commit Local hooks
With an agent
All agent toolsThe agent tools install as a Claude Code plugin: skills for setting up and tuning Vale, and hooks that lint each file the assistant writes. Type both lines in Claude Code, then ask for what you need.
/plugin marketplace add vale-cli/agent-tools
/plugin install vale@agent-tools - “set up vale end to end” /vale:onboard Try the style packages against your docs in a temp directory, draft a vocabulary, a decision per noisy rule, and the CI job, and show one proposal with before and after counts.
- “flag this phrase” /vale:rule Write one rule for a house convention, with test cases beside it, and prove it with vale test and a run on the real corpus.
- “make vale pass” /vale:fix Fix alerts a file at a time, applying the replacement each rule defines, one pull request per file.
- “why is the hook silent” /vale:doctor Check a setup end to end: the binary, the configuration, the synced styles, the vocabulary, and a real run on a real file.
Who runs it
Teams who use Vale on what models write, or on the docs for the agents they build: as a check an agent runs, a skill it follows, or a style that flags AI tells.
- NVIDIA All NeMo Agent Toolkit documentation is checked with Vale before it merges.
- CircleCI Writes Vale into the docs style guide its AI assistants follow, with a vale-linter skill that fixes error-level alerts and opens a pull request per file.
- Promptless Runs each customer's Vale config over the docs its agent drafts and fixes the findings before opening a suggestion. Also lints its docs in CI against a house style.
- Mastra Runs write-good and ai-tells over the docs for its TypeScript agent framework.
- Uniswap Lints the docs for its AI tools, skills, and agents with a Uniswap vocabulary.
- seedcord Keeps LLMisms out of its docs, guide, and code comments, and holds them to plain English that readers at any level can follow.
- Modelplane Lints its docs with Google's style and a package that flags AI tells.
- gqlgen Lints its Markdown with write-good, alex, proselint, Readability, Elastic's style, and a package that flags AI tells.
- Broad Institute Lints the POASTA aligner's docs and Rust comments with Vale's rules and an AI-tells style.
- pgEdge Lints Markdown docs, llms.txt files, and Go doc comments at error level with its own PgEdge style.
Formats
Where this kind of writing lives. Vale parses each one, so rules see the prose and skip the markup, the code, and the URLs.
Read more
On the blog
- Introducing Voices: AI writing skills as Vale rules The writing skill you would reach for, rewritten as Vale rules. Checked on every draft rather than remembered, and free until something breaks one.
- Setting up Vale with an agent 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.
- The model writes the rules. The rules check the docs. A pitch going around says a rule-based linter is the old way and an AI quality gate is the new one. Measured against five model reviews, a counting test, a forgetting test, and a million-word corpus, the model does the pattern work fine, at six hundred times the cost. The one real cost of a linter, configuring it, is the part AI has made cheap.
In the docs
Other kinds of writing
Technical
Docs, references, and the style guide your team already follows.
Read the guidePublic sector
Plain English for the public, held to a government style guide.
Read the guideResearch
Papers, notebooks, and the docs for the software research runs on.
Read the guideCreative
Fiction, essays, and the rules writers have argued over for a century.
Read the guideCode & data
The prose inside files that aren’t prose: comments, API descriptions, and the log.
Read the guide