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

The dart_skills_lint CLI provides --fix to preview proposed changes as a diff and --fix-apply to automatically correct violations in 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 untouched.
• --fix-apply: Applies fixes immediately. The tool writes the corrected content back to the 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:

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

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:

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:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}