vale-ai-tells
CLAUDE.md118 starsChanged 37 days agoMITView on GitHub
Refer to @AGENTS.md for commit conventions and the prose-lint output contract. What follows is specific to this repository. vale-ai-tells provides a Vale package for detecting linguistic patterns commonly associated with AI-generated prose. It provides YAML rule files that flag vocabulary fingerprints, structural patterns, and rhetorical tells. The README tracks the current rule count. First-time setup: A clone already contains the vendored payload, because it is committed. Delete it and every mise command that reads tasks fails while loading the configuration,…
In this repository32 other files it gives its agents.
- AGENTS.mdAGENTS.md
- analyze-sessionSkill
- codex-analyze-sessionSkill
- codex-commitSkill
- codex-fix-proseSkill
- codex-fix-prSkill
- codex-merge-prSkill
- codex-prSkill
- codex-rebaseSkill
- codex-resolve-rebase-conflictsSkill
- codex-review-commit-messageSkill
- codex-review-pr-descriptionSkill
- codex-review-prose-fixSkill
- codex-review-squash-messageSkill
- codex-watch-prSkill
- codex-write-pr-descriptionSkill
- codex-write-prose-fixSkill
- commitSkill
- fix-proseSkill
- fix-prSkill
- merge-prSkill
- prSkill
- rebaseSkill
- releaseSkill
- resolve-rebase-conflictsSkill
- review-commit-messageSkill
- review-pr-descriptionSkill
- review-prose-fixSkill
- review-squash-messageSkill
- watch-prSkill
- write-pr-descriptionSkill
- write-prose-fixSkill
The file
We split this CLAUDE.md into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
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
- Very specific: line 121
Add or update the rule's cases in tests/<style>/<Rule>.test.yml, one per token family and one per guard, and run mise run test
- Distinctive: line 122
Ensure rules don't have excessive false positives
- Distinctive: line 123
Update README.md if adding/removing rules
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Claude Code instructions
Refer to @AGENTS.md for commit conventions and the prose-lint output contract. What follows is specific to this repository.
Project overview
vale-ai-tells provides a Vale package for detecting linguistic patterns commonly associated with AI-generated prose. It provides YAML rule files that flag vocabulary fingerprints, structural patterns, and rhetorical tells. The README tracks the current rule count.
Repository structure
vale-ai-tells/
├── styles/
│ ├── ai-tells/ # Core prose rules (*.yml)
│ ├── ai-tells-commits/ # Commit-message rules (*.yml)
│ ├── ai-tells-experimental/ # Opt-in structural and metric rules (*.yml)
│ └── config/ # Tengo scripts, the agent template, vocabularies
├── tests/ # Per-rule vale test cases (<style>/<Rule>.test.yml)
├── .github/workflows/ # CI, security, release, and Renovate automation
├── .config/mise/conf.d/ # Vendored devtools tool pins (vendir owns this)
├── .devtools/tasks/ # Vendored devtools shared tasks (vendir owns this)
├── .pre-commit-config.yaml
├── .vale.ini # Repo dev config (enables all three styles)
├── mise.toml # Repo-specific pins and tasks; selects the shared ones
├── mise.lock # Resolved versions, URLs, and digests
├── vendir.yml # The devtools payload: source, tag, target directories
├── vendir.lock.yml # The commit each directory resolved to
├── README.md
├── AGENTS.md # Commit and prose-output contract for agents
├── EXPERIMENTAL.md # Experimental-rule reference
├── CHANGELOG.md
├── TODO.md
├── test-document.md # Positive fixtures (patterns should fire)
├── test-false-positives.md # Negative fixtures (should stay clean)
└── test-commit-messages.md # Commit-message fixturesDevelopment workflow
First-time setup:
mise run bootstrap # vendir sync, mise install, vale sync, prek installA clone already contains the vendored payload, because it is committed. Delete it and every mise command that reads tasks fails while loading the configuration, because the stamps in mise.toml extend templates only the payload defines. That is the enforcement, not a bug. mise install and vendir sync keep working through it, which is what recovers the tree.
Testing rules locally:
vale --config=.vale.ini test-document.md
mise run test-rules # the per-rule cases under tests/
mise run test # the rule cases, then the false-positive fixtures stay cleanCases for a rule go in tests/<style>/<Rule>.test.yml, with rule: ../../styles/<style>/<Rule>.yml isolating it. Assert with contains (the check name and the quoted match) and absent. Keep them out of styles/: vale before 3.24 loads every .yml there as a rule, and a test file breaks vale sync for consumers.
Measuring a candidate token:
mise run corpus-build # once per machine, into ~/.cache/vale-ai-tells/corpus
mise run corpus-grep 'rather than [a-z]+ing' # count a PCRE pattern per corpus, with sample paragraphsA token is counted against human technical prose written before the models before it is added to a rule, and the count goes in the rule comment with an example hit or two. The Go and Python standard library corpora are reference prose, and the PEPs, Go proposals, Go blog, Rust RFCs, and Pro Git are explanation and argument, so quote the argumentative ones for a clause-level construction. A count in the tens that is the construction itself stays and gets documented, while one in the hundreds is ordinary English and measures out. Confirm the settled count through Vale over the corpus files, since Vale uses a different regex engine than the grep task. The header of tools/corpus-build.sh lists the sources and pins.
Running the gates:
Gates from the vendored payload use a devtools: prefix. The rest belong to this repository.
mise run lint # every linter below, in one pass
mise run devtools:check-vendored # the vendored payload matches what git holds
mise run devtools:check-pins # every tbhb-dev/devtools pin site names one release
mise run devtools:lint-yaml # ryl
mise run devtools:lint-markdown # rumdl
mise run devtools:lint-config # biome on JSON
mise run devtools:lint-spelling # cspell
mise run lint-prose # Vale on the docs
mise run lint-messages # Vale on each rule's own message: field (dogfooding)
mise run devtools:lint-toml # tombi
mise run devtools:lint-mise # mise fmt --check
mise run lint-editorconfig
mise run devtools:lint-workflows # actionlint
mise run check-all # lint, test, and the full-history gitleaks scanPre-commit hooks:
mise run devtools:prek # run hooks on staged files
mise run devtools:prek-all # run hooks on all filesBuilding and releasing:
mise run build-package # write the three release zips locally
mise run release vX.Y.ZRule conventions
All rules use error level by default. Users can override this in their .vale.ini. Core rules use Vale's existence and sequence extensions, plus occurrence for the density rule and substitution for the house-compound swaps. The experimental style adds script (Tengo), metric, capitalization, and substitution rules. Each rule needs:
message: Clear explanation of why the rule flags the patternlevel: Alwayserrortokensorswap: The patterns to match- A comment recording what the tokens cost on the pre-LLM corpora and what was measured out, from the corpus tasks above
Messages must pass the ai-tells style themselves. Avoid em-dashes and anthropomorphic or cliché idioms. Give the good word rather than quoting the flagged one. Write each message as AI <label>: '%s'. <concrete action>. so agents can act on it. mise run lint-messages enforces this: tools/lint-messages.sh copies each message field into a scratch Markdown file and lints it as prose. It runs as part of mise run lint.
Tone
Appreciate the irony: an AI working on a tool that detects AI writing. Lean into it. Find the humor in flagging your own tendencies and catching yourself mid-cliché while helping humans spot the patterns you statistically tend to produce.
Quality standards
Before committing changes:
- Add or update the rule's cases in
tests/<style>/<Rule>.test.yml, one per token family and one per guard, and runmise run test - Ensure rules don't have excessive false positives
- Update README.md if adding/removing rules
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
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.

