Auto-fix

claudelint can automatically fix certain validation issues.

Overview

Auto-fix capability allows you to:

Preview fixes before applying them (--fix-dry-run)
Automatically resolve fixable issues (--fix)
Choose which severity levels to fix (--fix-type)
See unified diffs of proposed changes

Safety: Auto-fix uses atomic file writes and can be previewed before applying.

Usage

Preview Fixes

See what would be fixed without modifying files:

bash

claudelint check-all --fix-dry-run

Output:

text

 Previewing 3 fixes...

Proposed changes:
Index: .claude/skills/my-skill/test.sh
===================================================================
--- .claude/skills/my-skill/test.sh original
+++ .claude/skills/my-skill/test.sh fixed
@@ -1,1 +1,2 @@
+#!/usr/bin/env bash
 echo "Hello"

✓ 3 fixes would be applied to 3 files

Apply Fixes

Automatically fix all fixable issues:

bash

claudelint check-all --fix

Output:

text

 Applying 3 fixes...

✓ 3 fixes applied to 3 files

 Run validation again to check for remaining issues

Fix Specific Types

Fix only errors, warnings, or all issues:

bash

# Fix only errors
claudelint check-all --fix --fix-type errors

# Fix only warnings
claudelint check-all --fix --fix-type warnings

# Fix all (default)
claudelint check-all --fix --fix-type all

Fixable Rules

Skills

skill-missing-shebang (warning, fixable)

Adds #!/usr/bin/env bash as the first line of shell scripts.

Before:

bash

echo "Hello"

After:

bash

#!/usr/bin/env bash
echo "Hello"

skill-missing-version (warning, fixable)

Adds version: "1.0.0" to SKILL.md frontmatter.

Before:

markdown

---
name: my-skill
description: A test skill
---

After:

markdown

---
name: my-skill
description: A test skill
version: '1.0.0'
---

skill-missing-changelog (warning, fixable)

Creates CHANGELOG.md with Keep a Changelog template.

skill-shell-script-no-error-handling (warning, fixable)

Adds set -euo pipefail to shell scripts that lack error handling.

skill-reference-not-linked (warning, fixable)

Converts backtick file references (e.g., `scripts/deploy.sh`) into markdown links.

skill-name-directory-mismatch (error, fixable)

Updates the name field in SKILL.md frontmatter to match the parent directory name.

Plugin

plugin-missing-component-paths (warning, fixable)

Adds ./ prefix to component paths that should be explicit about their location.

Run claudelint list-rules --fixable to see all fixable rules.

Common Workflows

Safe Workflow

Preview fixes to see what will change:
bash
```
claudelint check-all --fix-dry-run
```
Review the proposed changes
Apply fixes if changes look correct:
bash
```
claudelint check-all --fix
```
Validate again to check for remaining issues:
bash
```
claudelint check-all
```

Commit the auto-fixed files:

bash

git add .
git commit -m "fix: auto-fix validation issues"

CI/CD Integration

yaml

# .github/workflows/lint.yml
name: Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
      - run: npm install -g claude-code-lint

      # Validate and auto-fix
      - run: claudelint check-all --fix

      # Commit fixes (optional)
      - uses: stefanzweifel/git-auto-commit-action@v7
        with:
          commit_message: 'fix: auto-fix linting issues'

Pre-commit Hook

bash

#!/bin/bash
# .git/hooks/pre-commit

# Auto-fix issues before committing
claudelint check-all --fix

# Re-stage fixed files
git add -u

# Run validation
claudelint check-all

How Auto-fix Works

Validation runs all validators and collects fixable issues
Collection gathers all autoFix objects from errors and warnings
Application applies fixes to files:
- Reads current file content
- Applies fix function
- Writes updated content atomically
Reporting shows results with file counts and diffs

Safety Features

Atomic Writes

Files are written atomically - if an error occurs, the file remains unchanged.

Dry-run Mode

Preview changes without modifying files:

bash

claudelint check-all --fix-dry-run

Unified Diffs

See exactly what will change in a standard diff format.

No Backup Files

Auto-fix does not create .bak files. Use version control (git) for safety:

bash

# Before fixing
git status  # Check for uncommitted changes
git stash   # Stash changes if needed

# Apply fixes
claudelint check-all --fix

# Review changes
git diff

# Revert if needed
git checkout .

Limitations

Not All Rules Are Fixable

Some issues require human judgment:

skill-missing-comments - Requires understanding script purpose
skill-missing-examples - Requires understanding skill usage
import-circular - Requires restructuring imports

Use claudelint list-rules --fixable to see which rules support auto-fix.

Caching Disabled with --fix

Auto-fix disables caching to preserve fix functions (functions can't be serialized to JSON).

This means validation runs slower with --fix, but ensures fixes work correctly.

Sequential Fixes

Fixes are applied sequentially to each file. If multiple fixes modify the same line, later fixes see the result of earlier fixes.

Troubleshooting

Fixes Not Applied

Problem: --fix runs but files aren't modified

Solutions:

Check file permissions:
bash
```
ls -l .claude/skills/my-skill/
```
Verify files aren't read-only
Use --fix-dry-run to see if fixes are detected

Fixes Failed

Problem: "N fixes failed" message appears

Causes:

File doesn't exist (for file creation fixes)
Invalid file content (can't parse frontmatter)
Permission denied

Solution:

Run with --verbose to see detailed error messages.

Changes Look Wrong

Problem: Auto-fix makes unexpected changes

Solution:

Use --fix-dry-run first to preview
Review diffs carefully
Use version control to revert:
bash
```
git checkout .
```

Report issue if fix is incorrect:

bash

# Include:
# - Original file content
# - Expected fix
# - Actual fix (from --fix-dry-run)

No Fixable Issues Found

Problem: "No auto-fixable issues found" despite validation errors

Explanation:

Not all rules support auto-fix. Only mechanical changes that don't require context can be auto-fixed.

Solution:

Fix remaining issues manually based on error messages.

Best Practices

Use Dry-run First

Always preview changes before applying:

bash

claudelint check-all --fix-dry-run | less

Commit Before Fixing

Ensure you can revert if needed:

bash

git status
# Commit or stash changes first
claudelint check-all --fix

Fix in Batches

Fix one type at a time for easier review:

bash

claudelint check-all --fix --fix-type warnings
git diff
git add -p  # Review each change

Validate After Fixing

Always run validation again:

bash

claudelint check-all --fix
claudelint check-all  # Verify all issues resolved

Review Auto-fixes in PRs

When auto-fixes are applied in CI:

Review the changes in the PR
Ensure fixes are correct
Don't blindly merge auto-fix commits

Auto-fix ​

Overview ​

Usage ​

Preview Fixes ​

Apply Fixes ​

Fix Specific Types ​

Fixable Rules ​

Skills ​

Plugin ​

Common Workflows ​

Safe Workflow ​

CI/CD Integration ​

Pre-commit Hook ​

How Auto-fix Works ​

Safety Features ​

Atomic Writes ​

Dry-run Mode ​

Unified Diffs ​

No Backup Files ​

Limitations ​

Not All Rules Are Fixable ​

Caching Disabled with --fix ​

Sequential Fixes ​

Troubleshooting ​

Fixes Not Applied ​

Fixes Failed ​

Changes Look Wrong ​

No Fixable Issues Found ​

Best Practices ​

Use Dry-run First ​

Commit Before Fixing ​

Fix in Batches ​

Validate After Fixing ​

Review Auto-fixes in PRs ​

See Also ​

Auto-fix

Overview

Usage

Preview Fixes

Apply Fixes

Fix Specific Types

Fixable Rules

Skills

Plugin

Common Workflows

Safe Workflow

CI/CD Integration

Pre-commit Hook

How Auto-fix Works

Safety Features

Atomic Writes

Dry-run Mode

Unified Diffs

No Backup Files

Limitations

Not All Rules Are Fixable

Caching Disabled with --fix

Sequential Fixes

Troubleshooting

Fixes Not Applied

Fixes Failed

Changes Look Wrong

No Fixable Issues Found

Best Practices

Use Dry-run First

Commit Before Fixing

Fix in Batches

Validate After Fixing

Review Auto-fixes in PRs

See Also