/ansible-generator

name: ansible-generator
description: Generate, create, or scaffold Ansible playbooks, roles, tasks, handlers, inventory, vars.

Ansible Generator

Trigger Phrases

Use this skill when the request is to generate or scaffold Ansible content, for example:

• "Create a playbook to deploy nginx with TLS."
• "Generate an Ansible role for PostgreSQL backups."
• "Write inventory files for prod and staging."
• "Build reusable Ansible tasks for user provisioning."
• "Initialize an Ansible project with ansible.cfg and requirements.yml."
• "Give me a quick Ansible snippet to install Docker."

Do not use this skill as the primary workflow when the request is validation/debug-only (syntax errors, lint failures, Molecule/test failures). Use `ansible-validator` for those cases.

Deterministic Execution Flow

Run these stages in order. Do not skip a stage unless the `Validation Exceptions Matrix` explicitly allows it.

Stage 0: Classify Request Mode

Determine one mode first:

| Mode | Typical user intent | Deliverable | | --- | --- | --- | | `full-generation` | "create/build/generate" a full playbook/role/inventory/project file set | Complete file(s), production-ready | | `snippet-only` | "quick snippet/example" without full file context | Focused task/play snippet | | `docs-only` | explanation, pattern comparison, or conceptual guidance only | Explanatory content, optional examples |

Stage 1: Collect Minimum Inputs

If details are missing, ask briefly. If the user does not provide them, proceed with safe defaults and state assumptions.

| Resource type | Required inputs | Safe defaults if missing | | --- | --- | --- | | Playbook | target hosts, privilege (`become`), OS family, objective | `hosts: all`, `become: false`, OS-agnostic modules | | Role | role name, primary service/package, supported OS | role name from task domain, Debian + RedHat vars | | Tasks file | operation scope, required vars, execution context | standalone reusable tasks with documented vars | | Inventory | environments, host groups, hostnames/IPs | `production`/`staging` groups with placeholders | | Project config | collections/roles dependencies, lint policy | minimal `ansible.cfg`, `requirements.yml`, `.ansible-lint` |

Stage 2: Reference Extraction Checklist

Before drafting content, extract the following from local references/templates.

Required references

• `references/best-practices.md`
• Extract: FQCN requirements, idempotency rules, naming, security expectations.
• `references/module-patterns.md`
• Extract: correct module/parameter patterns for the exact task type.

Required templates by output type

• Playbook: `assets/templates/playbook/basic_playbook.yml`
• Role: `assets/templates/role/` (including `meta/argument_specs.yml` and `molecule/default/` for test scaffolding)
• Inventory (INI): `assets/templates/inventory/hosts`
• Inventory (YAML): `assets/templates/inventory/hosts.yml`
• Project config: `assets/templates/project/ansible.cfg`, `assets/templates/project/requirements.yml`, `assets/templates/project/.ansible-lint`

Extraction checks

• Identify every `[PLACEHOLDER]` that must be replaced.
• Decide module selection priority (`ansible.builtin.*` first).
• Capture at least one OS-appropriate package pattern when OS-specific behavior is needed.
• Capture required prerequisites (collections, binaries, target assumptions).

Stage 3: Generate

Apply these generation standards:

1. Use FQCN module names (`ansible.builtin.*` first choice). 2. Keep tasks idempotent (`state`, `creates/removes`, `changed_when` when needed). 3. Use descriptive verb-first task names. 4. Use `true`/`false` booleans (not `yes`/`no`). 5. Add `no_log: true` for sensitive values. 6. Replace all placeholders before presenting output. 7. Prefer `ansible.builtin.dnf` for RHEL 8+/CentOS 8+ (legacy `yum` only for older systems).

Stage 4: Validate (Default) or Apply Exception (Fallback)

Use the matrix below to keep validation deterministic and non-blocking.

Validation Exceptions Matrix

| Scenario | Default behavior | Allowed fallback | What to report | | --- | --- | --- | --- | | `full-generation` | Run `ansible-validator` after generation and after each fix pass | If validator/tools are unavailable, run manual static checks (YAML shape, placeholder scan, FQCN/idempotency/security review) and provide exact deferred validation commands | Explicitly list which checks ran, which were skipped, and why | | `snippet-only` | Skip full validator by default; do inline sanity checks | Run full validator only if user asks or snippet is promoted to full file | State that validation was limited because output is snippet-only | | `docs-only` | No runtime validation | None needed | State that no executable artifact was generated | | Offline environment (no web/docs access) | Continue with local references and templates | Skip external doc lookups; prefer builtin-module implementations; provide notes for later external verification | State offline constraint and impacted checks/lookups |

Resource Generation Guidance

Playbooks

• Use `assets/templates/playbook/basic_playbook.yml` as structure.
• Include: header comments, `pre_tasks`/`tasks`/`post_tasks` as needed, handlers, tags.
• Add health checks when service deployment/configuration is involved.

Roles

• Build from `assets/templates/role/` structure.
• Keep defaults in `defaults/main.yml`; keep higher-priority role vars in `vars/main.yml`.
• Include OS-specific vars (`vars/Debian.yml`, `vars/RedHat.yml`) when relevant.
• Add `meta/argument_specs.yml` for variable validation.
• Include `molecule/default/` scaffold (from `assets/templates/role/molecule/`) for production-ready roles.

Task Files

• Keep scope narrow and reusable.
• Document required input variables in comments.
• Use conditionals for environment/OS-sensitive operations.

Inventory

• Build logical host groups and optional group hierarchies.
• Use variable layering inte