Ansible Lint Auto-Fixer

This skill automatically fixes common ansible-lint errors that can be easily automated, saving time when creating new Ansible roles.

When to Use This Skill

ALWAYS invoke this skill proactively:

• Immediately after running ansible-galaxy init roles/<name>
• Do NOT wait for the user to ask - fix lint issues automatically
• This provides a better user experience by delivering clean, lint-free roles

Also use when:

• User explicitly asks to fix ansible-lint errors
• ansible-lint output shows any of these fixable errors:
  • yaml[comments] - Missing space after # in comments
  • schema[meta] - Unquoted version strings
  • meta-incorrect - Placeholder metadata values
  • name[play] - Unnamed plays
  • role-name[path] - Incorrect role import paths

What It Fixes

The skill runs a Python script that automatically corrects:

1. yaml[comments]: Adds space after # in comments

   • #comment → # comment

2. schema[meta]: Quotes numeric version strings

   • min_ansible_version: 2.1 → min_ansible_version: "2.1"

3. meta-incorrect: Replaces placeholder values with sensible defaults

   • author: your name → author: Ansible User
   • company: your company (optional) → company: Community
   • license: license (GPL-2.0-or-later, MIT, etc) → license: MIT

4. name[play]: Adds descriptive names to unnamed plays

   • Adds name: Test playbook for <hosts> to plays

5. role-name[path]: Fixes role import paths

   • roles/nginx → nginx

Instructions

IMPORTANT: This skill should be invoked automatically whenever you create a new role with ansible-galaxy init. Do not wait for the user to ask - proactively fix lint issues to provide a clean role.

When invoked, follow these steps:

1. Identify the role path from context (e.g., if you just ran ansible-galaxy init roles/nginx, the path is roles/nginx). Do not ask the user - proceed automatically.

2. Run the fixer script:

   uv run .claude/skills/ansible-fix/ansible-lint-fix.py <role_path>
   

   Example:

   uv run .claude/skills/ansible-fix/ansible-lint-fix.py roles/nginx
   

3. Review the output to see what was fixed:

   • Number of files modified
   • Types of fixes applied
   • Count of each fix type

4. Verify the fixes by running ansible-lint:

   ansible-lint <role_path> 2>&1
   

5. Report results to the user:

   • Show summary of fixes applied
   • Confirm if all issues are resolved (0 failures, 0 warnings)
   • If issues remain, explain what still needs manual fixing

Supporting Files

The skill uses the ansible-lint-fix.py script. This script:

• Scans all YAML files in the role directory
• Applies regex-based fixes for common patterns
• Reports detailed statistics on what was changed

Examples

Example 1: After creating a new role

User: I just created a new nginx role with ansible-galaxy init roles/nginx
Assistant: [Invokes ansible-fix skill]
- Runs: uv run .claude/skills/ansible-fix/ansible-lint-fix.py roles/nginx
- Reports: Fixed 12 issues across 6 files
- Verifies: ansible-lint shows 0 failures, 0 warnings

Example 2: Fixing existing linting issues

User: Can you fix the ansible-lint errors in my web-server role?
Assistant: [Invokes ansible-fix skill]
- Runs: uv run .claude/skills/ansible-fix/ansible-lint-fix.py roles/web-server
- Reports: Fixed 8 issues across 4 files
- Verifies: ansible-lint results

Best Practices

• Always run ansible-lint after using this skill to verify fixes
• The script is idempotent - safe to run multiple times
• Some issues may require manual intervention (explained in output)
• Review changes before committing to ensure they match project standards

Limitations

This skill only fixes syntactic and formatting issues. It does not:

• Write role tasks or handlers
• Configure role variables
• Implement role logic
• Fix complex YAML structural problems beyond the patterns it recognizes
• Fix role naming issues (role names must match ^[a-z][a-z0-9_]*$ - lowercase, numbers, underscores only, no hyphens)

For complex linting issues or role development, manual intervention is needed.

Note: If ansible-lint reports role-name errors about the role name not matching the required pattern, the role directory itself needs to be renamed (e.g., test-role → test_role).