# How to Use --fix and --fix-apply Flags for Automatic Lint Fixes in dart_skills_lint

> Learn to use dart_skills_lint --fix and --fix-apply flags to automatically fix linting violations in SKILL.md files. Preview changes before applying them for efficient code correction.

- Repository: [Flutter/skills](https://github.com/flutter/skills)
- Tags: how-to-guide
- Published: 2026-05-09

---

**The `dart_skills_lint` CLI provides `--fix` to preview proposed changes as a diff and `--fix-apply` to automatically correct violations in [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) files without manual editing.**

The `flutter/skills` repository ships `dart_skills_lint`, a command-line validator for skill metadata files. When the tool detects rule violations, it can execute **automatic lint fixes** directly from the command line, either in dry-run mode or by rewriting the source files in place.

## Understanding the --fix and --fix-apply Flags

The tool exposes two complementary flags that control how violations are resolved:

- **`--fix`**: Performs a dry-run. The tool calculates proposed fixes and prints a line-by-line diff to the console, but leaves the original [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) untouched.
- **`--fix-apply`**: Applies fixes immediately. The tool writes the corrected content back to the [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) file and then performs a second validation pass to verify the changes resolved all issues.

These flags are defined in `tool/dart_skills_lint/lib/src/entry_point.dart` at lines 30-32 and 75-78, where they are added to the `ArgParser` as boolean options.

## How Automatic Fixes Work Under the Hood

### CLI Flag Definitions in entry_point.dart

When you invoke the tool, `entry_point.dart` parses the command-line arguments. The flags are stored in local variables at lines 99-102:

```dart
final fix = results['fix'] as bool;
final fixApply = results['fix-apply'] as bool;

```

These booleans are then passed into `validateSkillsInternal`, which constructs a `ValidationSession` object.

### Session Initialization and Validation Flow

The `ValidationSession` class, located in `tool/dart_skills_lint/lib/src/validation_session.dart`, stores the flag values as immutable fields at lines 60-68. When validation completes, the session checks whether either flag is enabled before proceeding to the fixer logic.

### The Fix Application Logic

Inside `_applyFixesIfNeeded` (lines 403-405), the session returns early if neither flag is set. Otherwise, it iterates over every `FixableRule` that reported errors:

1. **Generate fixes**: The rule’s `fix` method returns the proposed new content for the file.
2. **Apply or display**: 
   - If `--fix-apply` is true, the content is written to [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) and the validator reruns to confirm success.
   - If only `--fix` is true, the session calls `_printDiff` (lines 455-460) to display changes using a simple line-index comparison algorithm.

The diff algorithm compares lines at the same index, which is sufficient for the current fixers that modify existing lines in place.

## Practical Usage Examples

### Preview Changes Without Writing Files

Use `--fix` to see exactly what would change before committing:

```bash
dart run dart_skills_lint --skills-directory ./my_skills --fix

```

This outputs a diff showing line-by-line changes, such as:

```

  [Dry Run] Proposed changes for my-awesome-skill (SKILL.md):
- Line 12: description: "Old description   "
+ Line 12: description: "Updated description"

```

### Apply Fixes Automatically

Use `--fix-apply` to rewrite the files and validate the corrections:

```bash
dart run dart_skills_lint --skill ./my_skills/cool_skill --fix-apply

```

The tool prints a confirmation message and reruns validation to ensure the skill is now valid.

### Combine With Other Flags

You can use either flag alongside other options like `--quiet` or `--check-relative-paths`:

```bash
dart run dart_skills_lint \
  -s ./my_skills/cool_skill \
  --fix-apply \
  --quiet \
  --check-relative-paths

```

## Summary

- The `--fix` flag performs a dry-run, printing a diff via `_printDiff` in `validation_session.dart` without modifying files.
- The `--fix-apply` flag writes corrections directly to [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) and reruns validation to confirm fixes.
- Both flags are parsed in `entry_point.dart` and stored in `ValidationSession`, which delegates to rule-specific `FixableRule` implementations.
- The diff algorithm is line-index based and works for rules that modify existing lines.

## Frequently Asked Questions

### What is the difference between --fix and --fix-apply?

The `--fix` flag shows a preview of changes as a console diff without touching your files, while `--fix-apply` actually rewrites the [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) file with the corrected content and reruns the validator to verify the fixes worked.

### Which lint rules support automatic fixing?

Any rule that implements the `FixableRule` interface supports automatic fixes. The specific fix logic resides in each rule’s `fix` method, such as those found in `tool/dart_skills_lint/lib/src/rules/trailing_whitespace_rule.dart`.

### Is it safe to run --fix-apply in CI/CD pipelines?

Running `--fix-apply` in CI is generally not recommended because the tool modifies source files in place. Use `--fix` instead to detect violations and fail the build if issues exist, or apply fixes locally and commit the corrected files.

### How does the diff output format work?

The diff compares original and proposed file content line-by-line at matching indices. As implemented in `validation_session.dart` lines 54-60 and 455-460, it prints removed lines with `-` and added lines with `+`, prefixed with line numbers for easy reference.