agentleFS
Hugging FaceKnown publisherhuggingface/transformers-mlinter/.ai/skills/add-mlinter-rule/SKILL.md

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).

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

    Use the module-level RULE_ID constant instead of hardcoding the rule ID string.

    line 17
  2. Very specific:

    Check for duplicate coverage in mlinter/rules.toml.

    line 21
  3. Distinctive:

    Read the full TOML file and review existing rule descriptions and explanations.

    line 22
  4. Distinctive:

    If an existing rule already covers the same concern, stop and ask whether to proceed, extend the existing rule, or abort.

    line 23
  5. Very specific:

    Add the TOML entry to mlinter/rules.toml.

    line 29
  6. Distinctive:

    Follow the exact formatting style of existing entries.

    line 35
  7. Very specific:

    Create the rule module at mlinter/trfXXX.py.

    line 37
  8. Very specific:

    Start with the Apache 2.0 license header copied from an existing trf*.py file.

    line 38
  9. Very specific:

    Add a module docstring: """TRFXXX: <short description>."""

    line 39
  10. Very specific:

    Import ast, Path, and any needed helpers from ._helpers.

    line 40
  11. Distinctive:

    Run the rule against all models.

    line 45
  12. Distinctive:

    If the run errors, fix the rule code and re-run.

    line 49
  13. Very specific:

    Ask whether to fix the models or add them to allowlist_models in mlinter/rules.toml.

    line 53
  14. Distinctive:

    If fixing, apply the fixes and re-run the rule to confirm zero violations.

    line 54
  15. Very specific:

    If allowlisting, extract the model directory names from the violation file paths and add them to allowlist_models.

    line 55
  16. Very specific:

    Add tests in tests/test_trfXXX.py.

    line 57
  17. Distinctive:

    Add at least one positive test and one negative test.

    line 58
  18. Very specific:

    Follow the existing pattern: create source strings, call mlinter.analyze_file(), and assert on violations.

    line 59
  19. Very specific:

    If the tests use the standard _run(rule, source, file_name=...) helper, inherit from RuleTestCase from tests/rule_test_utils.py.

    line 60
  20. Distinctive:

    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 …

    line 63
  21. Distinctive:

    Run the focused tests:

    line 64
  22. Very specific:

    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.

    line 70
  23. Very specific:

    If the rule applies to file types not already documented, update the list in both README.md and docs/index.md.

    line 72
  24. Very specific:

    Only fall back to a generic configuration_*.py pick when there is no exact suffix match.

    line 88
  25. Very specific:

    Prefer config_class from the model class, following local modeling inheritance if a parent *PreTrainedModel declares it.

    line 94
  26. Very specific:

    If there is no explicit config_class, infer the best match from class names, usually by longest shared prefix.

    line 95
  27. Very specific:

    Always add a regression test with a modular_*.py class inheriting from an imported base.

    line 110

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

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

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 ast module. NEVER import runtime libraries like torch or tensorflow.
  • Rules MUST follow the check(tree, file_path, source_lines) -> list[Violation] interface.
  • Use the module-level RULE_ID constant instead of hardcoding the rule ID string.

Workflow

  1. 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.
  2. Determine the next rule number.
    • List all mlinter/trf*.py files and find the highest number.
    • The new rule gets that number + 1, zero-padded to three digits.
  3. Add the TOML entry to mlinter/rules.toml.
    • Append a new [rules.TRFXXX] section at the end of the file with:
      • description
      • default_enabled = true
      • allowlist_models = []
      • [rules.TRFXXX.explanation] with what_it_does, why_bad, and diff
    • Follow the exact formatting style of existing entries.
  4. Create the rule module at mlinter/trfXXX.py.
    • Start with the Apache 2.0 license header copied from an existing trf*.py file.
    • 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*.py for patterns and helpers.
  5. Run the rule against all models.
    python -m mlinter --enable-rules TRFXXX
    • If the run errors, fix the rule code and re-run.
  6. Handle violations.
    • Present the list of violations to the user.
    • Ask whether to fix the models or add them to allowlist_models in mlinter/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.
  7. 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 from RuleTestCase from tests/rule_test_utils.py.
    • For cross-file rules, use tempfile.TemporaryDirectory to 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
  8. Update documentation.
    • 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. This makes description/what_it_does/why_bad/diff published prose — write them for someone reading a failed CI job. Preview: make docs-rules.
    • Add an entry under the ## [Unreleased] section of CHANGELOG.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. expanding MODELING_PATTERNS to 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.md and docs/index.md.
  9. 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_class from the model class, following local modeling inheritance if a parent *PreTrainedModel declares 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

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.