SKILL.md for Ansible project in Codex

C:\Users\zdudic\.codex\skills\Ansible\SKILL.md

---
name: Ansible
description: Use for general Ansible playbook, role, inventory, linting, and compatibility work.
---

# Ansible General Skill

## Research existing solutions first

For non-trivial tasks or unfamiliar problems, check official documentation and relevant GitHub roles, code, issues and discussions before designing custom logic.

- Review how existing solutions work and whether they fit the project's Ansible versions, operating systems, idempotence, check mode and error handling.
- Share useful findings and source links with Zarko. Explain the benefits, limitations and proposed adaptation, then discuss the approach before implementing.
- Do not copy blindly. Adapt only what is needed, preserving the existing role's simplicity and coding style.
- If no suitable solution is found, say so and explain the proposed custom approach.

## Role README.md

Preserve the README.md layout generated by `ansible-galaxy` and Zarko's edits.
Keep existing headings and section order; write brief role-specific content
within those sections. Add Behavior section if it's needed.

## Role directories and examples

Before finishing, verify all required role directories exist, example is `vars` .

Always provide:
- `vars/hostname=fqdn.yml`
- `vars/project=example.yml`

Both files must contain valid Ansible YAML examples tailored to the role,
using its actual variables and configuration format, consistent with its
defaults and tasks.

## Gathered facts

- Access gathered facts through `ansible_facts[...]`.
- Do not rely on injected top-level facts such as:
  - `ansible_pkg_mgr`
  - `ansible_distribution`
  - `ansible_distribution_major_version`
  - `ansible_os_family`
  - `ansible_hostname`
  - `ansible_python_version`
- Use forms such as:
  - `ansible_facts['pkg_mgr']`
  - `ansible_facts['distribution']`
  - `ansible_facts['distribution_major_version']`
  - `ansible_facts['os_family']`
  - `ansible_facts['hostname']`
  - `ansible_facts['python_version']`
- Assume `INJECT_FACTS_AS_VARS` may be disabled.
- Do not create custom variables with the reserved `ansible_` prefix.

## Implementation

- Do not over engineer, simplicity is great.
- Prefer idempotent, purpose-built `ansible.builtin` or installed collection modules.
- Use `raw`, `shell`, or `command` only when no appropriate module is available.
- If several related tasks share the same `when` condition, group them in a block when doing so improves readability and preserves execution logic.
- When using those modules, explain why they are necessary and handle change reporting and check mode appropriately.
- Follow the repository's existing YAML and module naming conventions.

## Supported distributions and minimum major versions

Do not add an upper version limit unless explicitly required.

### In defaults/main.yml

This is example for supporting Oracle Linux 7 and newer. 

```
role_name_distro_ok:
  - { role_name_distro: "OracleLinux", role_name_min_ver: 7 }
```

### In tasks/main.yml

Use this pattern for roles with a distro_ok support list, especially when several distributions are supported.
Check the whole list before reporting an unsupported host: one nonmatching entry does not mean the host is unsupported.
Include the role tasks once when any entry matches.

```
---
- name: Initialize distro support result
  ansible.builtin.set_fact:
    role_name_distro_supported: false

- name: Check supported distro and minimum major version
  when:
    - ansible_facts['distribution'] == os.role_name_distro
    - ansible_facts['distribution_major_version'] is version(os.role_name_min_ver, '>=')
  ansible.builtin.set_fact:
    role_name_distro_supported: true
  loop: "{{ role_name_distro_ok }}"
  loop_control:
    loop_var: os

- name: Report unsupported distro and version
  when: not role_name_distro_supported
  ansible.builtin.debug:
    msg: "{{ ansible_facts['distribution'] }} {{ ansible_facts['distribution_major_version'] }} not supported by role."

- name: Include role tasks
  when: role_name_distro_supported
  ansible.builtin.include_tasks: analysis.yml
...
```

## Review

- Inspect changed files for injected top-level gathered facts.
- Convert only confirmed gathered facts to `ansible_facts[...]`.
- Leave magic, connection, inventory, and user-defined variables unchanged.
- Preserve each file's existing line endings.
- Do not normalize or convert CRLF/LF.
- If a diff shows the whole file changed only because of line-ending
  conversion, restore its original line endings and keep only the intended
  content changes.

## Validation

Follow the active workspace `AGENTS.md` for supported Ansible versions,
controller paths, lint commands, test commands, inventories, and Git
authorization boundaries.