⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
add-mlinter-rule
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).
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
mlinter
A standalone linter for Hugging Face Transformers model
integration files — modeling_*.py, modular_*.py, configuration_*.py, processing_*.py,
image_processing_*.py, video_processing_*.py, feature_extraction_*.py,
tokenization_*.py and generation_*.py under src/transformers/models/, plus test_tokenization_*.py under
tests/models/. It enforces the
structural conventions that keep hundreds of model implementations consistent with each other.
📖 Documentation: https://huggingface.github.io/transformers-mlinter/
The docs site is generated from mlinter/rules.toml, so its
rule reference is always in step with the
installed rules.
Installation
pip install transformers-mlinter
When working on the transformers repo, mlinter is included in the quality extras:
pip install -e ".[quality]"
Quick start
Run from the root of a transformers checkout:
mlinter # check every model integration file
mlinter --changed-only --base-ref origin/main # only what you changed
mlinter --list-rules # list rules and their default state
mlinter --rule TRF001 # explain one rule
Pass a path to check code that lives outside a transformers checkout — a model repository shipped on
the Hub with trust_remote_code, for instance, which has to honour the same conventions:
mlinter ~/models/LLaDA-8B-Instruct # a directory, searched recursively
mlinter path/to/modeling_llada.py # or a single file
See the CLI reference for every flag, the Python API, and cache locations.
Documentation map
| Page | What's there |
|---|---|
| Home | What mlinter checks and why, installation, how rule registration works |
| Rules | All rules, filterable, one page each with examples and exemptions |
| CLI usage | Every flag, output formats, cache, Python API |
| Suppressing rules | # trf-ignore, whole-file directives, cutoff dates, allowlists |
| Contributing a rule | Adding a rule, the add-mlinter-rule skill, constraints on a rule |
| Releasing | The tag-driven release process |
Development
git clone https://github.com/huggingface/transformers-mlinter
cd transformers-mlinter
pip install -e ".[dev]"
make test # pytest under tests/
make lint # ruff check + format --check
make format # auto-fix style
make typecheck # ty on mlinter/
Building the docs site
The rule pages are generated and git-ignored. Building needs the Ruby toolchain once:
cd docs && bundle install && cd ..
make docs # regenerate rule pages, build the site, check internal links
make docs-serve # live preview on http://localhost:4000/transformers-mlinter/
License
Apache-2.0. See LICENSE.
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
.ai/skills/add-mlinter-rule/SKILL.md6.7 KBupstream ↗
--- name: add-mlinter-rule description: 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). --- # 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. ```bash 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: ```bash 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. ```bash 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`README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/huggingface-transformers-mlinter-ai-skills-add-mlinter-rule.md