add-a-lint-rule
Skill1 starsChanged 3 months agoMITView on GitHub
Turn a described failure into a checkable vat lint or vat brain check rule.
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- change-a-command-contractSkill
- cut-a-releaseSkill
- add-a-lint-ruleSkill
- change-a-command-contractSkill
- cut-a-releaseSkill
The file
We split this skill 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 37
Add the row to the reference table: docs/COMMANDS.md for a lint rule, docs/BRAIN.md for a brain rule.
- Distinctive: line 39
Write the test that fails without the rule.
- Distinctive: line 58
If the failure cannot be detected from what vat can read — the manifest, the working trees, the harness files, the records — it is not a …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill 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
Add a lint rule
When to use this
Somebody wants a convention enforced, or a failure has happened twice and should not happen a third time.
First, decide whether it is a rule at all
A rule that cannot be checked is not added. If the convention cannot become a
vat lint finding or a vat doctor finding, it does not belong in this tool —
say so and stop. Adding prose instead is how a tool that sells mechanical
enforcement ends up shipping advice.
Two more questions decide the shape:
- Severity.
erroris for a state that makes the workspace wrong;warnis for one that makes it worse. Warnings alone do not change an exit code, and every command that reports findings agrees on that. - Fixable. A rule is
Fixableonly if repair is unambiguous and touches nothing a human wrote. Diagnosis and repair stay separate commands.
Steps
- Implement the check. Workspace rules live in
internal/lint; knowledge-layer rules live ininternal/brain. Collect the finding, never return early — these commands run in a loop while somebody cleans a repository, and one finding per run is unusable. - Register the name in the list its package keeps:
lint.RuleNames()forvat lint,brain.RuleNames()forvat brain check. An unregistered rule cannot be selected with--only, so it is a rule nobody can ask for. - Add the row to the reference table:
docs/COMMANDS.mdfor a lint rule,docs/BRAIN.mdfor a brain rule. - Write the test that fails without the rule.
make check.
What catches you if you skip a step
These already exist and will go red on their own:
TestTheReferenceListsExactlyTheLintRulesThatExist— the lint table matcheslint.RuleNames()exactly, in both directions.TestTheBrainReferenceListsExactlyTheRulesThatExist— the same fordocs/BRAIN.md.TestTheReadmeQuotesTheRuleCountItActuallyHas— the README states a number of rules, and a new rule changes it.
They are the reason step 2 and step 3 are not optional. Do not treat a green suite reached by editing a table as proof; the rule still has to fire.
When it must stop
If the failure cannot be detected from what vat can read — the manifest, the working trees, the harness files, the records — it is not a rule. Report that conclusion rather than approximating it with a heuristic that will produce false findings in somebody else's workspace.
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.

