add-mlinter-rule
Skill12 starsChanged 3 months agoApache-2.0View on GitHub
Add a new TRF rule to the mlinter. Checks for duplicates, creates the rule module and TOML entry, runs against all models, and handles violations (fix or allowlist).
In this repository3 other files it gives its agents.
- .ai/AGENTS.mdAGENTS.md
- releaseSkill
- remove-mlinter-ruleSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
27 rules. About 0 are common, 9 are distinctive, and 18 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
18
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
Use the module-level RULE_ID constant instead of hardcoding the rule ID string.
- Very specific: line 21
Check for duplicate coverage in mlinter/rules.toml.
- Distinctive: line 22
Read the full TOML file and review existing rule descriptions and explanations.
- Distinctive: line 23
If an existing rule already covers the same concern, stop and ask whether to proceed, extend the existing rule, or abort.
- Very specific: line 29
Add the TOML entry to mlinter/rules.toml.
- Distinctive: line 35
Follow the exact formatting style of existing entries.
- Very specific: line 37
Create the rule module at mlinter/trfXXX.py.
- Very specific: line 38
Start with the Apache 2.0 license header copied from an existing trf*.py file.
- Very specific: line 39
Add a module docstring: """TRFXXX: <short description>."""
- Very specific: line 40
Import ast, Path, and any needed helpers from ._helpers.
- Distinctive: line 45
Run the rule against all models.
- Distinctive: line 49
If the run errors, fix the rule code and re-run.
- Very specific: line 53
Ask whether to fix the models or add them to allowlist_models in mlinter/rules.toml.
- Distinctive: line 54
If fixing, apply the fixes and re-run the rule to confirm zero violations.
- Very specific: line 55
If allowlisting, extract the model directory names from the violation file paths and add them to allowlist_models.
- Very specific: line 57
Add tests in tests/test_trfXXX.py.
- Distinctive: line 58
Add at least one positive test and one negative test.
- Very specific: line 59
Follow the existing pattern: create source strings, call mlinter.analyze_file(), and assert on violations.
- Very specific: line 60
If the tests use the standard _run(rule, source, file_name=...) helper, inherit from RuleTestCase from tests/rule_test_utils.py.
- Distinctive: line 63
If the rule maps a modeling class to a specific config class, add a regression where another config class in the same file would otherwise …
- Distinctive: line 64
Run the focused tests:
- Very specific: line 70
No rule page to write: the docs site generates one per rule from rules.toml and docs/rules/ is git-ignored, so never commit one.
- Very specific: line 72
If the rule applies to file types not already documented, update the list in both README.md and docs/index.md.
- Very specific: line 88
Only fall back to a generic configuration_*.py pick when there is no exact suffix match.
- Very specific: line 94
Prefer config_class from the model class, following local modeling inheritance if a parent *PreTrainedModel declares it.
- Very specific: line 95
If there is no explicit config_class, infer the best match from class names, usually by longest shared prefix.
- Very specific: line 110
Always add a regression test with a modular_*.py class inheriting from an imported base.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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 Mlinter Rule
Input
<description>: Natural-language description of what the rule should detect.- Optional: specific AST pattern or a before/after diff showing the pattern.
Constraints
- Rules MUST use static analysis only with Python's
astmodule. NEVER import runtime libraries liketorchortensorflow. - Rules MUST follow the
check(tree, file_path, source_lines) -> list[Violation]interface. - Use the module-level
RULE_IDconstant instead of hardcoding the rule ID string.
Workflow
- Check for duplicate coverage in
mlinter/rules.toml.- Read the full TOML file and review existing rule descriptions and explanations.
- If an existing rule already covers the same concern, stop and ask whether to proceed, extend the existing rule, or abort.
- Determine the next rule number.
- List all
mlinter/trf*.pyfiles and find the highest number. - The new rule gets that number + 1, zero-padded to three digits.
- List all
- Add the TOML entry to
mlinter/rules.toml.- Append a new
[rules.TRFXXX]section at the end of the file with:descriptiondefault_enabled = trueallowlist_models = [][rules.TRFXXX.explanation]withwhat_it_does,why_bad, anddiff
- Follow the exact formatting style of existing entries.
- Append a new
- Create the rule module at
mlinter/trfXXX.py.- Start with the Apache 2.0 license header copied from an existing
trf*.pyfile. - Add a module docstring:
"""TRFXXX: <short description>.""" - Import
ast,Path, and any needed helpers from._helpers. - Define
RULE_ID = "" # Set by discovery. - Implement
def check(tree: ast.Module, file_path: Path, source_lines: list[str]) -> list[Violation]:. - Refer to existing rules in
mlinter/trf*.pyfor patterns and helpers.
- Start with the Apache 2.0 license header copied from an existing
- Run the rule against all models.
python -m mlinter --enable-rules TRFXXX- If the run errors, fix the rule code and re-run.
- Handle violations.
- Present the list of violations to the user.
- Ask whether to fix the models or add them to
allowlist_modelsinmlinter/rules.toml. - If fixing, apply the fixes and re-run the rule to confirm zero violations.
- If allowlisting, extract the model directory names from the violation file paths and add them to
allowlist_models.
- Add tests in
tests/test_trfXXX.py.- Add at least one positive test and one negative test.
- Follow the existing pattern: create source strings, call
mlinter.analyze_file(), and assert on violations. - If the tests use the standard
_run(rule, source, file_name=...)helper, inherit fromRuleTestCasefromtests/rule_test_utils.py. - For cross-file rules, use
tempfile.TemporaryDirectoryto create real file structures. - If the rule maps a modeling class to a specific config class, add a regression where another config class in the same file would otherwise cause a false positive or false negative.
- Run the focused tests:
pytest tests/test_trfXXX.py -x -v - Update documentation.
- No rule page to write: the docs site generates one per rule from
rules.tomlanddocs/rules/is git-ignored, so never commit one. This makesdescription/what_it_does/why_bad/diffpublished prose — write them for someone reading a failed CI job. Preview:make docs-rules. - Add an entry under the
## [Unreleased]section ofCHANGELOG.md(create that section above the latest released version if it does not yet exist) describing the new rule. Mention any incidental changes shipped with it (e.g. expandingMODELING_PATTERNSto cover new file types), since those affect every rule. - If the rule applies to file types not already documented, update the list in both
README.mdanddocs/index.md.
- No rule page to write: the docs site generates one per rule from
- Final validation.
make lint make test
Model architecture knowledge
The mlinter processes files one at a time via analyze_file(file_path, text, enabled_rules). When a rule needs cross-file information, the rule module must read the other file from disk. Watch for these patterns:
Multi-config directories
Some model directories contain multiple configuration files. Match by suffix first:
modeling_foo_text.py -> configuration_foo_text.py.
Only fall back to a generic configuration_*.py pick when there is no exact suffix match.
Multi-class configuration files
A single configuration_*.py file can define multiple config classes. If the rule is checking a property that belongs to one specific config class, do not accept the first matching class in the file. Resolve the modeling class's target config class first:
- Prefer
config_classfrom the model class, following local modeling inheritance if a parent*PreTrainedModeldeclares it. - If there is no explicit
config_class, infer the best match from class names, usually by longest shared prefix.
Then validate only that config class.
Inherited configs
Some config classes inherit from another model config rather than directly from PreTrainedConfig. If the base class is not PreTrainedConfig or PretrainedConfig and still ends with Config, assume the field may be inherited and skip the violation unless the rule specifically needs stricter handling.
Modular imported bases
modular_*.py files commonly define classes that inherit from another model's imported class, and
analyze_file only passes the AST for the file currently being linted. If a rule depends on inherited
methods or a full base chain, an imported base is unknown, not evidence that the expected behavior is
missing. Prefer resolving the generated modeling_*.py when the rule needs the flattened class, or
skip/report nothing when _base_chain_has_unresolved_import(...) says the local AST is inconclusive.
Always add a regression test with a modular_*.py class inheriting from an imported base.
tie_word_embeddings is not in PreTrainedConfig
The base PreTrainedConfig does not define tie_word_embeddings. When a rule needs it, the model config must declare it explicitly, either as a class attribute or through self.tie_word_embeddings = ... in initialization code.
Reference
- Rule modules:
mlinter/trf*.py - Rule config:
mlinter/rules.toml - Helpers:
mlinter/_helpers.py - Rule tests:
tests/test_trfXXX.py - Shared rule-test helpers:
tests/rule_test_utils.py - General linter tests:
tests/test_mlinter.py - README (repo front door + PyPI description):
README.md - Docs site source:
docs/— hand-written pages only;docs/rules/is generated and git-ignored - Rule page generator:
scripts/build_docs.py
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.

