# add-mlinter-rule

Adopt this skill: https://proskills.md/skills/other/huggingface-transformers-mlinter-ai-skills-add-mlinter-rule

Page: https://proskills.md/skills/other/huggingface-transformers-mlinter-ai-skills-add-mlinter-rule
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .ai/skills/add-mlinter-rule/SKILL.md
size: 6876
upstream: https://github.com/huggingface/transformers-mlinter/blob/main/.ai/skills/add-mlinter-rule/SKILL.md

````text
---
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`
````

## File: README.md
upstream: https://github.com/huggingface/transformers-mlinter/blob/main/README.md

````text
<!-- Absolute URL on purpose: this README is also the PyPI long_description, and PyPI does not resolve
     repo-relative image paths. -->
<p align="center">
  <img src="https://raw.githubusercontent.com/huggingface/transformers-mlinter/main/docs/assets/images/mlinter-logo.png"
       alt="mlinter" width="360">
</p>

# mlinter

A standalone linter for [Hugging Face Transformers](https://github.com/huggingface/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](https://huggingface.github.io/transformers-mlinter/rules/) is always in step with the
installed rules.

## Installation

```bash
pip install transformers-mlinter
```

When working on the transformers repo, mlinter is included in the `quality` extras:

```bash
pip install -e ".[quality]"
```

## Quick start

Run from the root of a transformers checkout:

```bash
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:

```bash
mlinter ~/models/LLaDA-8B-Instruct          # a directory, searched recursively
mlinter path/to/modeling_llada.py           # or a single file
```

See the [CLI reference](https://huggingface.github.io/transformers-mlinter/usage/) for every flag, the
Python API, and cache locations.

## Documentation map

| Page | What's there |
|:-----|:-------------|
| [Home](https://huggingface.github.io/transformers-mlinter/) | What mlinter checks and why, installation, how rule registration works |
| [Rules](https://huggingface.github.io/transformers-mlinter/rules/) | All rules, filterable, one page each with examples and exemptions |
| [CLI usage](https://huggingface.github.io/transformers-mlinter/usage/) | Every flag, output formats, cache, Python API |
| [Suppressing rules](https://huggingface.github.io/transformers-mlinter/suppressing/) | `# trf-ignore`, whole-file directives, cutoff dates, allowlists |
| [Contributing a rule](https://huggingface.github.io/transformers-mlinter/contributing/) | Adding a rule, the `add-mlinter-rule` skill, constraints on a rule |
| [Releasing](https://huggingface.github.io/transformers-mlinter/release/) | The tag-driven release process |

## Development

```bash
git clone https://github.com/huggingface/transformers-mlinter
cd transformers-mlinter
pip install -e ".[dev]"
```

```bash
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:

```bash
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](LICENSE).
````
