ansible-fundamentals_skill

Overview

This skill codifies Ansible fundamentals for writing reliable, production-grade playbooks and tasks. It focuses on execution via uv run, using Fully Qualified Collection Names (FQCN), safe use of command/shell, and consistent naming and variable conventions. Follow these rules to produce idempotent, auditable, and maintainable automation.

How this skill works

The skill inspects playbook and task patterns and enforces golden rules: prefix all ansible CLI calls with uv run, prefer native modules using FQCNs, and add explicit changed_when/failed_when for ad-hoc commands. It guides module selection, collection installation, execution patterns, linting, and secret handling with no_log. It also prescribes task naming and variable naming conventions for clarity.

When to use it

• Writing new playbooks or tasks to ensure idempotency and clarity
• Choosing between ansible.builtin modules and command/shell invocations
• Running ansible-playbook, ansible-lint, or ansible-galaxy via uv run
• Installing or managing Ansible collections in requirements.yml
• Reviewing playbooks for secret exposure or poor error handling

Best practices

• Always run Ansible CLI commands with the uv run prefix (uv run ansible-playbook ...)
• Use Fully Qualified Collection Names (ansible.builtin.copy, ansible.posix.authorized_key)
• Prefer native modules for idempotency; use command/shell only when necessary
• For command/shell tasks, set changed_when and failed_when, and use no_log for secrets
• Include set -euo pipefail in shell scripts and shell module bodies
• Write descriptive task names starting with action verbs and use snake_case variables

Example use cases

• Install packages with ansible.builtin.apt/dnf while ensuring desired state
• Manage service state via ansible.builtin.systemd with clear restart behavior
• Run vendor CLIs (pvecm, pveceph, kubectl) using ansible.builtin.command with guards
• Install collections from requirements.yml using uv run ansible-galaxy collection install -r
• Lint and check playbooks with uv run ansible-lint and --syntax-check before CI