agentleFS
takealook97takealook97/vat/.agents/skills/add-a-lint-rule/SKILL.md

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.

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
  1. Very specific:

    Add the row to the reference table: docs/COMMANDS.md for a lint rule, docs/BRAIN.md for a brain rule.

    line 37
  2. Distinctive:

    Write the test that fails without the rule.

    line 39
  3. Distinctive:

    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 …

    line 58

≈ “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.

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

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. error is for a state that makes the workspace wrong; warn is 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 Fixable only if repair is unambiguous and touches nothing a human wrote. Diagnosis and repair stay separate commands.

Steps

  1. Implement the check. Workspace rules live in internal/lint; knowledge-layer rules live in internal/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.
  2. Register the name in the list its package keeps: lint.RuleNames() for vat lint, brain.RuleNames() for vat brain check. An unregistered rule cannot be selected with --only, so it is a rule nobody can ask for.
  3. Add the row to the reference table: docs/COMMANDS.md for a lint rule, docs/BRAIN.md for a brain rule.
  4. Write the test that fails without the rule.
  5. make check.

What catches you if you skip a step

These already exist and will go red on their own:

  • TestTheReferenceListsExactlyTheLintRulesThatExist — the lint table matches lint.RuleNames() exactly, in both directions.
  • TestTheBrainReferenceListsExactlyTheRulesThatExist — the same for docs/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.

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.